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