summaryrefslogtreecommitdiffstats
path: root/src/doc/book/nostarch/chapter11.md
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/doc/book/nostarch/chapter11.md476
1 files changed, 261 insertions, 215 deletions
diff --git a/src/doc/book/nostarch/chapter11.md b/src/doc/book/nostarch/chapter11.md
index ea4ffe5bf..cf909d70c 100644
--- a/src/doc/book/nostarch/chapter11.md
+++ b/src/doc/book/nostarch/chapter11.md
@@ -33,11 +33,12 @@ We can write tests that assert, for example, that when we pass `3` to the
we make changes to our code to make sure any existing correct behavior has not
changed.
-Testing is a complex skill: although we can’t cover every detail about how to
-write good tests in one chapter, we’ll discuss the mechanics of Rust’s testing
-facilities. We’ll talk about the annotations and macros available to you when
-writing your tests, the default behavior and options provided for running your
-tests, and how to organize tests into unit tests and integration tests.
+Testing is a complex skill: although we can’t cover in one chapter every detail
+about how to write good tests, in this chapter we will discuss the mechanics of
+Rust’s testing facilities. We’ll talk about the annotations and macros
+available to you when writing your tests, the default behavior and options
+provided for running your tests, and how to organize tests into unit tests and
+integration tests.
## How to Write Tests
@@ -45,9 +46,9 @@ Tests are Rust functions that verify that the non-test code is functioning in
the expected manner. The bodies of test functions typically perform these three
actions:
-1. Set up any needed data or state.
-2. Run the code you want to test.
-3. Assert the results are what you expect.
+* Set up any needed data or state.
+* Run the code you want to test.
+* Assert that the results are what you expect.
Let’s look at the features Rust provides specifically for writing tests that
take these actions, which include the `test` attribute, a few macros, and the
@@ -60,8 +61,8 @@ attribute. Attributes are metadata about pieces of Rust code; one example is
the `derive` attribute we used with structs in Chapter 5. To change a function
into a test function, add `#[test]` on the line before `fn`. When you run your
tests with the `cargo test` command, Rust builds a test runner binary that runs
-the annotated functions and reports on whether each
-test function passes or fails.
+the annotated functions and reports on whether each test function passes or
+fails.
Whenever we make a new library project with Cargo, a test module with a test
function in it is automatically generated for us. This module gives you a
@@ -89,10 +90,10 @@ Filename: src/lib.rs
```
#[cfg(test)]
mod tests {
-[1] #[test]
+ 1 #[test]
fn it_works() {
let result = 2 + 2;
- [2] assert_eq!(result, 4);
+ 2 assert_eq!(result, 4);
}
}
```
@@ -119,19 +120,21 @@ The `cargo test` command runs all tests in our project, as shown in Listing
$ cargo test
Compiling adder v0.1.0 (file:///projects/adder)
Finished test [unoptimized + debuginfo] target(s) in 0.57s
- Running unittests (target/debug/deps/adder-92948b65e88960b4)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+92948b65e88960b4)
-[1] running 1 test
-[2] test tests::it_works ... ok
+1 running 1 test
+2 test tests::it_works ... ok
-[3] test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+3 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
-[4] Doc-tests adder
+ 4 Doc-tests adder
running 0 tests
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
-
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Listing 11-2: The output from running the automatically generated test
@@ -143,13 +146,12 @@ ok.` [3] means that all the tests passed, and the portion that reads `1 passed;
0 failed` totals the number of tests that passed or failed.
It’s possible to mark a test as ignored so it doesn’t run in a particular
-instance; we’ll cover that in the “Ignoring Some Tests Unless Specifically
-Requested” section later in this chapter. Because we haven’t done that here,
-the summary shows `0 ignored`. We can also pass an argument to the `cargo test`
-command to run only tests whose name matches a string; this is called *filtering*
-and we’ll cover that in the “Running a Subset of Tests by Name” section.
-Here we haven’t filtered the tests being run, so the end of the summary shows `0
-filtered out`.
+instance; we’ll cover that in “Ignoring Some Tests Unless Specifically
+Requested” on page XX. Because we haven’t done that here, the summary shows `0
+ignored`. We can also pass an argument to the `cargo test` command to run only
+tests whose name matches a string; this is called *filtering* and we’ll cover
+it in “Running a Subset of Tests by Name” on page XX. Here we haven’t filtered
+the tests being run, so the end of the summary shows `0 filtered out`.
The `0 measured` statistic is for benchmark tests that measure performance.
Benchmark tests are, as of this writing, only available in nightly Rust. See
@@ -161,10 +163,10 @@ The next part of the test output starting at `Doc-tests adder` [4] is for the
results of any documentation tests. We don’t have any documentation tests yet,
but Rust can compile any code examples that appear in our API documentation.
This feature helps keep your docs and your code in sync! We’ll discuss how to
-write documentation tests in the “Documentation Comments as Tests” section of
-Chapter 14. For now, we’ll ignore the `Doc-tests` output.
+write documentation tests in “Documentation Comments as Tests” on page XX. For
+now, we’ll ignore the `Doc-tests` output.
-Let’s start to customize the test to our own needs. First change the name of
+Let’s start to customize the test to our own needs. First, change the name of
the `it_works` function to a different name, such as `exploration`, like so:
Filename: src/lib.rs
@@ -174,7 +176,8 @@ Filename: src/lib.rs
mod tests {
#[test]
fn exploration() {
- assert_eq!(2 + 2, 4);
+ let result = 2 + 2;
+ assert_eq!(result, 4);
}
}
```
@@ -186,7 +189,8 @@ Then run `cargo test` again. The output now shows `exploration` instead of
running 1 test
test tests::exploration ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Now we’ll add another test, but this time we’ll make a test that fails! Tests
@@ -222,18 +226,20 @@ Run the tests again using `cargo test`. The output should look like Listing
```
running 2 tests
test tests::exploration ... ok
-[1] test tests::another ... FAILED
+1 test tests::another ... FAILED
-[2] failures:
+2 failures:
---- tests::another stdout ----
thread 'main' panicked at 'Make this test fail', src/lib.rs:10:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
-[3] failures:
+3 failures:
tests::another
-[4] test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+4 test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
error: test failed, to rerun pass '--lib'
```
@@ -248,7 +254,7 @@ line 10 in the *src/lib.rs* file. The next section [3] lists just the names of
all the failing tests, which is useful when there are lots of tests and lots of
detailed failing test output. We can use the name of a failing test to run just
that test to more easily debug it; we’ll talk more about ways to run tests in
-the “Controlling How Tests Are Run” section.
+“Controlling How Tests Are Run” on page XX.
The summary line displays at the end [4]: overall, our test result is `FAILED`.
We had one test pass and one test fail.
@@ -256,7 +262,7 @@ We had one test pass and one test fail.
Now that you’ve seen what the test results look like in different scenarios,
let’s look at some macros other than `panic!` that are useful in tests.
-### Checking Results with the `assert!` Macro
+### Checking Results with the assert! Macro
The `assert!` macro, provided by the standard library, is useful when you want
to ensure that some condition in a test evaluates to `true`. We give the
@@ -265,9 +271,9 @@ to ensure that some condition in a test evaluates to `true`. We give the
`assert!` macro calls `panic!` to cause the test to fail. Using the `assert!`
macro helps us check that our code is functioning in the way we intend.
-In Chapter 5, Listing 5-15, we used a `Rectangle` struct and a `can_hold`
-method, which are repeated here in Listing 11-5. Let’s put this code in the
-*src/lib.rs* file, then write some tests for it using the `assert!` macro.
+In Listing 5-15, we used a `Rectangle` struct and a `can_hold` method, which
+are repeated here in Listing 11-5. Let’s put this code in the *src/lib.rs*
+file, then write some tests for it using the `assert!` macro.
Filename: src/lib.rs
@@ -299,11 +305,11 @@ Filename: src/lib.rs
```
#[cfg(test)]
mod tests {
-[1] use super::*;
+ 1 use super::*;
#[test]
-[2] fn larger_can_hold_smaller() {
- [3] let larger = Rectangle {
+ 2 fn larger_can_hold_smaller() {
+ 3 let larger = Rectangle {
width: 8,
height: 7,
};
@@ -312,7 +318,7 @@ mod tests {
height: 1,
};
- [4] assert!(larger.can_hold(&smaller));
+ 4 assert!(larger.can_hold(&smaller));
}
}
```
@@ -322,11 +328,11 @@ indeed hold a smaller rectangle
Note that we’ve added a new line inside the `tests` module: `use super::*;`
[1]. The `tests` module is a regular module that follows the usual visibility
-rules we covered in Chapter 7 in the “Paths for Referring to an Item in the
-Module Tree” section. Because the `tests` module is an inner module, we need to
-bring the code under test in the outer module into the scope of the inner
-module. We use a glob here so anything we define in the outer module is
-available to this `tests` module.
+rules we covered in “Paths for Referring to an Item in the Module Tree” on page
+XX. Because the `tests` module is an inner module, we need to bring the code
+under test in the outer module into the scope of the inner module. We use a
+glob here, so anything we define in the outer module is available to this
+`tests` module.
We’ve named our test `larger_can_hold_smaller` [2], and we’ve created the two
`Rectangle` instances that we need [3]. Then we called the `assert!` macro and
@@ -338,7 +344,8 @@ out!
running 1 test
test tests::larger_can_hold_smaller ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
It does pass! Let’s add another test, this time asserting that a smaller
@@ -353,7 +360,7 @@ mod tests {
#[test]
fn larger_can_hold_smaller() {
- // --snip--
+ --snip--
}
#[test]
@@ -381,7 +388,8 @@ running 2 tests
test tests::larger_can_hold_smaller ... ok
test tests::smaller_cannot_hold_larger ... ok
-test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Two tests that pass! Now let’s see what happens to our test results when we
@@ -390,7 +398,8 @@ method by replacing the greater-than sign with a less-than sign when it
compares the widths:
```
-// --snip--
+--snip--
+
impl Rectangle {
fn can_hold(&self, other: &Rectangle) -> bool {
self.width < other.width && self.height > other.height
@@ -408,26 +417,29 @@ test tests::larger_can_hold_smaller ... FAILED
failures:
---- tests::larger_can_hold_smaller stdout ----
-thread 'main' panicked at 'assertion failed: larger.can_hold(&smaller)', src/lib.rs:28:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+thread 'main' panicked at 'assertion failed:
+larger.can_hold(&smaller)', src/lib.rs:28:9
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
failures:
tests::larger_can_hold_smaller
-test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
-Our tests caught the bug! Because `larger.width` is 8 and `smaller.width` is
-5, the comparison of the widths in `can_hold` now returns `false`: 8 is not
+Our tests caught the bug! Because `larger.width` is `8` and `smaller.width` is
+`5`, the comparison of the widths in `can_hold` now returns `false`: 8 is not
less than 5.
-### Testing Equality with the `assert_eq!` and `assert_ne!` Macros
+### Testing Equality with the assert_eq! and assert_ne! Macros
A common way to verify functionality is to test for equality between the result
of the code under test and the value you expect the code to return. You could
-do this using the `assert!` macro and passing it an expression using the `==`
-operator. However, this is such a common test that the standard library
+do this by using the `assert!` macro and passing it an expression using the
+`==` operator. However, this is such a common test that the standard library
provides a pair of macros—`assert_eq!` and `assert_ne!`—to perform this test
more conveniently. These macros compare two arguments for equality or
inequality, respectively. They’ll also print the two values if the assertion
@@ -464,7 +476,8 @@ Let’s check that it passes!
running 1 test
test tests::it_adds_two ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
We pass `4` as the argument to `assert_eq!`, which is equal to the result of
@@ -489,23 +502,25 @@ test tests::it_adds_two ... FAILED
failures:
---- tests::it_adds_two stdout ----
-[1] thread 'main' panicked at 'assertion failed: `(left == right)`
-[2] left: `4`,
-[3] right: `5`', src/lib.rs:11:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+1 thread 'main' panicked at 'assertion failed: `(left == right)`
+2 left: `4`,
+3 right: `5`', src/lib.rs:11:9
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
failures:
tests::it_adds_two
-test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Our test caught the bug! The `it_adds_two` test failed, and the message tells
-us that the assertion that fails was `` assertion failed: `(left == right)` ``
-[1] and what the `left` [2] and `right` [3] values are. This message helps us
-start debugging: the `left` argument was `4` but the `right` argument, where we
-had `add_two(2)`, was `5`. You can imagine that this would be especially
-helpful when we have a lot of tests going on.
+us that the assertion that failed was `assertion failed: `(left == right)`` [1]
+and what the `left` [2] and `right` [3] values are. This message helps us start
+debugging: the `left` argument was `4` but the `right` argument, where we had
+`add_two(2)`, was `5`. You can imagine that this would be especially helpful
+when we have a lot of tests going on.
Note that in some languages and test frameworks, the parameters to equality
assertion functions are called `expected` and `actual`, and the order in which
@@ -513,7 +528,7 @@ we specify the arguments matters. However, in Rust, they’re called `left` and
`right`, and the order in which we specify the value we expect and the value
the code produces doesn’t matter. We could write the assertion in this test as
`assert_eq!(add_two(2), 4)`, which would result in the same failure message
-that displays `` assertion failed: `(left == right)` ``.
+that displays `assertion failed: `(left == right)``.
The `assert_ne!` macro will pass if the two values we give it are not equal and
fail if they’re equal. This macro is most useful for cases when we’re not sure
@@ -531,21 +546,20 @@ the standard library types implement these traits. For structs and enums that
you define yourself, you’ll need to implement `PartialEq` to assert equality of
those types. You’ll also need to implement `Debug` to print the values when the
assertion fails. Because both traits are derivable traits, as mentioned in
-Listing 5-12 in Chapter 5, this is usually as straightforward as adding the
+Listing 5-12, this is usually as straightforward as adding the
`#[derive(PartialEq, Debug)]` annotation to your struct or enum definition. See
-Appendix C, “Derivable Traits,” for more details about these and other
-derivable traits.
+Appendix C for more details about these and other derivable traits.
### Adding Custom Failure Messages
You can also add a custom message to be printed with the failure message as
optional arguments to the `assert!`, `assert_eq!`, and `assert_ne!` macros. Any
arguments specified after the required arguments are passed along to the
-`format!` macro (discussed in Chapter 8 in the “Concatenation with the `+`
-Operator or the `format!` Macro” section), so you can pass a format string that
-contains `{}` placeholders and values to go in those placeholders. Custom
-messages are useful for documenting what an assertion means; when a test fails,
-you’ll have a better idea of what the problem is with the code.
+`format!` macro (discussed in “Concatenation with the + Operator or the format!
+Macro” on page XX), so you can pass a format string that contains `{}`
+placeholders and values to go in those placeholders. Custom messages are useful
+for documenting what an assertion means; when a test fails, you’ll have a
+better idea of what the problem is with the code.
For example, let’s say we have a function that greets people by name and we
want to test that the name we pass into the function appears in the output:
@@ -554,7 +568,7 @@ Filename: src/lib.rs
```
pub fn greeting(name: &str) -> String {
- format!("Hello {}!", name)
+ format!("Hello {name}!")
}
#[cfg(test)]
@@ -594,8 +608,10 @@ test tests::greeting_contains_name ... FAILED
failures:
---- tests::greeting_contains_name stdout ----
-thread 'main' panicked at 'assertion failed: result.contains(\"Carol\")', src/lib.rs:12:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+thread 'main' panicked at 'assertion failed:
+result.contains(\"Carol\")', src/lib.rs:12:9
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
failures:
@@ -614,8 +630,7 @@ fn greeting_contains_name() {
let result = greeting("Carol");
assert!(
result.contains("Carol"),
- "Greeting did not contain name, value was `{}`",
- result
+ "Greeting did not contain name, value was `{result}`"
);
}
```
@@ -624,21 +639,23 @@ Now when we run the test, we’ll get a more informative error message:
```
---- tests::greeting_contains_name stdout ----
-thread 'main' panicked at 'Greeting did not contain name, value was `Hello!`', src/lib.rs:12:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+thread 'main' panicked at 'Greeting did not contain name, value
+was `Hello!`', src/lib.rs:12:9
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
```
We can see the value we actually got in the test output, which would help us
debug what happened instead of what we were expecting to happen.
-### Checking for Panics with `should_panic`
+### Checking for Panics with should_panic
In addition to checking return values, it’s important to check that our code
handles error conditions as we expect. For example, consider the `Guess` type
-that we created in Chapter 9, Listing 9-13. Other code that uses `Guess`
-depends on the guarantee that `Guess` instances will contain only values
-between 1 and 100. We can write a test that ensures that attempting to create a
-`Guess` instance with a value outside that range panics.
+that we created in Listing 9-13. Other code that uses `Guess` depends on the
+guarantee that `Guess` instances will contain only values between 1 and 100. We
+can write a test that ensures that attempting to create a `Guess` instance with
+a value outside that range panics.
We do this by adding the attribute `should_panic` to our test function. The
test passes if the code inside the function panics; the test fails if the code
@@ -647,9 +664,8 @@ inside the function doesn’t panic.
Listing 11-8 shows a test that checks that the error conditions of `Guess::new`
happen when we expect them to.
-Filename: src/lib.rs
-
```
+// src/lib.rs
pub struct Guess {
value: i32,
}
@@ -657,7 +673,10 @@ pub struct Guess {
impl Guess {
pub fn new(value: i32) -> Guess {
if value < 1 || value > 100 {
- panic!("Guess value must be between 1 and 100, got {}.", value);
+ panic!(
+ "Guess value must be between 1 and 100, got {}.",
+ value
+ );
}
Guess { value }
@@ -676,7 +695,7 @@ mod tests {
}
```
-Listing 11-8: Testing that a condition will cause a `panic!`
+Listing 11-8: Testing that a condition will cause a panic!
We place the `#[should_panic]` attribute after the `#[test]` attribute and
before the test function it applies to. Let’s look at the result when this test
@@ -686,18 +705,24 @@ passes:
running 1 test
test tests::greater_than_100 - should panic ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Looks good! Now let’s introduce a bug in our code by removing the condition
that the `new` function will panic if the value is greater than 100:
```
-// --snip--
+// src/lib.rs
+--snip--
+
impl Guess {
pub fn new(value: i32) -> Guess {
if value < 1 {
- panic!("Guess value must be between 1 and 100, got {}.", value);
+ panic!(
+ "Guess value must be between 1 and 100, got {}.",
+ value
+ );
}
Guess { value }
@@ -719,7 +744,8 @@ note: test did not panic as expected
failures:
tests::greater_than_100
-test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
We don’t get a very helpful message in this case, but when we look at the test
@@ -735,10 +761,9 @@ consider the modified code for `Guess` in Listing 11-9 where the `new` function
panics with different messages depending on whether the value is too small or
too large.
-Filename: src/lib.rs
-
```
-// --snip--
+// src/lib.rs
+--snip--
impl Guess {
pub fn new(value: i32) -> Guess {
@@ -777,32 +802,30 @@ This test will pass because the value we put in the `should_panic` attribute’s
`expected` parameter is a substring of the message that the `Guess::new`
function panics with. We could have specified the entire panic message that we
expect, which in this case would be `Guess value must be less than or equal to
-100, got 200.` What you choose to specify depends on how much of the panic
+100, got 200`. What you choose to specify depends on how much of the panic
message is unique or dynamic and how precise you want your test to be. In this
case, a substring of the panic message is enough to ensure that the code in the
test function executes the `else if value > 100` case.
-<!---
-We may want to make extra clear above that `expected` here means substring. I
-think many people would assume equality rather than substring like the
-expected/actual of unit tests.
-
-(let alone how .expect(..) works. It seems we use the word expect in different
-ways around the language/library )
-/JT --->
-<!-- I've changed the example to be more clearly a substring specified, and
-changed the caption as well. Hope that makes it extra clear! /Carol -->
-
To see what happens when a `should_panic` test with an `expected` message
fails, let’s again introduce a bug into our code by swapping the bodies of the
`if value < 1` and the `else if value > 100` blocks:
```
+// src/lib.rs
+--snip--
if value < 1 {
- panic!("Guess value must be less than or equal to 100, got {}.", value);
+ panic!(
+ "Guess value must be less than or equal to 100, got {}.",
+ value
+ );
} else if value > 100 {
- panic!("Guess value must be greater than or equal to 1, got {}.", value);
+ panic!(
+ "Guess value must be greater than or equal to 1, got {}.",
+ value
+ );
}
+--snip--
```
This time when we run the `should_panic` test, it will fail:
@@ -814,30 +837,35 @@ test tests::greater_than_100 - should panic ... FAILED
failures:
---- tests::greater_than_100 stdout ----
-thread 'main' panicked at 'Guess value must be greater than or equal to 1, got 200.', src/lib.rs:13:13
+thread 'main' panicked at 'Guess value must be greater than or equal to 1, got
+200.', src/lib.rs:13:13
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
note: panic did not contain expected string
- panic message: `"Guess value must be greater than or equal to 1, got 200."`,
+ panic message: `"Guess value must be greater than or equal to 1, got
+200."`,
expected substring: `"less than or equal to 100"`
failures:
tests::greater_than_100
-test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out;
+finished in 0.00s
```
The failure message indicates that this test did indeed panic as we expected,
but the panic message did not include the expected string `'Guess value must be
less than or equal to 100'`. The panic message that we did get in this case was
-`Guess value must be greater than or equal to 1, got 200.` Now we can start
+`Guess value must be greater than or equal to 1, got 200`. Now we can start
figuring out where our bug is!
-### Using `Result<T, E>` in Tests
+### Using Result<T, E> in Tests
Our tests so far all panic when they fail. We can also write tests that use
`Result<T, E>`! Here’s the test from Listing 11-1, rewritten to use `Result<T,
E>` and return an `Err` instead of panicking:
+Filename: src/lib.rs
+
```
#[cfg(test)]
mod tests {
@@ -872,15 +900,15 @@ test`.
## Controlling How Tests Are Run
-Just as `cargo run` compiles your code and then runs the resulting binary,
-`cargo test` compiles your code in test mode and runs the resulting test
+Just as `cargo run` compiles your code and then runs the resultant binary,
+`cargo test` compiles your code in test mode and runs the resultant test
binary. The default behavior of the binary produced by `cargo test` is to run
all the tests in parallel and capture output generated during test runs,
preventing the output from being displayed and making it easier to read the
output related to the test results. You can, however, specify command line
options to change this default behavior.
-Some command line options go to `cargo test`, and some go to the resulting test
+Some command line options go to `cargo test`, and some go to the resultant test
binary. To separate these two types of arguments, you list the arguments that
go to `cargo test` followed by the separator `--` and then the ones that go to
the test binary. Running `cargo test --help` displays the options you can use
@@ -934,7 +962,7 @@ Filename: src/lib.rs
```
fn prints_and_returns_10(a: i32) -> i32 {
- println!("I got the value {}", a);
+ println!("I got the value {a}");
10
}
@@ -968,16 +996,18 @@ test tests::this_test_will_fail ... FAILED
failures:
---- tests::this_test_will_fail stdout ----
-[1] I got the value 8
+1 I got the value 8
thread 'main' panicked at 'assertion failed: `(left == right)`
left: `5`,
right: `10`', src/lib.rs:19:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
failures:
tests::this_test_will_fail
-test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Note that nowhere in this output do we see `I got the value 4`, which is
@@ -986,8 +1016,8 @@ output from the test that failed, `I got the value 8` [1], appears in the
section of the test summary output, which also shows the cause of the test
failure.
-If we want to see printed values for passing tests as well, we can tell Rust
-to also show the output of successful tests with `--show-output`.
+If we want to see printed values for passing tests as well, we can tell Rust to
+also show the output of successful tests with `--show-output`:
```
$ cargo test -- --show-output
@@ -1017,12 +1047,14 @@ I got the value 8
thread 'main' panicked at 'assertion failed: `(left == right)`
left: `5`,
right: `10`', src/lib.rs:19:9
-note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+note: run with `RUST_BACKTRACE=1` environment variable to display
+a backtrace
failures:
tests::this_test_will_fail
-test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
### Running a Subset of Tests by Name
@@ -1074,7 +1106,8 @@ test tests::add_three_and_two ... ok
test tests::add_two_and_two ... ok
test tests::one_hundred ... ok
-test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
#### Running Single Tests
@@ -1085,12 +1118,14 @@ We can pass the name of any test function to `cargo test` to run only that test:
$ cargo test one_hundred
Compiling adder v0.1.0 (file:///projects/adder)
Finished test [unoptimized + debuginfo] target(s) in 0.69s
- Running unittests (target/debug/deps/adder-92948b65e88960b4)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+92948b65e88960b4)
running 1 test
test tests::one_hundred ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2
+filtered out; finished in 0.00s
```
Only the test with the name `one_hundred` ran; the other two tests didn’t match
@@ -1110,13 +1145,15 @@ run those two by running `cargo test add`:
$ cargo test add
Compiling adder v0.1.0 (file:///projects/adder)
Finished test [unoptimized + debuginfo] target(s) in 0.61s
- Running unittests (target/debug/deps/adder-92948b65e88960b4)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+92948b65e88960b4)
running 2 tests
test tests::add_three_and_two ... ok
test tests::add_two_and_two ... ok
-test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s
+test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1
+filtered out; finished in 0.00s
```
This command ran all tests with `add` in the name and filtered out the test
@@ -1137,7 +1174,8 @@ Filename: src/lib.rs
```
#[test]
fn it_works() {
- assert_eq!(2 + 2, 4);
+ let result = 2 + 2;
+ assert_eq!(result, 4);
}
#[test]
@@ -1147,20 +1185,22 @@ fn expensive_test() {
}
```
-After `#[test]` we add the `#[ignore]` line to the test we want to exclude. Now
-when we run our tests, `it_works` runs, but `expensive_test` doesn’t:
+After `#[test]`, we add the `#[ignore]` line to the test we want to exclude.
+Now when we run our tests, `it_works` runs, but `expensive_test` doesn’t:
```
$ cargo test
Compiling adder v0.1.0 (file:///projects/adder)
Finished test [unoptimized + debuginfo] target(s) in 0.60s
- Running unittests (target/debug/deps/adder-92948b65e88960b4)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+92948b65e88960b4)
running 2 tests
test expensive_test ... ignored
test it_works ... ok
-test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
The `expensive_test` function is listed as `ignored`. If we want to run only
@@ -1169,19 +1209,21 @@ the ignored tests, we can use `cargo test -- --ignored`:
```
$ cargo test -- --ignored
Finished test [unoptimized + debuginfo] target(s) in 0.61s
- Running unittests (target/debug/deps/adder-92948b65e88960b4)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+92948b65e88960b4)
running 1 test
test expensive_test ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1
+filtered out; finished in 0.00s
```
By controlling which tests run, you can make sure your `cargo test` results
-will be fast. When you’re at a point where it makes sense to check the results
-of the `ignored` tests and you have time to wait for the results, you can run
-`cargo test -- --ignored` instead. If you want to run all tests whether they’re
-ignored or not, you can run `cargo test -- --include-ignored`.
+will be returned quickly. When you’re at a point where it makes sense to check
+the results of the `ignored` tests and you have time to wait for the results,
+you can run `cargo test -- --ignored` instead. If you want to run all tests
+whether they’re ignored or not, you can run `cargo test -- --include-ignored`.
## Test Organization
@@ -1206,16 +1248,16 @@ code that they’re testing. The convention is to create a module named `tests`
in each file to contain the test functions and to annotate the module with
`cfg(test)`.
-#### The Tests Module and `#[cfg(test)]`
+#### The Tests Module and #[cfg(test)]
-The `#[cfg(test)]` annotation on the tests module tells Rust to compile and run
-the test code only when you run `cargo test`, not when you run `cargo build`.
-This saves compile time when you only want to build the library and saves space
-in the resulting compiled artifact because the tests are not included. You’ll
-see that because integration tests go in a different directory, they don’t need
-the `#[cfg(test)]` annotation. However, because unit tests go in the same files
-as the code, you’ll use `#[cfg(test)]` to specify that they shouldn’t be
-included in the compiled result.
+The `#[cfg(test)]` annotation on the `tests` module tells Rust to compile and
+run the test code only when you run `cargo test`, not when you run `cargo
+build`. This saves compile time when you only want to build the library and
+saves space in the resultant compiled artifact because the tests are not
+included. You’ll see that because integration tests go in a different
+directory, they don’t need the `#[cfg(test)]` annotation. However, because unit
+tests go in the same files as the code, you’ll use `#[cfg(test)]` to specify
+that they shouldn’t be included in the compiled result.
Recall that when we generated the new `adder` project in the first section of
this chapter, Cargo generated this code for us:
@@ -1227,12 +1269,13 @@ Filename: src/lib.rs
mod tests {
#[test]
fn it_works() {
- assert_eq!(2 + 2, 4);
+ let result = 2 + 2;
+ assert_eq!(result, 4);
}
}
```
-This code is the automatically generated test module. The attribute `cfg`
+This code is the automatically generated `tests` module. The attribute `cfg`
stands for *configuration* and tells Rust that the following item should only
be included given a certain configuration option. In this case, the
configuration option is `test`, which is provided by Rust for compiling and
@@ -1275,7 +1318,7 @@ Listing 11-12: Testing a private function
Note that the `internal_adder` function is not marked as `pub`. Tests are just
Rust code, and the `tests` module is just another module. As we discussed in
-the “Paths for Referring to an Item in the Module Tree” section, items in child
+“Paths for Referring to an Item in the Module Tree” on page XX, items in child
modules can use the items in their ancestor modules. In this test, we bring all
of the `test` module’s parent’s items into scope with `use super::*`, and then
the test can call `internal_adder`. If you don’t think private functions should
@@ -1291,7 +1334,7 @@ work correctly on their own could have problems when integrated, so test
coverage of the integrated code is important as well. To create integration
tests, you first need a *tests* directory.
-#### The *tests* Directory
+#### The tests Directory
We create a *tests* directory at the top level of our project directory, next
to *src*. Cargo knows to look for integration test files in this directory. We
@@ -1307,12 +1350,12 @@ adder
├── Cargo.lock
├── Cargo.toml
├── src
-│   └── lib.rs
+│ └── lib.rs
└── tests
└── integration_test.rs
```
-Enter the code in Listing 11-13 into the *tests/integration_test.rs* file:
+Enter the code in Listing 11-13 into the *tests/integration_test.rs* file.
Filename: tests/integration_test.rs
@@ -1327,37 +1370,42 @@ fn it_adds_two() {
Listing 11-13: An integration test of a function in the `adder` crate
-Each file in the `tests` directory is a separate crate, so we need to bring our
-library into each test crate’s scope. For that reason we add `use adder` at the
-top of the code, which we didn’t need in the unit tests.
+Each file in the *tests* directory is a separate crate, so we need to bring our
+library into each test crate’s scope. For that reason we add `use adder;` at
+the top of the code, which we didn’t need in the unit tests.
We don’t need to annotate any code in *tests/integration_test.rs* with
-`#[cfg(test)]`. Cargo treats the `tests` directory specially and compiles files
+`#[cfg(test)]`. Cargo treats the *tests* directory specially and compiles files
in this directory only when we run `cargo test`. Run `cargo test` now:
```
$ cargo test
Compiling adder v0.1.0 (file:///projects/adder)
Finished test [unoptimized + debuginfo] target(s) in 1.31s
- Running unittests (target/debug/deps/adder-1082c4b063a8fbe6)
+ Running unittests src/lib.rs (target/debug/deps/adder-
+1082c4b063a8fbe6)
-[1] running 1 test
+1 running 1 test
test tests::internal ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
- [2] Running tests/integration_test.rs (target/debug/deps/integration_test-1082c4b063a8fbe6)
+ 2 Running tests/integration_test.rs
+(target/debug/deps/integration_test-1082c4b063a8fbe6)
running 1 test
-[3] test it_adds_two ... ok
+3 test it_adds_two ... ok
-[4] test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
Doc-tests adder
running 0 tests
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
The three sections of output include the unit tests, the integration test, and
@@ -1386,12 +1434,14 @@ followed by the name of the file:
```
$ cargo test --test integration_test
Finished test [unoptimized + debuginfo] target(s) in 0.64s
- Running tests/integration_test.rs (target/debug/deps/integration_test-82e7799c1bc62298)
+ Running tests/integration_test.rs
+(target/debug/deps/integration_test-82e7799c1bc62298)
running 1 test
test it_adds_two ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
This command runs only the tests in the *tests/integration_test.rs* file.
@@ -1409,11 +1459,11 @@ regarding how to separate code into modules and files.
The different behavior of *tests* directory files is most noticeable when you
have a set of helper functions to use in multiple integration test files and
-you try to follow the steps in the “Separating Modules into Different Files”
-section of Chapter 7 to extract them into a common module. For example, if we
-create *tests/common.rs* and place a function named `setup` in it, we can add
-some code to `setup` that we want to call from multiple test functions in
-multiple test files:
+you try to follow the steps in “Separating Modules into Different Files” on
+page XX to extract them into a common module. For example, if we create
+*tests/common.rs* and place a function named `setup` in it, we can add some
+code to `setup` that we want to call from multiple test functions in multiple
+test files:
Filename: tests/common.rs
@@ -1431,53 +1481,58 @@ did we call the `setup` function from anywhere:
running 1 test
test tests::internal ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
- Running tests/common.rs (target/debug/deps/common-92948b65e88960b4)
+ Running tests/common.rs (target/debug/deps/common-
+92948b65e88960b4)
running 0 tests
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
- Running tests/integration_test.rs (target/debug/deps/integration_test-92948b65e88960b4)
+ Running tests/integration_test.rs
+(target/debug/deps/integration_test-92948b65e88960b4)
running 1 test
test it_adds_two ... ok
-test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
Doc-tests adder
running 0 tests
-test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
+test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0
+filtered out; finished in 0.00s
```
Having `common` appear in the test results with `running 0 tests` displayed for
it is not what we wanted. We just wanted to share some code with the other
-integration test files.
-To avoid having `common` appear in the test output, instead of creating
-*tests/common.rs*, we’ll create *tests/common/mod.rs*. The project directory
-now looks like this:
+integration test files. To avoid having `common` appear in the test output,
+instead of creating *tests/common.rs*, we’ll create *tests/common/mod.rs*. The
+project directory now looks like this:
```
├── Cargo.lock
├── Cargo.toml
├── src
-│   └── lib.rs
+│ └── lib.rs
└── tests
├── common
- │   └── mod.rs
+ │ └── mod.rs
└── integration_test.rs
```
This is the older naming convention that Rust also understands that we
-mentioned in the “Alternate File Paths” section of Chapter 7. Naming the file
-this way tells Rust not to treat the `common` module as an integration test
-file. When we move the `setup` function code into *tests/common/mod.rs* and
-delete the *tests/common.rs* file, the section in the test output will no
-longer appear. Files in subdirectories of the *tests* directory don’t get
-compiled as separate crates or have sections in the test output.
+mentioned in “Alternate File Paths” on page XX. Naming the file this way tells
+Rust not to treat the `common` module as an integration test file. When we move
+the `setup` function code into *tests/common/mod.rs* and delete the
+*tests/common.rs* file, the section in the test output will no longer appear.
+Files in subdirectories of the *tests* directory don’t get compiled as separate
+crates or have sections in the test output.
After we’ve created *tests/common/mod.rs*, we can use it from any of the
integration test files as a module. Here’s an example of calling the `setup`
@@ -1498,7 +1553,7 @@ fn it_adds_two() {
```
Note that the `mod common;` declaration is the same as the module declaration
-we demonstrated in Listing 7-21. Then in the test function, we can call the
+we demonstrated in Listing 7-21. Then, in the test function, we can call the
`common::setup()` function.
#### Integration Tests for Binary Crates
@@ -1512,10 +1567,9 @@ crates can use; binary crates are meant to be run on their own.
This is one of the reasons Rust projects that provide a binary have a
straightforward *src/main.rs* file that calls logic that lives in the
*src/lib.rs* file. Using that structure, integration tests *can* test the
-library crate with `use` to make the important functionality available.
-If the important functionality works, the small amount of code in the
-*src/main.rs* file will work as well, and that small amount of code doesn’t
-need to be tested.
+library crate with `use` to make the important functionality available. If the
+important functionality works, the small amount of code in the *src/main.rs*
+file will work as well, and that small amount of code doesn’t need to be tested.
## Summary
@@ -1531,11 +1585,3 @@ reduce logic bugs having to do with how your code is expected to behave.
Let’s combine the knowledge you learned in this chapter and in previous
chapters to work on a project!
-<!---
-We hint at doc tests but don't cover them. Should we have a section in this
-chapter about that? They're pretty handy.
-/JT --->
-<!-- We cover that in chapter 14, and there's a forward reference to that in
-"The Anatomy of a Test Function" section. I don't actually think most Rust
-developers will write doc tests; they're the most useful when writing open
-source libraries, which I think only a minority of developers do. /Carol -->