Controlling test execution - Rust for C-Programmers

24.4 Controlling Test Execution

Cargo provides fine-grained control over the test execution process. By default, cargo test compiles and runs all enabled tests in your project, which includes unit tests, integration tests, and (as we’ll cover in Section 24.6) documentation tests. However, you often need more specific control, such as running a subset of tests by name, focusing only on unit or specific integration tests, or adjusting execution parameters like parallelism and output verbosity. These options are invaluable for efficient development workflows and for managing test suites in continuous integration (CI) environments.

24.4.1 Running Specific Tests

You can selectively run tests based on their names or their location within your project:

Filter by Name: Run only tests whose names contain a specific substring. The filter applies to the test function’s full path (e.g., module_name::sub_module::test_function_name or simply test_function_name if it’s unique enough).
```
# Runs tests with "api" in their name, like test_public_api_call
# or api_tests::some_test
cargo test api

# Runs only the test named test_internal_logic within the tests module
# of your library
cargo test tests::test_internal_logic
```
The substring match is case-sensitive.
Run Specific Integration Test File: Execute all #[test] functions within a particular integration test file located in the tests/ directory. Provide the filename without the .rs extension.
```
# Runs all #[test] functions in tests/api_usage.rs
cargo test --test api_usage
```
Run Only Library Unit Tests: Execute only the unit tests defined within your library crate (typically in src/lib.rs or modules defined therein). This command will not run integration tests or documentation tests.
```
cargo test --lib
```
Similarly, if you have a binary crate with tests in src/main.rs, you can run them using cargo test --bin your_binary_name. If your package only contains a single binary, cargo test --bins can be used.

24.4.2 Ignoring Tests

Tests that are slow, require specific environments (e.g., network access), or are currently flaky can be marked with the #[ignore] attribute.

#[test]
fn very_fast_test() { /* ... */ }

#[test]
#[ignore = "Requires network access and is slow"] // Optional reason string
fn test_external_service() {
    // ... code that might take a long time or fail intermittently ...
}

Ignored tests are skipped by default when running cargo test.
To run only the ignored tests:
```
cargo test -- --ignored
```
To run all tests, including those marked as ignored:
```
cargo test -- --include-ignored
```

Note on --: Arguments placed after a standalone -- are passed directly to the test runner executable built by Cargo, not to Cargo itself. Use cargo test -- --help to see options accepted by the test runner, such as --ignored, --include-ignored, --test-threads, and --nocapture. Contrast this with cargo test --help, which shows Cargo’s own command-line options.

24.4.3 Controlling Parallelism and Output

Parallel Execution: By default, cargo test runs tests in parallel using multiple threads for faster execution. If tests might interfere with each other (e.g., accessing the same file or resource without synchronization) or if sequential execution simplifies debugging, parallelism can be disabled:
```
# Run tests sequentially using only one thread
cargo test -- --test-threads=1
```
Capturing Output: Standard output (println!) and standard error (eprintln!) generated by passing tests are captured by default and not displayed. Output from failing tests is shown. To display the output from all tests, regardless of their status:
```
# Show all stdout/stderr from all tests
cargo test -- --nocapture
```