Crate rb_sys_test_helpers

rb-sys-test-helpers

Helpers for testing Ruby extensions from Rust

Usage

Add this to your Cargo.toml:

[dev-dependencies]
rb-sys-env = { version = "0.1" }
rb-sys-test-helpers = { version = "0.2" }

Then, in your crate’s build.rs:

pub fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _ = rb_sys_env::activate()?;

    Ok(())
}

Then, you can use the with_ruby_vm function in your tests:

#[cfg(test)]
mod tests {
    use rb_sys_test_helpers::ruby_test;
    use rb_sys::{rb_num2fix, rb_int2big, FIXNUM_P};

    #[ruby_test]
    fn test_something() {
        // Your test code here will have a valid Ruby VM (hint: this works with
        // the `magnus` crate, too!)
        //
        // ...

        let int = unsafe { rb_num2fix(1) };
        let big = unsafe { rb_int2big(9999999) };

        assert!(FIXNUM_P(int));
        assert!(!FIXNUM_P(big));
    }
}

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Macros

• capture_gc_stat_for
  Captures the GC stat before and after the expression.
• eval
  Evaluates a Ruby expression.
• memoized
  Memoizes the result rb_sys::VALUE of the given expression.
• rb_funcall_typed
  This is a macro that allows you to call a method on a Ruby object, and get an Option back. If the type matches, it will return Some, otherwise it will return None.
• rstring
  Creates a new Ruby string from a Rust string.
• rstring_to_string
  Allows you to convert a Ruby string to a Rust string.
• rsymbol
  Creates a new Ruby symbol from a Rust literal str.
• trigger_full_gc
  Runs the garbage collector 10 times to ensure that we have a clean slate.

Structs

• RubyException
  A simple wrapper around a Ruby exception that provides some convenience methods for testing.

Functions

• cleanup_ruby^⚠
  Cleanup the Ruby VM.
• protect
  Catches a Ruby exception and returns it as a Result (using rb_sys::rb_protect).
• setup_ruby^⚠
  Setup the Ruby VM and return a guard that will cleanup the VM when dropped.
• setup_ruby_unguarded^⚠
  Setup the Ruby VM, without cleaning up afterwards.
• with_gc_stress
  Runs a test with GC stress enabled to help find GC bugs.
• with_ruby_vm
  Run a given function with inside of a Ruby VM.

Attribute Macros

• ruby_test
  A proc-macro which generates a #[test] function has access to a valid Ruby VM.