Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

Rust libtest

doc.rust-lang.org

  • Free plan
  • Windows
  • macOS
  • Linux
7.7 Club score Visit doc.rust-lang.org

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.

Rust libtest

Free

Free plan

Getting started

  1. Open the Rust documentation at https://doc.rust-lang.org/rustc/tests/.
  2. Build a test executable with `rustc --test` to link it with libtest.
  3. Mark test functions with `#[test]`.
  4. Run tests with Cargo’s `cargo test` command or execute the test binary.
  5. 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.