How do you test a Rust attribute macro such as `#[route]`, including its compile errors, when `proc_macro` APIs panic outside a macro?
answer
- proc_macro only inside rustc
- logic on proc_macro2 types
- compile-fail ui tests
- snapshot the stderr
- look at the expansion
basics
~20 sWrite the transformation over proc_macro2 types and unit-test it with syn::parse2, check behaviour and error messages with trybuild's pass and compile_fail cases against .stderr snapshots, and inspect the generated code with cargo expand or nightly -Zunpretty=expanded.
solid answer
~40 s`proc_macro`'s API needs rustc's macro bridge, so parsing a `proc_macro::TokenStream` in a `#[test]` panics with `procedural macro API is used outside of a procedural macro`. Keep the `#[proc_macro_attribute]` function as a thin wrapper that converts to `proc_macro2::TokenStream` and calls `expand_route(...)`, which unit tests drive with `quote!` input and `syn::parse2`. For the user's view, **trybuild** compiles each test file you register: `pass` cases must compile and run without panicking, and `compile_fail` cases must fail with output matching an adjacent `.stderr` file. A missing snapshot is written to `wip/` and fails the test. `TRYBUILD=overwrite` rewrites snapshots in place for review in the diff. To read the expansion itself, use the third-party `cargo expand` or nightly `-Zunpretty=expanded`.
code
rust · 32 lines#[proc_macro_attribute]
pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream {
expand_route(attr.into(), item.into())
.unwrap_or_else(syn::Error::into_compile_error)
.into()
}
// The logic lives on proc_macro2 types, so a plain #[test] can call it.
fn expand_route(
attr: proc_macro2::TokenStream,
item: proc_macro2::TokenStream,
) -> syn::Result<proc_macro2::TokenStream> {
let args: RouteArgs = syn::parse2(attr)?;
let handler: ItemFn = syn::parse2(item)?;
let reg = format_ident!("{}_route", handler.sig.ident);
let (name, method, path) = (&handler.sig.ident, args.method.to_string(), &args.path);
Ok(quote! {
#handler
pub fn #reg() -> (&'static str, &'static str, fn() -> String) { (#method, #path, #name) }
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_missing_method() {
let err = expand_route(quote!("/users"), quote!(fn f() -> String { String::new() })).unwrap_err();
assert_eq!(err.to_string(), "expected identifier");
}
}go deeper
Recall that macro errors are tested by compiling small example files and comparing the compiler's messages, and that the expansion can be printed to read it.
Explain why proc_macro panics outside the compiler and how a proc_macro2 wrapper makes the logic unit-testable.
Build the layered suite: parser unit tests, trybuild pass and compile-fail cases with reviewed snapshots, and expansion inspection when a test fails for an unclear reason.
Make diagnostics a tested contract, with one snapshot per promised error and a pinned toolchain, so macro users can rely on its messages as on its API.
## Why ordinary unit tests do not work directly A procedural macro runs inside the compiler. The types in the compiler-provided `proc_macro` crate are handles into rustc, and the crate's own documentation says it is "only intended for use inside the implementation of procedural macros." Run a `#[test]` that parses a string into `proc_macro::TokenStream` and it panics with `procedural macro API is used outside of a procedural macro`. `proc_macro::is_available()`, stable since 1.57, returns `false` there. It lets shared code detect the situation without panicking. The fix is a **thin wrapper**. The **proc-macro2** crate mirrors the `proc_macro` API and falls back to its own implementation outside a macro. Its documentation names "make procedural macros unit testable" as one of its two purposes. syn and quote are built on it. 1. The `#[proc_macro_attribute] fn route` converts both streams with `.into()` and calls `expand_route`. 2. `expand_route(attr: proc_macro2::TokenStream, item: proc_macro2::TokenStream) -> syn::Result<proc_macro2::TokenStream>` holds all the logic and parses with `syn::parse2`. 3. Errors come back as `syn::Error`, and the wrapper turns them into `compile_error!` with `into_compile_error`. Returning `syn::Result` also keeps error handling in one place. Every `?` inside the core turns a parse failure into a spanned error, and the wrapper is the only spot that turns it into tokens. Unit tests then build input with `quote!(GET, "/users")`, call `expand_route`, and assert on the result. They can check that the output parses back as a `syn::File` with two items, or that the error message is `expected identifier`. ## Testing what the user sees with trybuild Unit tests check the transformation. They do not prove that the expanded code compiles in a real crate, or that the user gets a readable error. **trybuild** is a test harness that runs rustc on a set of test files: - `TestCases::new()` creates the runner. `pass(path)` expects the file to compile and its `main` to run without panicking. `compile_fail(path)` expects compilation to fail. - For each compile-fail file, the compiler's output must match an adjacent **`.stderr`** file with the same name. - If the `.stderr` file does not exist yet, trybuild writes the actual output to a `wip/` directory beside `Cargo.toml` and fails the test. You review the file and move it into `tests/ui/`. - Running with `TRYBUILD=overwrite` writes the output straight into place. Review the `git diff` afterwards. - Dev-dependencies of the crate are available inside the test files. trybuild compiles each file as its own crate depending on yours, which matters because a procedural macro cannot be used in the crate that defines it. Good compile-fail cases test **your** diagnostics: a missing method in `#[route("/users")]`, an unknown argument, the attribute on a `struct`. trybuild's own documentation advises against compile-fail tests that merely call public APIs with arguments of the wrong type, because they add nothing. Snapshots contain rustc's wording, which can change between releases. Run them on one pinned toolchain in CI, and expect to re-bless them when the toolchain moves. ## Looking at the expansion When a test fails and you cannot see why, read the generated code: | Tool | Toolchain | What you get | |---|---|---| | `cargo expand` | third-party subcommand | the crate's source with every macro expanded | | `cargo rustc -- -Zunpretty=expanded` | nightly only | the same, straight from rustc | | `eprintln!("{item}")` inside the macro | any | the raw streams, printed during the build | Stable rustc rejects the `-Z` flag with `the option `Z` is only accepted on the nightly compiler`. Printing the streams from inside the macro works anywhere, because a macro has the compiler's standard error. ## What a complete suite looks like - Unit tests on `expand_route` for every branch of the parser and every error message. - trybuild `pass` cases exercising real handlers, including generics and attributes the macro must carry through. - trybuild `compile_fail` cases with reviewed `.stderr` snapshots, one per diagnostic you promise, including the attribute placed on the wrong kind of item, such as a `struct`. - A pinned toolchain in CI, so snapshot changes arrive with a deliberate upgrade rather than at random. - The expansion inspected once by hand whenever the generated code changes shape.
- Your trybuild suite starts failing after a toolchain upgrade, with no change to the macro. What happened, and what do you do?The `.stderr` snapshots contain rustc's own wording and layout, which can change between releases. Re-run with `TRYBUILD=overwrite`, read the diff, and accept it if only the compiler's phrasing moved. If your macro's error moved to a different span or disappeared, that is a regression in the macro. Pinning the toolchain in CI makes these updates deliberate.
- Why does a trybuild `pass` case add anything over the unit test that the output parses?Parsing back as a `syn::File` proves only that the output is syntactically valid. A pass case compiles the expansion inside a real crate, so name resolution, types and borrows are checked, and then it runs `main`. Unhygienic paths, missing imports and wrong types show up only there.
- You can call `proc_macro::TokenStream` parsing from a normal #[test] in the macro crate
- A trybuild compile-fail case passes as long as compilation fails for any reason
- A missing .stderr snapshot makes trybuild accept whatever the compiler printed
- `-Zunpretty=expanded` works on the stable compiler
- Testing that the output parses proves the expansion compiles