1. 1. Introduction
  2. 2. Getting Started
  3. 3. Tutorial: Guessing Game
  4. 4. Syntax and Semantics
    1. 4.1. Variable Bindings
    2. 4.2. Functions
    3. 4.3. Primitive Types
    4. 4.4. Comments
    5. 4.5. if
    6. 4.6. Loops
    7. 4.7. Vectors
    8. 4.8. Ownership
    9. 4.9. References and Borrowing
    10. 4.10. Lifetimes
    11. 4.11. Mutability
    12. 4.12. Structs
    13. 4.13. Enums
    14. 4.14. Match
    15. 4.15. Patterns
    16. 4.16. Method Syntax
    17. 4.17. Strings
    18. 4.18. Generics
    19. 4.19. Traits
    20. 4.20. Drop
    21. 4.21. if let
    22. 4.22. Trait Objects
    23. 4.23. Closures
    24. 4.24. Universal Function Call Syntax
    25. 4.25. Crates and Modules
    26. 4.26. `const` and `static`
    27. 4.27. Attributes
    28. 4.28. `type` aliases
    29. 4.29. Casting between types
    30. 4.30. Associated Types
    31. 4.31. Unsized Types
    32. 4.32. Operators and Overloading
    33. 4.33. Deref coercions
    34. 4.34. Macros
    35. 4.35. Raw Pointers
    36. 4.36. `unsafe`
  5. 5. Effective Rust
    1. 5.1. The Stack and the Heap
    2. 5.2. Testing
    3. 5.3. Conditional Compilation
    4. 5.4. Documentation
    5. 5.5. Iterators
    6. 5.6. Concurrency
    7. 5.7. Error Handling
    8. 5.8. Choosing your Guarantees
    9. 5.9. FFI
    10. 5.10. Borrow and AsRef
    11. 5.11. Release Channels
    12. 5.12. Using Rust without the standard library
  6. 6. Nightly Rust
    1. 6.1. Compiler Plugins
    2. 6.2. Inline Assembly
    3. 6.3. No stdlib
    4. 6.4. Intrinsics
    5. 6.5. Lang items
    6. 6.6. Advanced linking
    7. 6.7. Benchmark Tests
    8. 6.8. Box Syntax and Patterns
    9. 6.9. Slice Patterns
    10. 6.10. Associated Constants
    11. 6.11. Custom Allocators
  7. 7. Glossary
  8. 8. Syntax Index
  9. 9. Bibliography

Testing

Program testing can be a very effective way to show the presence of bugs, but it is hopelessly inadequate for showing their absence.

Edsger W. Dijkstra, "The Humble Programmer" (1972)

Let's talk about how to test Rust code. What we will not be talking about is the right way to test Rust code. There are many schools of thought regarding the right and wrong way to write tests. All of these approaches use the same basic tools, and so we'll show you the syntax for using them.

The test attribute

At its simplest, a test in Rust is a function that's annotated with the test attribute. Let's make a new project with Cargo called adder:

$ cargo new adder
$ cd adder

Cargo will automatically generate a simple test when you make a new project. Here's the contents of src/lib.rs:

#[cfg(test)]
mod tests {
    #[test]
    fn it_works() {
    }
}Run

Note the #[test]. This attribute indicates that this is a test function. It currently has no body. That's good enough to pass! We can run the tests with cargo test:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

   Doc-tests adder

running 0 tests

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

Cargo compiled and ran our tests. There are two sets of output here: one for the test we wrote, and another for documentation tests. We'll talk about those later. For now, see this line:

test tests::it_works ... ok

Note the it_works. This comes from the name of our function:

fn it_works() {Run

We also get a summary line:

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

So why does our do-nothing test pass? Any test which doesn't panic! passes, and any test that does panic! fails. Let's make our test fail:

#[test]
fn it_works() {
    assert!(false);
}Run

assert! is a macro provided by Rust which takes one argument: if the argument is true, nothing happens. If the argument is false, it will panic!. Let's run our tests again:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... FAILED

failures:

---- test::it_works stdout ----
        thread 'tests::it_works' panicked at 'assertion failed: false', src/lib.rs:5


failures:
    tests::it_works

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

error: test failed

Rust indicates that our test failed:

test tests::it_works ... FAILED

And that's reflected in the summary line:

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

We also get a non-zero status code. We can use $? on OS X and Linux:

$ echo $?
101

On Windows, if you’re using cmd:

> echo %ERRORLEVEL%

And if you’re using PowerShell:

> echo $LASTEXITCODE # the code itself
> echo $? # a boolean, fail or succeed

This is useful if you want to integrate cargo test into other tooling.

We can invert our test's failure with another attribute: should_panic:

#[test]
#[should_panic]
fn it_works() {
    assert!(false);
}Run

This test will now succeed if we panic! and fail if we complete. Let's try it:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

   Doc-tests adder

running 0 tests

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

Rust provides another macro, assert_eq!, that compares two arguments for equality:

#[test]
#[should_panic]
fn it_works() {
    assert_eq!("Hello", "world");
}Run

Does this test pass or fail? Because of the should_panic attribute, it passes:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

   Doc-tests adder

running 0 tests

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

should_panic tests can be fragile, as it's hard to guarantee that the test didn't fail for an unexpected reason. To help with this, an optional expected parameter can be added to the should_panic attribute. The test harness will make sure that the failure message contains the provided text. A safer version of the example above would be:

#[test]
#[should_panic(expected = "assertion failed")]
fn it_works() {
    assert_eq!("Hello", "world");
}Run

That's all there is to the basics! Let's write one 'real' test:

pub fn add_two(a: i32) -> i32 {
    a + 2
}

#[test]
fn it_works() {
    assert_eq!(4, add_two(2));
}Run

This is a very common use of assert_eq!: call some function with some known arguments and compare it to the expected output.

The ignore attribute

Sometimes a few specific tests can be very time-consuming to execute. These can be disabled by default by using the ignore attribute:

#[test]
fn it_works() {
    assert_eq!(4, add_two(2));
}

#[test]
#[ignore]
fn expensive_test() {
    // code that takes an hour to run
}Run

Now we run our tests and see that it_works is run, but expensive_test is not:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 2 tests
test expensive_test ... ignored
test it_works ... ok

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

   Doc-tests adder

running 0 tests

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

The expensive tests can be run explicitly using cargo test -- --ignored:

$ cargo test -- --ignored
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test expensive_test ... ok

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

   Doc-tests adder

running 0 tests

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

The --ignored argument is an argument to the test binary, and not to Cargo, which is why the command is cargo test -- --ignored.

The tests module

There is one way in which our existing example is not idiomatic: it's missing the tests module. You might have noticed this test module was present in the code that was initially generated with cargo new but was missing from our last example. Let's explain what this does.

The idiomatic way of writing our example looks like this:

pub fn add_two(a: i32) -> i32 {
    a + 2
}

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

    #[test]
    fn it_works() {
        assert_eq!(4, add_two(2));
    }
}Run

There's a few changes here. The first is the introduction of a mod tests with a cfg attribute. The module allows us to group all of our tests together, and to also define helper functions if needed, that don't become a part of the rest of our crate. The cfg attribute only compiles our test code if we're currently trying to run the tests. This can save compile time, and also ensures that our tests are entirely left out of a normal build.

The second change is the use declaration. Because we're in an inner module, we need to bring our test function into scope. This can be annoying if you have a large module, and so this is a common use of globs. Let's change our src/lib.rs to make use of it:

pub fn add_two(a: i32) -> i32 {
    a + 2
}

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

    #[test]
    fn it_works() {
        assert_eq!(4, add_two(2));
    }
}Run

Note the different use line. Now we run our tests:

$ cargo test
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

   Doc-tests adder

running 0 tests

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

It works!

The current convention is to use the tests module to hold your "unit-style" tests. Anything that tests one small bit of functionality makes sense to go here. But what about "integration-style" tests instead? For that, we have the tests directory.

The tests directory

Each file in tests/*.rs directory is treated as an individual crate. To write an integration test, let's make a tests directory and put a tests/integration_test.rs file inside with this as its contents:

extern crate adder;

#[test]
fn it_works() {
    assert_eq!(4, adder::add_two(2));
}Run

This looks similar to our previous tests, but slightly different. We now have an extern crate adder at the top. This is because each test in the tests directory is an entirely separate crate, and so we need to import our library. This is also why tests is a suitable place to write integration-style tests: they use the library like any other consumer of it would.

Let's run them:

$ cargo test
   Compiling adder v0.1.0 (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

     Running target/debug/integration_test-68064b69521c828a

running 1 test
test it_works ... ok

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

   Doc-tests adder

running 0 tests

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

Now we have three sections: our previous test is also run, as well as our new one.

Cargo will ignore files in subdirectories of the tests/ directory. Therefore shared modules in integrations tests are possible. For example tests/common/mod.rs is not separately compiled by cargo but can be imported in every test with mod common;

That's all there is to the tests directory. The tests module isn't needed here, since the whole thing is focused on tests.

Let's finally check out that third section: documentation tests.

Documentation tests

Nothing is better than documentation with examples. Nothing is worse than examples that don't actually work, because the code has changed since the documentation has been written. To this end, Rust supports automatically running examples in your documentation (note: this only works in library crates, not binary crates). Here's a fleshed-out src/lib.rs with examples:

//! The `adder` crate provides functions that add numbers to other numbers.
//!
//! # Examples
//!
//! ```
//! assert_eq!(4, adder::add_two(2));
//! ```

/// This function adds two to its argument.
///
/// # Examples
///
/// ```
/// use adder::add_two;
///
/// assert_eq!(4, add_two(2));
/// ```
pub fn add_two(a: i32) -> i32 {
    a + 2
}

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

    #[test]
    fn it_works() {
        assert_eq!(4, add_two(2));
    }
}Run

Note the module-level documentation with //! and the function-level documentation with ///. Rust's documentation supports Markdown in comments, and so triple graves mark code blocks. It is conventional to include the # Examples section, exactly like that, with examples following.

Let's run the tests again:

$ cargo test
   Compiling adder v0.1.0. (file:///home/you/projects/adder)
     Running target/debug/deps/adder-91b3e234d4ed382a

running 1 test
test tests::it_works ... ok

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

     Running target/debug/integration_test-68064b69521c828a

running 1 test
test it_works ... ok

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

   Doc-tests adder

running 2 tests
test add_two_0 ... ok
test _0 ... ok

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

Now we have all three kinds of tests running! Note the names of the documentation tests: the _0 is generated for the module test, and add_two_0 for the function test. These will auto increment with names like add_two_1 as you add more examples.

We haven’t covered all of the details with writing documentation tests. For more, please see the Documentation chapter.