Testing

Table of Contents

Testing is fundamental to Rust.

Unit, integration, and documentation tests all come builtin.

Organizing Tests

Tests typically end up in 1 of 4 possible locations:

  • Immediately beside the functionality tested. (Unit test)

  • In a tests submodule. (Private integration test)

  • In documentation. (Documentation test)

  • In the tests/ directory. (Public integration test)

Unit Tests

  • Allows testing functionality in the same module and environment.

  • Typically exist immediately near the functionality.

  • Good for testing to make sure a single action works.

Unit Tests

enum Direction { North, South, East, West }

fn is_north(dir: Direction) -> bool {
    match dir {
        Direction::North => true,
        _ => false,
    }
}

#[test]
fn is_north_works() {
    assert!(is_north(Direction::North) == true);
    assert!(is_north(Direction::South) == false);
}

Unit Tests

$ cargo test
running 1 test
test is_north_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

tests Submodule

  • Allows testing as if the functionality is being used elsewhere in the project.

  • For testing private APIs and functionality.

  • Good for testing expected processes and use cases.

tests Submodule

enum Direction { North, South, East, West }

fn is_north(dir: Direction) -> bool {
    match dir {
        Direction::North => true,
        _ => false,
    }
}

#[cfg(test)]
mod tests {
    use super::{is_north, Direction};
    
    #[test]
    fn is_north_works() {
        assert!(is_north(Direction::North) == true);
        assert!(is_north(Direction::South) == false);
    }
}

tests Submodule

$ cargo test
running 1 test
test tests::is_north_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Documentation Tests

  • Allows testing public functionality.

  • Is displayed in rustdoc output.

  • For demonstrating expected use cases and examples.

Documentation Tests

/// ```rust
/// use example::Direction;
/// let way_home = Direction::North;
/// ```
pub enum Direction { North, South, East, West }

Documentation Tests

$ cargo test
running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

   Doc-tests example

running 1 test
test Direction_0 ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

Integration Tests

  • Tests as if the crate is an external dependency.

  • Intended for longer or full-function tests.

Integration Tests

/tests/basic.rs
use example::{is_north, Direction};

#[test]
fn is_north_works() {
    assert!(is_north(Direction::North) == true); (1)
    assert!(is_north(Direction::South) == false);
}

Integration Tests

$ cargo test
running 1 test
test is_north_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured

     Running target/debug/deps/example-9f39afa5d2a1c6bf

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured

   Doc-tests example

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured