trybuild Documentation

Use trybuild::TestCases::pass to assert that a Rust file compiles successfully and that its main function executes without panicking. This is useful for testing successful usage patterns or for workshop-style environments where you want to control the execution of multiple test cases in a single harness.

#[test]
fn ui() {
    let t = trybuild::TestCases::new();
    t.pass("tests/01-parse-header.rs");
    t.compile_fail("tests/03-expand-four-errors.rs");
}

Use trybuild::TestCases::compile_fail to assert that specific Rust files fail to compile with the expected error messages.

For each test file (e.g., tests/my_test.rs), trybuild expects an adjacent file with the same name but a .stderr extension (e.g., tests/my_test.stderr) containing the exact expected compiler output. If the compiler output does not match the .stderr file, the test fails and displays a diff.

Note: A compile_fail test will also fail if the code actually compiles successfully.

#[test]
fn ui() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/ui/*.rs");
}

When your compiler output changes, you need to update your .stderr files. There are two recommended workflows:

1. The wip directory method: If a compile_fail test is run and no .stderr file exists, trybuild saves the actual output into a wip/ directory in your project root. You can then move these files from wip/ into your test directory.
2. The TRYBUILD=overwrite method: Run your tests with the TRYBUILD=overwrite environment variable. This tells trybuild to skip the wip/ directory and write the actual compiler output directly into your existing .stderr files. Always check git diff after using this method to verify the changes.

TRYBUILD=overwrite cargo test

The Rust compiler's diagnostic output (including source snippets) can change depending on whether the rust-src component is installed via rustup. To ensure consistent test results across different environments (like local dev vs. CI), add a rust-toolchain.toml file to your project:

[toolchain]
components = ["rust-src"]

The TestCases struct is the primary entry point for the trybuild harness. It is typically instantiated within a standard #[test] function.

• new() -> TestCases: Creates a new test runner instance.
• pass<P: AsRef<Path>>(&self, path: P): Registers a file that is expected to compile successfully and run without panicking.
• compile_fail<P: AsRef<Path>>(&self, path: P): Registers a file that is expected to fail compilation. It expects a corresponding *.stderr file to exist for comparison.

let t = trybuild::TestCases::new();
t.pass("tests/success.rs");
t.compile_fail("tests/failure.rs");

The Variations struct represents the collection of possible normalized versions of a compiler output.

• preferred(): Returns the 'last' variation. This is the version used for display when a test fails or when the stderr file is missing.
• any<F>(mut f: F): A utility to check if any of the generated variations satisfy a predicate f. This is how trybuild determines if a test passes.
• concat(&mut self, other: &Self): Merges another set of variations into the current one.

// Example of how Variations are used conceptually
if variations.any(|stderr| stderr == expected_output) {
    // Test passes
}

let preferred_output = variations.preferred();

The following Normalization enum variants define the different levels of transformation applied to compiler output. These are applied cumulatively based on their order. New steps are added to the end of the list to maintain backward compatibility with older snapshots.

// Available Normalization levels:
Basic,
StripCouldNotCompile,
StripCouldNotCompile2,
StripForMoreInformation,
StripForMoreInformation2,
TrimEnd,
RustLib,
TypeDirBackslash,
WorkspaceLines,
PathDependencies,
CargoRegistry,
ArrowOtherCrate,
RelativeToDir,
LinesOutsideInputFile,
Unindent,
AndOthers,
StripLongTypeNameFiles,
UnindentAfterHelp,
AndOthersVerbose,
UnindentMultilineNote,
DependencyVersion,
HeadingNote,
UnindentSuggestion,
CustomRegistry,
MorePathDependencies,

You can run a subset of your trybuild tests by passing a filter string to cargo test. The filter string must be prefixed with trybuild= and passed as an argument after the -- separator. Only test cases whose filenames contain the filter string will be executed.

Example usage:

$ cargo test -- ui trybuild=tuple_structs.rs