1# Testing attributes 2 3The following [attributes] are used for specifying functions for performing 4tests. Compiling a crate in "test" mode enables building the test functions 5along with a test harness for executing the tests. Enabling the test mode also 6enables the [`test` conditional compilation option]. 7 8## The `test` attribute 9 10The *`test` attribute* marks a function to be executed as a test. These 11functions are only compiled when in test mode. Test functions must be free, 12monomorphic functions that take no arguments, and the return type must be one 13of the following: 14 15* `()` 16* `Result<(), E> where E: Error` 17<!-- * `!` --> 18<!-- * Result<!, E> where E: Error` --> 19 20> Note: The implementation of which return types are allowed is determined by 21> the unstable [`Termination`] trait. 22 23<!-- If the previous section needs updating (from "must take no arguments" 24 onwards, also update it in the crates-and-source-files.md file --> 25 26> Note: The test mode is enabled by passing the `--test` argument to `rustc` 27> or using `cargo test`. 28 29Tests that return `()` pass as long as they terminate and do not panic. Tests 30that return a `Result<(), E>` pass as long as they return `Ok(())`. Tests that 31do not terminate neither pass nor fail. 32 33```rust 34# use std::io; 35# fn setup_the_thing() -> io::Result<i32> { Ok(1) } 36# fn do_the_thing(s: &i32) -> io::Result<()> { Ok(()) } 37#[test] 38fn test_the_thing() -> io::Result<()> { 39 let state = setup_the_thing()?; // expected to succeed 40 do_the_thing(&state)?; // expected to succeed 41 Ok(()) 42} 43``` 44 45## The `ignore` attribute 46 47A function annotated with the `test` attribute can also be annotated with the 48`ignore` attribute. The *`ignore` attribute* tells the test harness to not 49execute that function as a test. It will still be compiled when in test mode. 50 51The `ignore` attribute may optionally be written with the [_MetaNameValueStr_] 52syntax to specify a reason why the test is ignored. 53 54```rust 55#[test] 56#[ignore = "not yet implemented"] 57fn mytest() { 58 // … 59} 60``` 61 62> **Note**: The `rustc` test harness supports the `--include-ignored` flag to 63> force ignored tests to be run. 64 65## The `should_panic` attribute 66 67A function annotated with the `test` attribute that returns `()` can also be 68annotated with the `should_panic` attribute. The *`should_panic` attribute* 69makes the test only pass if it actually panics. 70 71The `should_panic` attribute may optionally take an input string that must 72appear within the panic message. If the string is not found in the message, 73then the test will fail. The string may be passed using the 74[_MetaNameValueStr_] syntax or the [_MetaListNameValueStr_] syntax with an 75`expected` field. 76 77```rust 78#[test] 79#[should_panic(expected = "values don't match")] 80fn mytest() { 81 assert_eq!(1, 2, "values don't match"); 82} 83``` 84 85[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax 86[_MetaNameValueStr_]: ../attributes.md#meta-item-attribute-syntax 87[`Termination`]: ../../std/process/trait.Termination.html 88[`test` conditional compilation option]: ../conditional-compilation.md#test 89[attributes]: ../attributes.md 90