cargo-test

Only run tests containing a specific string in their names

$ cargo [[t|test]] [test_name]

$ cargo [[t|test]] -- --test-threads [count]

$ cargo [[t|test]] [[-r|--release]]

$ cargo [[t|test]] --workspace

$ cargo [[t|test]] [[-p|--package]] [package]

$ cargo [[t|test]] -- --nocapture

cargo test [OPTIONS] [<paths>...] [-- [<test-args>...]]

-h, --help
    Prints help information

-V, --version
    Prints version information

--all
    Test all packages in the workspace

--all-features
    Activate all available features

--bins
    Test all binaries

--color <WHEN>
    Configure coloring of output: auto, always, never

--doc
    Test only documentation examples

--examples
    Test all examples

--frozen
    Require Cargo.lock and cache up to date

--lib
    Test only the library

--manifest-path <PATH>
    Path to Cargo.toml

--no-default-features
    Disable default features

--no-fail-fast
    Run all tests despite failures

--no-run
    Compile but skip running tests

--package <SPEC>...
    Test only specified packages

--release
    Build in release mode with optimizations

--test <NAME>
    Test only the specified test target

--tests
    Test all tests (lib/tests/benches/examples)

-p <SPEC>, --package <SPEC>
    Package to test

-q, --quiet
    Suppress cargo log messages

-v, --verbose ...
    Verbose output; -vv for more

--workspace
    Test root workspace packages

The cargo test command compiles and runs unit tests for a Rust project, utilizing Rust's built-in testing framework. It automatically discovers tests marked with the #[test] attribute in source files, including integration tests in the tests/ directory.

By default, it builds in debug mode and runs tests in parallel across available CPU cores for speed. Tests can be filtered by name or module using arguments, and options allow targeting specific packages, binaries, examples, or benchmarks.

Output includes pass/fail status, execution time, and failure details with stack traces. Verbose mode (-v) shows compilation steps, while --no-run compiles without executing. It supports workspace projects, feature flags, and release builds (--release).

Ideal for CI/CD pipelines, it exits with non-zero code on failures, enabling script integration. Tests can accept command-line args passed after --, useful for parameterized testing.

Requires Rust toolchain and Cargo installed. Tests must use #[test] attribute. Parallel execution may interleave output. Workspace mode needs [workspace] in Cargo.toml.

Filter tests with cargo test <regex> or cargo test -- --ignored for opt-in tests.
Pass args to tests via -- <args>.

Use cargo bench for benchmarks, but cargo test -- --bench runs them as tests.

Introduced with Cargo 0.0.1 in 2014 by Rust team at Mozilla. Evolved with Rust editions (2018, 2021), adding workspace support, feature flags, and parallel testing improvements.

cargo build(1), cargo run(1), cargo check(1), rustdoc(1), rustc(1)