Controlling How Tests Are Run in Rust

Running tests efficiently and effectively is crucial for maintaining code quality. Rust's `cargo test` command provides a robust and flexible way to execute tests, offering several options to control which tests run, how they run, and what output they produce. This control is essential for various scenarios, such as debugging failures, focusing on specific features, or speeding up CI/CD pipelines.

Here are the primary ways to control how tests are run:

1. Running All Tests (Default Behavior):
* `cargo test`
* This command compiles your code and runs all tests found in your project's `src/lib.rs`, `src/main.rs`, `src/bin/*.rs`, and `tests/*.rs` files. It automatically detects functions annotated with `#[test]`.

2. Running Specific Tests:
* You can run specific tests by providing a pattern to `cargo test`. This pattern is matched against the full name of the test function.
* `cargo test <test_name_pattern>`
* Example: `cargo test add_two` will run tests like `test_add_two_numbers`.
* Example: `cargo test tests::add` will run all tests within the `tests` module that contain `add` in their name.
* This is particularly useful when you're working on a specific feature or trying to debug a particular test failure, as it saves time by not running the entire test suite.

3. Ignoring Tests:
* Sometimes, tests are expensive, require specific environments, or are temporarily broken. You can mark these tests to be ignored by default using the `#[ignore]` attribute.
* `#[test]
#[ignore]
fn expensive_test() { ... }`
* When you run `cargo test`, ignored tests will not be executed.

4. Running Ignored Tests:
* To explicitly run ignored tests, you use the `--ignored` flag.
* `cargo test -- --ignored`
* This will run *only* the tests marked with `#[ignore]`. Note the `--` separator; arguments after `--` are passed directly to the test binary, not to `cargo` itself.
* You can combine this with a name filter to run a specific ignored test: `cargo test -- --ignored expensive_test`.

5. Controlling Parallelism:
* By default, Rust runs tests in parallel using threads. This speeds up execution, but can cause issues if tests share mutable state or external resources.
* You can control the number of threads used with the `--test-threads` flag:
* `cargo test -- --test-threads=1`
* This runs tests sequentially, one after another. Useful for debugging tests that might have race conditions or conflicts when run in parallel.
* `cargo test -- --test-threads=N`
* Runs tests using `N` threads.

6. Showing Test Output (e.g., `println!`):
* By default, Rust captures output (like `println!`) from passing tests and only displays it for failing tests. This keeps the test output clean.
* To see output from all tests (passing and failing), use the `--nocapture` (or `--show-output`) flag:
* `cargo test -- --nocapture`
* This is invaluable for debugging, as it allows you to print intermediate values or messages from within your test functions.

7. Passing Custom Arguments:
* Any arguments provided after `--` are passed directly to the test harness. This mechanism is how flags like `--ignored`, `--test-threads`, and `--nocapture` work. You can even define your own test arguments and parse them within your test code if needed, though this is less common.

8. Running Tests from a Specific Target Type:
* `cargo test --lib`: Runs only library tests.
* `cargo test --bin <binary_name>`: Runs tests within a specific binary target.
* `cargo test --test <integration_test_name>`: Runs tests from a specific integration test file (e.g., `tests/integration_test.rs` would be `--test integration_test`).

By understanding and utilizing these options, developers can tailor their test execution to fit their specific needs, leading to more efficient development and robust software.

```rust
// src/lib.rs

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

pub fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_add_two_numbers() {
        println!("Running test_add_two_numbers"); // Output captured by default
        assert_eq!(add(2, 2), 4);
    }

    #[test]
    fn test_add_zero() {
        assert_eq!(add(5, 0), 5);
    }

    #[test]
    #[ignore] // This test will be ignored by default
    fn expensive_or_flaky_test() {
        // Simulate a long-running or unreliable test
        println!("-> This expensive or flaky test is running!"); // Will only show with --nocapture or --ignored
        assert_eq!(multiply(10, 10), 100); // Imagine this could fail sometimes
    }

    #[test]
    fn test_multiply_numbers() {
        println!("Running test_multiply_numbers and demonstrating output."); // Output captured by default
        assert_eq!(multiply(3, 4), 12);
    }

    #[test]
    fn another_add_test_case() {
        assert_eq!(add(10, 20), 30);
    }

    #[test]
    fn test_panic_example() {
        // This test will fail
        // panic!("This test is designed to fail!");
        assert_eq!(1, 2, "This assert will fail to show failure output");
    }
}

/*

To run these tests and observe the control mechanisms, open your terminal in the project root:

1.  Run all tests (default):
    `cargo test`
    (Notice 'expensive_or_flaky_test' is skipped)

2.  Run only tests containing 'add':
    `cargo test add`
    (Will run 'test_add_two_numbers', 'test_add_zero', 'another_add_test_case')

3.  Run only tests containing 'multiply':
    `cargo test multiply`
    (Will run 'test_multiply_numbers', and 'expensive_or_flaky_test' if it wasn't ignored)

4.  Run all ignored tests:
    `cargo test -- --ignored`
    (Will run only 'expensive_or_flaky_test')

5.  Run specific ignored test with output:
    `cargo test -- --ignored expensive_or_flaky_test --nocapture`
    (You'll see "-> This expensive or flaky test is running!")

6.  Run all tests and show `println!` output from all tests (passing and failing):
    `cargo test -- --nocapture`
    (You'll see all "Running ..." messages and the panic output)

7.  Run tests sequentially (one thread):
    `cargo test -- --test-threads=1`

8.  Run a specific test with output:
    `cargo test test_multiply_numbers -- --nocapture`
    (You'll see "Running test_multiply_numbers and demonstrating output.")

*/
```