Crate macrotest

  Test harness for macro expansion.

Similar to trybuild, but allows you to write tests on how macros are expanded.

Minimal Supported Rust Version: 1.66

Macro expansion tests

A minimal macrotest setup looks like this:

#[test]
pub fn pass() {
    macrotest::expand("tests/expand/*.rs");
    // Alternatively,
    macrotest::expand_without_refresh("tests/expand/*.rs");
}

The test can be run with cargo test. This test will invoke the cargo expand command on each of the source files that matches the glob pattern and will compare the expansion result with the corresponding *.expanded.rs file.

If a *.expanded.rs file doesn’t exists and it’s not explicitly expected to (see expand_without_refresh), it will be created (this is how you update your tests).

Possible test outcomes are:

• Pass: expansion succeeded and the result is the same as in the .expanded.rs file
• Fail: expansion was different from the .expanded.rs file content
• Refresh: .expanded.rs didn’t exist and has been created
• Refresh-fail: .expanded.rs is expected to be present, but not exists. See expand_without_refresh.

Note: when working with multiple expansion test files, it is recommended to specify wildcard (*.rs) instead of doing a multiple calls to expand functions for individual files. Usage of wildcards for multiple files will group them under a single temporary crate for which dependencies will be built a single time. In contrast, calling expand functions for each source file will create multiple temporary crates and that will reduce performance as depdendencies will be build for each of the temporary crates.

Passing additional arguments to cargo expand

It’s possible to specify additional arguments for cargo expand command.

In order to do so, use the following functions with _args suffix:

• expand_args
• expand_without_refresh_args

Example:

pub fn pass() {
    macrotest::expand_args("tests/expand/*.rs", &["--features", "my-feature"]);
    // Or
    macrotest::expand_without_refresh_args("tests/expand/*.rs", &["--features", "my-feature"]);
}

The _args functions will result in the following cargo expand command being run:

cargo expand --bin <test-name> --theme none --features my-feature

Workflow

First of all, the cargo expand tool must be present. You can install it via cargo:

cargo install --locked cargo-expand

(In CI, you’ll want to pin to a particular version, since cargo expand’s output is not stable across versions. Look up the current version and do something like cargo install --locked --version 1.0.81 cargo-expand.)

Setting up a test project

In your crate that provides procedural or declarative macros, under the tests directory, create an expand directory and populate it with different expansion test cases as rust source files.

Then create a tests.rs file that will run the tests:

#[test]
pub fn pass() {
    macrotest::expand("tests/expand/*.rs");
    // Or:
    macrotest::expand_without_refresh("tests/expand/*.rs");
}

And then you can run cargo test, which will

1. Expand macros in source files that match glob pattern
2. In case if expand function is used:
   • On the first run, generate the *.expanded.rs files for each of the test cases under the expand directory
   • On subsequent runs, compare test cases’ expansion result with the content of the respective *.expanded.rs files
3. In case if expand_without_refresh is used:
   • On each run, it will compare test cases’ expansion result with the content of the respective *.expanded.rs files.
   • If one or more *.expanded.rs files is not found, the test will fail.

Updating .expanded.rs

This applicable only to tests that are using expand or expand_args function.

Run tests with the environment variable MACROTEST=overwrite or remove the *.expanded.rs files and re-run the corresponding tests. Files will be created automatically; hand-writing them is not recommended.

Functions

expand

Attempts to expand macros in files that match glob pattern.

expand_args

Same as expand but allows to pass additional arguments to cargo-expand.

expand_without_refresh

Attempts to expand macros in files that match glob pattern. More strict version of expand function.

expand_without_refresh_args

Same as expand_without_refresh but allows to pass additional arguments to cargo-expand.