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] [TESTNAME...] [-- ARGS...]

--no-run
    Compile tests without running them.

--no-fail-fast
    Run all tests even if some fail, instead of stopping after the first failure.

--test
    Run only the specified integration test binary (e.g., --test my_integration_test).

--lib
    Test the current package's library target.

--bin
    Test a specific binary target.

--example
    Test a specific example.

--features
    Activate specified comma-separated features (e.g., --features "foo,bar").

--all-features
    Activate all available features of the package.

--workspace
    Test all packages in the current workspace.

-p / --package
    Test a specific package in the workspace.

--release
    Build tests in release mode with optimizations.

-j / --jobs
    Number of parallel jobs to run for compilation.

-v / --verbose
    Use verbose output, showing extra information.

-- --nocapture
    Don't capture stdout/stderr of test processes; print directly to console. Useful for debugging.

-- --test-threads
    Number of threads to use for running tests concurrently. Defaults to the number of CPU cores.

-- --ignored
    Run only tests marked with #[ignore].

-- --show-output
    Show stdout/stderr for successful tests as well (not just failures).

-- --skip
    Skip tests matching the provided TESTNAME.

The cargo test command compiles and executes all tests found in the current Rust package or workspace. It's an integral part of the Rust development workflow, ensuring code correctness and stability.
By default, cargo test discovers and runs three types of tests: unit tests (functions annotated with #[test] within modules), integration tests (files placed in the tests/ directory, treated as separate crates), and documentation tests (code examples embedded in documentation comments).
The command first builds the test binaries and then runs them, reporting the outcome for each test, including passed, failed, and ignored counts. This streamlined approach makes testing an efficient and accessible part of Rust development.

Tests must be written in Rust and annotated with #[test] or placed in the appropriate directory (tests/ for integration tests).
Arguments specified after -- are passed directly to the test binary, not interpreted by cargo itself. This distinction is crucial for options like --nocapture or --test-threads.
Large test suites can be slow; consider using --jobs for faster compilation or targeting specific tests during development.

You can run specific tests by providing part of their name as an argument directly after cargo test (e.g., cargo test my_specific_test). This will filter both unit and integration tests whose names contain the given string. Regular expressions can also be used for more advanced filtering.

RUST_BACKTRACE=1: Displays a backtrace on panic in tests, aiding in debugging.
RUST_TEST_THREADS=: Overrides the default number of test threads globally, equivalent to passing -- --test-threads .

cargo test automatically discovers and runs code examples embedded within documentation comments (marked with ```rust). This ensures that your documentation remains accurate and up-to-date with your code's behavior, promoting high-quality documentation practices.

cargo test has been a core component of the Rust ecosystem since the early days of Cargo and before the Rust 1.0 release. Its integration with the built-in test framework (libtest) has made testing a seamless and fundamental part of Rust development. Over time, features like doctests and improved filtering capabilities have been added, enhancing its versatility and developer experience.

cargo(1), cargo build(1), cargo run(1), cargo bench(1), rustc(1)