Rust libtest
doc.rust-lang.org
- Free plan
- Windows
- macOS
- Linux
What Rust libtest is
Rust libtest is the built-in test harness for building and running tests in a Rust crate. Compiling with `rustc --test` links the executable with libtest, which runs free functions marked with `#[test]`. A test passes when it returns without an error; it fails if it panics or returns a non-zero termination result. Tests can 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 through the harness. Documentation tests run by default: Cargo extracts code samples from library comments and executes them. You can filter tests by name or 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, and formatted as pretty, terse, or JSON; JSON format is unstable. Rust libtest is free and supports Linux, macOS, and Windows. Catching panics requires the unwind strategy; abort-strategy support is experimental. Benchmarks, custom harnesses, and the test crate’s support API are nightly-only or experimental.
Who it suits
Rust libtest suits Rust developers who want a built-in way to run unit, integration, and documentation tests. Its filtering, parallel execution, and output options also serve projects with larger test suites.
Good to know, and what to watch
- Built into Rust’s standard library test harness.
- Cargo runs unit, integration, and documentation tests.
- Supports test filtering, ignored tests, and test listing.
- Runs on Linux, macOS, and Windows.
- Catching panics requires the unwind strategy.
- Benchmarks are unstable and nightly-only.
- The test crate’s support API is experimental.
Plans
Every plan and priceRust libtest
Free plan
Getting started
- Open the Rust documentation at https://doc.rust-lang.org/rustc/tests/.
- Build a test executable with `rustc --test` to link it with libtest.
- Mark test functions with `#[test]`.
- Run tests with Cargo’s `cargo test` command or execute the test binary.
- Use the harness options to filter tests, configure thread count, or choose output.
Limits to check
The harness requires the unwind panic strategy to catch panics; abort-strategy support is experimental. Benchmarking with `#[bench]` and custom harnesses are experimental and available only on the nightly channel, and JSON output is unstable.
The Club's review
Rust libtest is Rust’s built-in test harness, used directly with rustc or through Cargo. It suits Rust developers who want a standard way to run unit, integration, and documentation tests. Its strongest case is the automatic Cargo workflow; nightly-only extensions and the unwind requirement narrow its reach for specialized setups.
Overview
With rustc --test, the compiler links a test executable to libtest, which discovers and runs functions marked with #[test]. A test passes if it returns normally and fails if it panics or returns a non-zero termination result. Cargo’s cargo test takes care of building and running tests, so most projects can use the harness without managing those steps themselves.
The default model is straightforward: tests run in parallel, and tests marked #[ignore] are compiled but skipped unless selected. The #[should_panic] attribute covers tests that are meant to panic. One important constraint is that catching panics requires the unwind panic strategy; abort-strategy support is experimental.
Key features
Filtering and test selection
Positional arguments filter tests by substring in their full test-function path. The harness also supports exact matching, skipping matches, and selecting ignored tests. This gives developers useful control from the command line without changing test code. Use --list to print tests and benchmarks without running them.
Execution and output
Parallel execution is the default, with the number of test threads adjustable through --test-threads. That is convenient for a general test run, while the thread setting offers a way to control concurrency. The harness can capture output, show output from successful tests, and produce pretty, terse, or JSON output. JSON output is unstable, so it is a poor choice for a workflow that depends on a fixed format.
Benchmarks and custom harnesses
The #[bench] feature and custom test harness support are experimental and require Rust’s nightly channel. Unstable command-line options need -Z unstable-options and may break or change. These features can serve developers willing to follow nightly changes, but they are not a dependable foundation for stable-channel requirements.
Pricing
Rust libtest is free. The Rust libtest plan costs free and is built into Rust’s standard library test harness. There is no paid tier to trade against feature caps; the practical trade-off is that the more experimental capabilities require nightly Rust.
Platforms
Rust libtest supports Linux, macOS, and Windows. That covers the three major desktop operating systems for teams running Rust tests across those environments.
Who it's for
Rust libtest is the right default for Rust developers who want Cargo to build and run unit, integration, and documentation tests, with filtering and output controls in the same harness. Cargo also extracts code samples from library documentation comments and runs them as documentation tests by default, which helps include examples in the project’s test routine.
Look elsewhere if you need a stable benchmark or custom-harness API, or if your test setup depends on catching panics while using an abort panic strategy. The nightly channel and experimental status make those use cases less suitable for a stable, predictable workflow.
Pros and cons
- Pro: Cargo builds and runs tests through cargo test, including unit, integration, and documentation tests, reducing the need to wire up a separate runner.
- Pro: Test filtering, ignored-test selection, thread-count control, and multiple output formats provide useful command-line control over a run.
- Pro: The built-in harness is free and supports Linux, macOS, and Windows.
- Con: Panic-catching tests require the unwind strategy; abort-strategy support remains experimental.
- Con: Benchmarks and custom harnesses are nightly-only experimental features, and unstable options can change or break.
- Con: JSON output is unstable, making it a risky dependency for tooling that expects a settled interface.
Alternatives
For other testing frameworks, browse Unit Testing Frameworks. The alternatives below target different languages or testing setups, rather than replacing libtest as a Rust harness.
- QUnit is a free, open-source JavaScript testing framework distributed via CDN, npm, and Yarn; choose it for JavaScript projects instead of Rust.
- Pest is a free PHP testing framework; choose it for PHP projects, noting that Pest 5 requires PHP 8.4 or later.
- ScalaTest is free, open-source software under the Apache 2.0 license; choose it for a Scala project.
- Vitest is free and open source; choose it for a project that calls for that alternative rather than Rust’s built-in harness.
- CppUTest is a free C/C++ unit-testing and mocking framework; choose it for C or C++ development.
- Kotest is a free option for a project that calls for Kotest’s standalone test framework, assertions library, or property testing.
- Hypothesis offers a free plan; consider it when its plan and platform fit your testing needs.
- NUnit is free to use under the MIT license for commercial and noncommercial applications; choose it when that alternative fits your testing needs.
Verdict
Rust libtest is the clear default for Rust developers who want Cargo to handle ordinary test builds and execution at no cost. Its integrated workflow and practical test controls are strong reasons to choose it. Look elsewhere for stable benchmark or custom-harness features, or when an abort-based setup must catch panics.
The verdict
Rust libtest provides a standard path for running crate tests, with Cargo handling build and execution. Nightly-only features and the unwind requirement matter if you need benchmarks, custom harnesses, or panic catching.
Questions people ask
Is Rust libtest free?
Yes. The listed plan is free, and libtest is built into Rust’s standard library test harness.
Which platforms does it support?
Linux, macOS, and Windows.
Does it work with Cargo?
Yes. `cargo test` builds and runs tests using libtest, including unit, integration, and documentation tests.
Can I run only selected tests?
Yes. The harness supports name and path filtering, exact matching, skipping matches, and selecting ignored tests.
Are benchmarks available?
The `#[bench]` benchmark feature is unstable and available only on Rust’s nightly channel.
What the maker publishes
- API stability
- The Rust test crate’s support API is marked nightly-only and experimental. source
- Benchmarking
- The #[bench] benchmark feature is unstable and available only on Rust’s nightly channel. source
- Benchmarks
- The harness supports `#[bench]` benchmarks, but benchmarks are unstable and available only on the nightly channel. source
- Cargo
- Cargo’s cargo test command handles building and running tests automatically. source
- Cargo integration
- Cargo's `cargo test` command builds and runs tests using libtest automatically. source
- Custom harnesses
- Experimental support for custom test harnesses is available on the nightly channel. source
- Documentation tests
- Cargo runs documentation tests by default by extracting code samples from library documentation comments and executing them. source
- Filtering
- Positional command-line arguments filter tests by substring in their full test-function path. source
- Harness
- Building with rustc --test links the executable with libtest, which handles running tests. source
- Listing
- The --list option prints tests and benchmarks without running them. source
- Output
- The harness can capture test output, show output from successful tests, and select pretty, terse, or JSON formats; JSON format is unstable. source
- Panic strategy limit
- Tests must use the unwind panic strategy to catch panics; abort-strategy support is experimental. source
- Parallel execution
- Tests run in parallel by default, and the thread count can be set with `--test-threads`. source
- Pass and fail
- A test passes when it returns without an error and fails when it panics or returns a non-zero termination result. source
- Purpose
- Rustc includes a built-in facility for building and running tests for a crate. source
- Results
- Tests pass when they return without an error and fail if they panic or return a non-zero termination result. source
- Test attributes
- The harness supports #[should_panic] tests and tests marked #[ignore], which are compiled but not run by default. source
- Test functions
- Tests are free functions marked with the `#[test]` attribute. source
- Test harness
- With `--test`, rustc links the executable with libtest, which handles running tests. source
- Test scope
- Cargo's test command compiles and executes unit, integration, and documentation tests. source
- Test selection
- The harness supports filtering tests by name, including exact matching, skipping matches, and selecting ignored tests. source
- Unstable options
- Unstable command-line options may not work correctly, break, or change, and require `-Z unstable-options`. source
Checked against the maker's pages on 8 Oct 2026.