src/doc/reference/src/attributes/testing.md

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