cargo test: Usage, Options & Common CI Errors

Build and run every test target in your crate.

cargo test compiles your crate in test mode and runs unit tests, integration tests under tests/, and documentation tests. Arguments after -- pass through to the test binary.

What it does

Builds the test harness for each target and executes it. By default tests run in parallel threads, which can surface ordering or shared-state flakiness that only appears in CI.

Common usage

cargo test                        # all tests
cargo test my_module::            # filter by name substring
cargo test --release              # test optimized build
cargo test -- --nocapture         # show println! output
cargo test -- --test-threads=1    # run serially

Common CI error: flaky parallel tests

Tests that share a file, port, or temp dir pass locally but fail intermittently in CI because the runner has more cores and higher parallelism. Reproduce with cargo test -- --test-threads=1; the real fix is isolating shared state (unique temp dirs, ephemeral ports) rather than serializing the whole suite.

Options

Related guides