### Add Macrotest and Cargo Expand to Dev Dependencies

Source: https://context7.com/eupn/macrotest/llms.txt

Add `macrotest` as a development dependency in your `Cargo.toml`. Install `cargo-expand` globally or pin its version for reproducible CI builds.

```toml
# Cargo.toml
[dev-dependencies]
macrotest = "1"
```

```bash
# Install cargo-expand (pin the version in CI for reproducibility)
cargo install --locked --version 1.0.81 cargo-expand
```

--------------------------------

### Testing Declarative Macro Expansion

Source: https://context7.com/eupn/macrotest/llms.txt

An example test file that uses the `test_vec!` macro and is intended to be expanded by `cargo expand` for testing purposes. It requires the `my_crate` crate to be available.

```rust
#[macro_use]
extern crate my_crate;

pub fn main() {
    test_vec![];
}
```

--------------------------------

### Pinning cargo-expand Version

Source: https://context7.com/eupn/macrotest/llms.txt

Installs a specific, locked version of `cargo-expand` to ensure consistent snapshot generation across different CI environments and prevent unexpected changes.

```bash
cargo install --locked --version 1.0.81 cargo-expand
```

--------------------------------

### Basic macro expansion test

Source: https://github.com/eupn/macrotest/blob/master/README.md

Create a test function in your `tests/` directory to run macro expansion tests. The `macrotest::expand` function takes a path to a directory containing `.rs` files, where each file is a test case.

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

--------------------------------

### Individual File Expansion (Less Efficient)

Source: https://context7.com/eupn/macrotest/llms.txt

Demonstrates testing individual files by calling `macrotest::expand` multiple times. This approach leads to slower build times as each file is processed in a separate temporary crate.

```rust
#[test]
pub fn slow_approach() {
    macrotest::expand("tests/expand/first.rs");
    macrotest::expand("tests/expand/second.rs"); // separate crate build!
}
```

--------------------------------

### Glob Pattern for Macro Expansion Tests

Source: https://context7.com/eupn/macrotest/llms.txt

Uses a glob pattern to include all `.rs` files in the `tests/expand/` directory for a single macrotest expansion. This is the recommended approach for efficiency.

```rust
#[test]
pub fn all_expansions() {
    macrotest::expand("tests/expand/*.rs");
}
```

--------------------------------

### Run Macro Expansion Tests with Auto-Refresh

Source: https://context7.com/eupn/macrotest/llms.txt

Use `macrotest::expand` to run tests on `.rs` files matching a glob pattern. It automatically creates or updates `.expanded.rs` snapshot files if they don't exist. Panics if existing snapshots do not match the live expansion.

```rust
// tests/tests.rs
#[test]
pub fn pass() {
    // Expands every .rs file under tests/expand/ and compares/creates .expanded.rs snapshots.
    macrotest::expand("tests/expand/*.rs");
}
```

--------------------------------

### macrotest::expand

Source: https://context7.com/eupn/macrotest/llms.txt

Runs macro expansion tests for files matching a glob pattern. If no `.expanded.rs` file exists, it is created automatically. The test fails if an existing snapshot does not match the live expansion output.

```APIDOC
## macrotest::expand

### Description
Runs macro expansion tests for all `.rs` files matching the given glob pattern and compares each result against a corresponding `.expanded.rs` file. If no `.expanded.rs` file exists yet, it is created automatically (snapshot refresh). The test panics if an existing snapshot does not match the live expansion output.

### Usage
```rust
// tests/tests.rs
#[test]
pub fn pass() {
    // Expands every .rs file under tests/expand/ and compares/creates .expanded.rs snapshots.
    macrotest::expand("tests/expand/*.rs");
}
```

### Directory Layout Example
```
# Directory layout after first run:
tests/
  expand/
    first.rs              # input: calls test_vec![]
    first.expanded.rs     # auto-generated: contains Vec::new();
    second.rs
    second.expanded.rs
```

### Output Example
```
# Output:
running 1 test
Running 2 macro expansion tests
tests/expand/first.rs - ok
tests/expand/second.rs - ok
test pass ... ok
```
```

--------------------------------

### Add macrotest as a dev-dependency

Source: https://github.com/eupn/macrotest/blob/master/README.md

Include macrotest in your Cargo.toml file under the [dev-dependencies] section to enable testing.

```toml
[dev-dependencies]
macrotest = "1"
```

--------------------------------

### macrotest::expand_args

Source: https://context7.com/eupn/macrotest/llms.txt

Similar to `expand`, but allows forwarding additional arguments to the `cargo expand` command. This is beneficial for testing macros that depend on Cargo features or require specific command-line flags.

```APIDOC
## macrotest::expand_args

### Description
Same as `expand` but forwards additional arguments to the underlying `cargo expand` invocation. Useful for testing macros that are gated behind Cargo features or that require specific flags.

### Usage
```rust
// tests/tests.rs
#[test]
pub fn pass_with_feature() {
    // Passes --features test-feature to `cargo expand`, enabling feature-gated macros.
    macrotest::expand_args("tests/expand_args/*.rs", &["--features", "test-feature"]);
}
```

### Example Input File
```rust
// tests/expand_args/with_args.rs  — input file
#![cfg(feature = "test-feature")]
#[macro_use]
extern crate my_crate;

pub fn main() {
    test_feature_vec![1, 2, 3];
}
```

### Example Generated Snapshot
```rust
// tests/expand_args/with_args.expanded.rs  — generated snapshot
#[macro_use]
extern crate my_crate;
pub fn main() {
    {
        let mut temp_vec = Vec::new();
        temp_vec.push(1);
        temp_vec.push(2);
        temp_vec.push(3);
        temp_vec
    };
}
```
```

--------------------------------

### Updating Snapshots with Environment Variable

Source: https://context7.com/eupn/macrotest/llms.txt

Uses the `MACROTEST=overwrite` environment variable to automatically update snapshot files during a test run. This provides a convenient way to refresh expected outputs.

```bash
MACROTEST=overwrite cargo test
```

--------------------------------

### Updating Snapshots by Deleting Files

Source: https://context7.com/eupn/macrotest/llms.txt

Command to remove all `.expanded.rs` snapshot files, forcing macrotest to regenerate them on the next test run. This is useful for updating expected outputs.

```bash
rm tests/expand/*.expanded.rs
cargo test
```

--------------------------------

### Run Macro Expansion Tests with Custom Cargo Expand Arguments

Source: https://context7.com/eupn/macrotest/llms.txt

Use `macrotest::expand_args` to pass additional arguments to `cargo expand`, such as feature flags. This is useful for testing macros that are gated by Cargo features or require specific build configurations.

```rust
// tests/tests.rs
#[test]
pub fn pass_with_feature() {
    // Passes --features test-feature to `cargo expand`, enabling feature-gated macros.
    macrotest::expand_args("tests/expand_args/*.rs", &["--features", "test-feature"]);
}
```

```rust
// tests/expand_args/with_args.rs  — input file
#![cfg(feature = "test-feature")]
#[macro_use]
extern crate my_crate;

pub fn main() {
    test_feature_vec![1, 2, 3];
}
```

```rust
// tests/expand_args/with_args.expanded.rs  — generated snapshot
#[macro_use]
extern crate my_crate;
pub fn main() {
    {
        let mut temp_vec = Vec::new();
        temp_vec.push(1);
        temp_vec.push(2);
        temp_vec.push(3);
        temp_vec
    };
}
```

--------------------------------

### Testing Derive Macro Expansion

Source: https://context7.com/eupn/macrotest/llms.txt

A test file that applies the `MyDerive` derive macro to a struct. The expansion will be captured by macrotest.

```rust
#[macro_use]
extern crate my_proc_macro_crate;

#[derive(MyDerive)]
struct Test;
```

--------------------------------

### Expected Expansion of Derive Macro

Source: https://context7.com/eupn/macrotest/llms.txt

The snapshot of the code after the `MyDerive` macro has been applied and expanded.

```rust
#[macro_use]
extern crate my_proc_macro_crate;
struct Test;
struct Hello;
```

--------------------------------

### Testing Attribute Macro Expansion

Source: https://context7.com/eupn/macrotest/llms.txt

A test file that applies the `my_attribute` attribute macro to a struct. The expansion will be captured by macrotest.

```rust
#[macro_use]
extern crate my_proc_macro_crate;

#[my_attribute]
struct Test;
```

--------------------------------

### macrotest::expand_without_refresh_args

Source: https://context7.com/eupn/macrotest/llms.txt

Combines the strict no-refresh behavior of `expand_without_refresh` with the ability to pass extra arguments to `cargo expand`. This function fails if any required `.expanded.rs` snapshot is absent.

```APIDOC
## macrotest::expand_without_refresh_args

### Description
Combines the strict no-refresh behavior of `expand_without_refresh` with the ability to pass extra arguments to `cargo expand`. Fails if any required `.expanded.rs` snapshot is absent.

### Usage
```rust
// tests/tests.rs
#[test]
#[should_panic]
pub fn fail_expect_expanded_args() {
    // No .expanded.rs snapshots exist in no_expanded_args/ → panics because
    // expand_without_refresh_args will not create them.
    macrotest::expand_without_refresh_args(
        "tests/no_expanded_args/*.rs",
        &["--features", "test-feature"],
    );
}
```
```

--------------------------------

### Glob Pattern for Nested Directories

Source: https://context7.com/eupn/macrotest/llms.txt

Uses a glob pattern to include files from nested directories within `tests/expand/` for macrotest expansion. This ensures correct handling of more complex project structures.

```rust
#[test]
pub fn nested_dirs() {
    macrotest::expand("tests/pr61/*/*.rs");
}
```

--------------------------------

### Strict Macro Expansion Tests with Custom Arguments

Source: https://context7.com/eupn/macrotest/llms.txt

Combine strict no-refresh behavior with custom `cargo expand` arguments using `macrotest::expand_without_refresh_args`. This function fails if any required `.expanded.rs` snapshot is missing and passes specified arguments to `cargo expand`.

```rust
// tests/tests.rs
#[test]
#[should_panic]
pub fn fail_expect_expanded_args() {
    // No .expanded.rs snapshots exist in no_expanded_args/ → panics because
    // expand_without_refresh_args will not create them.
    macrotest::expand_without_refresh_args(
        "tests/no_expanded_args/*.rs",
        &["--features", "test-feature"],
    );
}
```

--------------------------------

### Declarative Macro Definition (`macro_rules!`)

Source: https://context7.com/eupn/macrotest/llms.txt

Defines a declarative macro `test_vec!` that can create a `Vec` either empty or populated with provided expressions. This macro is intended to be tested using macrotest.

```rust
#[macro_export]
macro_rules! test_vec {
    () => { Vec::new() };
    ( $( $x:expr ),+ ) => {{ 
        let mut temp_vec = Vec::new();
        $( temp_vec.push($x); )* 
        temp_vec
    }};
}
```

--------------------------------

### Procedural Macro Definitions (derive, attribute)

Source: https://context7.com/eupn/macrotest/llms.txt

Defines a derive macro `MyDerive` and an attribute macro `my_attribute`. These are procedural macros designed to be tested with macrotest.

```rust
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, DeriveInput};

#[proc_macro_derive(MyDerive)]
pub fn my_derive(_input: TokenStream) -> TokenStream {
    quote! { struct Hello; }.into()
}

#[proc_macro_attribute]
pub fn my_attribute(_args: TokenStream, input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    quote! { #input struct Hello; }.into()
}
```

--------------------------------

### macrotest::expand_without_refresh

Source: https://context7.com/eupn/macrotest/llms.txt

A strict variant of `expand`. It requires all `.expanded.rs` snapshots to exist beforehand; missing snapshots will cause the test to fail immediately without creating new files. This is useful for CI environments to prevent accidental regeneration of unreviewed snapshots.

```APIDOC
## macrotest::expand_without_refresh

### Description
Strict variant of `expand`. Requires that every `.expanded.rs` snapshot already exists — if any are missing the test immediately fails rather than creating new files. Use this in CI to prevent accidentally committed un-reviewed snapshots from being silently regenerated.

### Usage
```rust
// tests/tests.rs
#[test]
pub fn pass_expect_expanded() {
    // Will FAIL if any .expanded.rs file is absent; will NOT create new snapshots.
    macrotest::expand_without_refresh("tests/expand/*.rs");
}

#[test]
#[should_panic]
pub fn fail_when_no_snapshots() {
    // tests/no_expanded/ contains .rs files but NO .expanded.rs files → panics.
    macrotest::expand_without_refresh("tests/no_expanded/*.rs");
}
```
```

--------------------------------

### Strict Macro Expansion Tests Without Refresh

Source: https://context7.com/eupn/macrotest/llms.txt

Use `macrotest::expand_without_refresh` for strict testing where all `.expanded.rs` snapshots must pre-exist. This prevents accidental regeneration of un-reviewed snapshots in CI environments.

```rust
// tests/tests.rs
#[test]
pub fn pass_expect_expanded() {
    // Will FAIL if any .expanded.rs file is absent; will NOT create new snapshots.
    macrotest::expand_without_refresh("tests/expand/*.rs");
}
```

```rust
// tests/tests.rs
#[test]
#[should_panic]
pub fn fail_when_no_snapshots() {
    // tests/no_expanded/ contains .rs files but NO .expanded.rs files → panics.
    macrotest::expand_without_refresh("tests/no_expanded/*.rs");
}
```

--------------------------------

### Expected Expansion of `test_vec![]`

Source: https://context7.com/eupn/macrotest/llms.txt

The expected output after `cargo expand` processes the `test_vec![]` macro invocation. This serves as the snapshot for regression testing.

```rust
#[macro_use]
extern crate my_crate;
pub fn main() {
    Vec::new();
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.