Rust libtest
doc.rust-lang.org
What it is
Rust libtest is Rust’s built-in test harness for compiling and running crate tests. Building with `rustc --test` links the executable to libtest; tests are free functions marked `#[test]`. Cargo’s `cargo test` handles building and running unit, integration, and documentation tests, including code samples extracted from library documentation comments. A test succeeds when it returns without an error; a panic or non-zero termination result marks failure. You can mark tests to expect a panic or to be ignored, filter by name, choose exact matches, skip matches, select ignored tests, or list tests and benchmarks without running them. Tests run in parallel by default, with the thread count configurable. The harness can capture output, display successful-test output, and format results as pretty, terse, or JSON; JSON formatting is unstable. Rust libtest is free and supports Linux, macOS, and Windows. Catching panics requires the unwind strategy; abort-strategy support is experimental. Benchmarking and custom harnesses are experimental and nightly-only.
Spec sheet
- Purpose
- Rustc includes a built-in facility for building and running tests for a crate.Read 8 Oct 2026 · doc.rust-lang.org
- API stability
- The Rust test crate’s support API is marked nightly-only and experimental.Read 8 Oct 2026 · doc.rust-lang.org
- Benchmarking
- The #[bench] benchmark feature is unstable and available only on Rust’s nightly channel.Read 8 Oct 2026 · doc.rust-lang.org
- Benchmarks
- The harness supports `#[bench]` benchmarks, but benchmarks are unstable and available only on the nightly channel.Read 8 Oct 2026 · doc.rust-lang.org
- Cargo
- Cargo’s cargo test command handles building and running tests automatically.Read 8 Oct 2026 · doc.rust-lang.org
- Cargo integration
- Cargo's `cargo test` command builds and runs tests using libtest automatically.Read 8 Oct 2026 · doc.rust-lang.org
- Custom harnesses
- Experimental support for custom test harnesses is available on the nightly channel.Read 8 Oct 2026 · doc.rust-lang.org
- Documentation tests
- Cargo runs documentation tests by default by extracting code samples from library documentation comments and executing them.Read 8 Oct 2026 · doc.rust-lang.org
- Filtering
- Positional command-line arguments filter tests by substring in their full test-function path.Read 8 Oct 2026 · doc.rust-lang.org
- Harness
- Building with rustc --test links the executable with libtest, which handles running tests.Read 8 Oct 2026 · doc.rust-lang.org
- Listing
- The --list option prints tests and benchmarks without running them.Read 8 Oct 2026 · doc.rust-lang.org
- Output
- The harness can capture test output, show output from successful tests, and select pretty, terse, or JSON formats; JSON format is unstable.Read 8 Oct 2026 · doc.rust-lang.org
- Panic strategy limit
- Tests must use the unwind panic strategy to catch panics; abort-strategy support is experimental.Read 8 Oct 2026 · doc.rust-lang.org
- Parallel execution
- Tests run in parallel by default, and the thread count can be set with `--test-threads`.Read 8 Oct 2026 · doc.rust-lang.org
- Pass and fail
- A test passes when it returns without an error and fails when it panics or returns a non-zero termination result.Read 8 Oct 2026 · doc.rust-lang.org
- Results
- Tests pass when they return without an error and fail if they panic or return a non-zero termination result.Read 8 Oct 2026 · doc.rust-lang.org
- Test attributes
- The harness supports #[should_panic] tests and tests marked #[ignore], which are compiled but not run by default.Read 8 Oct 2026 · doc.rust-lang.org
- Test functions
- Tests are free functions marked with the `#[test]` attribute.Read 8 Oct 2026 · doc.rust-lang.org
- Test harness
- With `--test`, rustc links the executable with libtest, which handles running tests.Read 8 Oct 2026 · doc.rust-lang.org
- Test scope
- Cargo's test command compiles and executes unit, integration, and documentation tests.Read 8 Oct 2026 · doc.rust-lang.org
- Test selection
- The harness supports filtering tests by name, including exact matching, skipping matches, and selecting ignored tests.Read 8 Oct 2026 · doc.rust-lang.org
- Unstable options
- Unstable command-line options may not work correctly, break, or change, and require `-Z unstable-options`.Read 8 Oct 2026 · doc.rust-lang.org
Plans and prices
Rust libtest Free Built into Rust’s standard library test harness Read 8 Oct 2026 · doc.rust-lang.org
Strong points and limits
Strong points
- Built into Rust’s standard library test harness
- Cargo runs unit, integration, and documentation tests
- Supports filters, ignored tests, and test listing
- Parallel execution with configurable thread count
- Free on Linux, macOS, and Windows
Limits
- JSON output format is unstable
- Benchmarks require Rust’s nightly channel
- Catching panics requires the unwind strategy
Who it suits
It suits Rust developers who want Cargo or rustc to build and run crate tests across Linux, macOS, or Windows. Teams needing stable benchmarking or custom harness support should note those features are nightly-only and experimental.
Verdict
Rust libtest covers common crate testing tasks, with Cargo automating test builds and execution. Its experimental and nightly-only features matter if you need benchmarking or custom harnesses.
Where Specifiction places it
- Unit Testing Frameworks#13 of 328.0
