Rust libtest
Rust libtest is the built-in harness for building and running tests for a Rust crate.
What Rust libtest is
Rust libtest is the built-in harness for building and running tests for a Rust crate. Compile with `rustc --test` to link the executable with libtest, which runs free functions marked with `#[test]`. A test passes if it returns without an error; a panic or non-zero termination result makes it fail. Tests may also be marked `#[should_panic]` or `#[ignore]`, with ignored tests compiled but skipped by default. Cargo's `cargo test` builds and runs unit, integration, and documentation tests, including documentation code samples by default. The harness can filter tests by name or full test-function path, skip matches, select ignored tests, and list tests and benchmarks without running them. Tests run in parallel by default, and `--test-threads` sets the thread count. Output can be captured, shown for successful tests, or formatted as pretty, terse, or JSON; JSON output is unstable. Rust libtest is free and supports Linux, macOS, and Windows. Catching panics requires the unwind strategy; abort-strategy support is experimental. Benchmarking with `#[bench]` and custom test harnesses are experimental and available only on nightly. The test crate's support API is also marked nightly-only and experimental.
Good
- Cargo runs unit, integration, and documentation tests.
- Supports ignored and should-panic tests.
- Tests can run in parallel with configurable thread count.
- Provides test filtering and multiple output formats.
Watch out
- Catching panics requires the unwind strategy.
- JSON output is unstable.
- Benchmarks and custom harnesses are experimental and nightly-only.
Who it suits
Rust libtest suits Rust developers who need to build and run crate tests through rustc or Cargo. Nightly Rust users may also explore its experimental benchmarking and custom-harness support.
Verdict
Rust libtest provides the standard path for running Rust crate tests, with Cargo handling common test types automatically. Its experimental options and panic-strategy requirement matter for teams relying on benchmarking or abort behavior.
Plans and prices
From Rust libtest's own pricing page, checked 8 Oct 2026.
| Plan | Price | What it gives you |
|---|---|---|
| Rust libtest | Free | Built into Rust’s standard library test harness |
The facts
Each one read from Rust libtest's own pages, with the date it was checked.
What it does
- API stability
- The Rust test crate’s support API is marked nightly-only and experimental.checked 8 Oct 2026
- Benchmarking
- The #[bench] benchmark feature is unstable and available only on Rust’s nightly channel.checked 8 Oct 2026
- Benchmarks
- The harness supports `#[bench]` benchmarks, but benchmarks are unstable and available only on the nightly channel.checked 8 Oct 2026
- Cargo
- Cargo’s cargo test command handles building and running tests automatically.checked 8 Oct 2026
- Cargo integration
- Cargo's `cargo test` command builds and runs tests using libtest automatically.checked 8 Oct 2026
- Custom harnesses
- Experimental support for custom test harnesses is available on the nightly channel.checked 8 Oct 2026
- Documentation tests
- Cargo runs documentation tests by default by extracting code samples from library documentation comments and executing them.checked 8 Oct 2026
- Filtering
- Positional command-line arguments filter tests by substring in their full test-function path.checked 8 Oct 2026
- Harness
- Building with rustc --test links the executable with libtest, which handles running tests.checked 8 Oct 2026
- Listing
- The --list option prints tests and benchmarks without running them.checked 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.checked 8 Oct 2026
- Panic strategy limit
- Tests must use the unwind panic strategy to catch panics; abort-strategy support is experimental.checked 8 Oct 2026
- Parallel execution
- Tests run in parallel by default, and the thread count can be set with `--test-threads`.checked 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.checked 8 Oct 2026
- Purpose
- Rustc includes a built-in facility for building and running tests for a crate.checked 8 Oct 2026
- Results
- Tests pass when they return without an error and fail if they panic or return a non-zero termination result.checked 8 Oct 2026
- Test attributes
- The harness supports #[should_panic] tests and tests marked #[ignore], which are compiled but not run by default.checked 8 Oct 2026
- Test functions
- Tests are free functions marked with the `#[test]` attribute.checked 8 Oct 2026
- Test harness
- With `--test`, rustc links the executable with libtest, which handles running tests.checked 8 Oct 2026
- Test scope
- Cargo's test command compiles and executes unit, integration, and documentation tests.checked 8 Oct 2026
- Test selection
- The harness supports filtering tests by name, including exact matching, skipping matches, and selecting ignored tests.checked 8 Oct 2026
- Unstable options
- Unstable command-line options may not work correctly, break, or change, and require `-Z unstable-options`.checked 8 Oct 2026
