- Home
- Unit Testing Frameworks
- Rust libtest
Rust libtest
What it is
Rust libtest is the test harness built into Rust’s standard library support. Compiling with `rustc --test` links an executable with libtest, which runs free functions marked `#[test]`. A test passes when it returns without an error; panics or non-zero termination results fail it. Cargo’s `cargo test` command builds and runs unit, integration, and documentation tests through the harness. Documentation tests run by extracting code samples from library comments and executing them. Tests may use `#[should_panic]` or `#[ignore]`; ignored tests are compiled but skipped by default. The harness filters by test-function path, supports exact matching and skipped matches, selects ignored tests, and lists tests or benchmarks without running them. Tests run in parallel by default, with thread count configurable through `--test-threads`. Output can be captured, shown for successful tests, or formatted as pretty, terse, or JSON; JSON output is unstable. Catching panics requires the unwind strategy, while abort support is experimental. `#[bench]` benchmarks and custom harnesses are nightly-only experimental features. Rust libtest is free on Linux, macOS, and Windows.
For and against
For
- Built into Rust’s test harness
- Runs unit, integration, and documentation tests
- Supports filtering and ignored tests
- Parallel execution with configurable threads
- Free on Linux, macOS, and Windows
Against
- JSON output is unstable
- Benchmarking requires nightly Rust
- Custom harnesses are experimental
- Abort panic strategy support is experimental
The verdict
Rust libtest provides the standard command-line test workflow for Rust crates, with filtering, parallel runs, and multiple output formats. Nightly-only and experimental features should be treated separately from its stable testing path.
Who it suits
It suits Rust developers building crate, unit, integration, documentation, or benchmark tests. Cargo users get the harness through the standard `cargo test` workflow.
Plans and prices
Rust libtest
Built into Rust’s standard library test harness
Read 8 Oct 2026 · doc.rust-lang.org
On the record
- API stability
- The Rust test crate’s support API is marked nightly-only and experimental.doc.rust-lang.org · read 8 Oct 2026
- Benchmarking
- The #[bench] benchmark feature is unstable and available only on Rust’s nightly channel.doc.rust-lang.org · read 8 Oct 2026
- Benchmarks
- The harness supports `#[bench]` benchmarks, but benchmarks are unstable and available only on the nightly channel.doc.rust-lang.org · read 8 Oct 2026
- Cargo
- Cargo’s cargo test command handles building and running tests automatically.doc.rust-lang.org · read 8 Oct 2026
- Cargo integration
- Cargo's `cargo test` command builds and runs tests using libtest automatically.doc.rust-lang.org · read 8 Oct 2026
- Custom harnesses
- Experimental support for custom test harnesses is available on the nightly channel.doc.rust-lang.org · read 8 Oct 2026
- Documentation tests
- Cargo runs documentation tests by default by extracting code samples from library documentation comments and executing them.doc.rust-lang.org · read 8 Oct 2026
- Filtering
- Positional command-line arguments filter tests by substring in their full test-function path.doc.rust-lang.org · read 8 Oct 2026
- Harness
- Building with rustc --test links the executable with libtest, which handles running tests.doc.rust-lang.org · read 8 Oct 2026
- Listing
- The --list option prints tests and benchmarks without running them.doc.rust-lang.org · read 8 Oct 2026
- Output
- The harness can capture test output, show output from successful tests, and select pretty, terse, or JSON formats; JSON format is unstable.doc.rust-lang.org · read 8 Oct 2026
- Panic strategy limit
- Tests must use the unwind panic strategy to catch panics; abort-strategy support is experimental.doc.rust-lang.org · read 8 Oct 2026
- Parallel execution
- Tests run in parallel by default, and the thread count can be set with `--test-threads`.doc.rust-lang.org · read 8 Oct 2026
- Pass and fail
- A test passes when it returns without an error and fails when it panics or returns a non-zero termination result.doc.rust-lang.org · read 8 Oct 2026
- Purpose
- Rustc includes a built-in facility for building and running tests for a crate.doc.rust-lang.org · read 8 Oct 2026
- Results
- Tests pass when they return without an error and fail if they panic or return a non-zero termination result.doc.rust-lang.org · read 8 Oct 2026
- Test attributes
- The harness supports #[should_panic] tests and tests marked #[ignore], which are compiled but not run by default.doc.rust-lang.org · read 8 Oct 2026
- Test functions
- Tests are free functions marked with the `#[test]` attribute.doc.rust-lang.org · read 8 Oct 2026
