Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert chapter 11 to use Listing component #3955

Merged
merged 5 commits into from
Jun 12, 2024
Merged

Convert chapter 11 to use Listing component #3955

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
36bc7f0
Convert chapter 11 to use Listing component
bzierk Jun 12, 2024
ae41d13
Fix typo
bzierk Jun 12, 2024
30559b5
Convert 11-02 and 11-03
bzierk Jun 12, 2024
533ea47
Revert Listing to span for filename
bzierk Jun 12, 2024
ab03ebc
Include one missing `file-name` in src/ch11-01-writing-tests.md Listing
chriskrycho Jun 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 20 additions & 26 deletions src/ch11-01-writing-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ $ cd adder
The contents of the *src/lib.rs* file in your `adder` library should look like
Listing 11-1.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-1" file-name="src/lib.rs" caption="The test module and function generated automatically by `cargo new`">

<!-- manual-regeneration
cd listings/ch11-writing-automated-tests
Expand All @@ -59,8 +59,7 @@ cd ../../..
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-01/src/lib.rs}}
```

<span class="caption">Listing 11-1: The test module and function generated
automatically by `cargo new`</span>
</Listing>

For now, let’s focus solely on the `it_works()` function. Note the
`#[test]` annotation: this attribute indicates this is a test function, so the
Expand All @@ -76,12 +75,13 @@ passes.
The `cargo test` command runs all tests in our project, as shown in Listing
11-2.

<Listing number="11-2" caption="The output from running the automatically generated test">

```console
{{#include ../listings/ch11-writing-automated-tests/listing-11-01/output.txt}}
```

<span class="caption">Listing 11-2: The output from running the automatically
generated test</span>
</Listing>

Cargo compiled and ran the test. We see the line `running 1 test`. The next
line shows the name of the generated test function, called `it_works`, and that
Expand Down Expand Up @@ -133,24 +133,24 @@ marked as failed. In Chapter 9, we talked about how the simplest way to panic
is to call the `panic!` macro. Enter the new test as a function named
`another`, so your *src/lib.rs* file looks like Listing 11-3.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-3" file-name="src/lib.rs" caption="Adding a second test that will fail because we call the `panic!` macro">

```rust,panics,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-03/src/lib.rs:here}}
```

<span class="caption">Listing 11-3: Adding a second test that will fail because
we call the `panic!` macro</span>
</Listing>

Run the tests again using `cargo test`. The output should look like Listing
11-4, which shows that our `exploration` test passed and `another` failed.

<Listing number="11-4" caption="Test results when one test passes and one test fails">

```console
{{#include ../listings/ch11-writing-automated-tests/listing-11-03/output.txt}}
```

<span class="caption">Listing 11-4: Test results when one test passes and one
test fails</span>
</Listing>

Instead of `ok`, the line `test tests::another` shows `FAILED`. Two new
sections appear between the individual results and the summary: the first
Expand Down Expand Up @@ -182,29 +182,27 @@ 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.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-5" file-name="src/lib.rs" caption="The `Rectangle` struct and its `can_hold` method from Chapter 5">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-05/src/lib.rs:here}}
```

<span class="caption">Listing 11-5: Using the `Rectangle` struct and its
`can_hold` method from Chapter 5</span>
</Listing>

The `can_hold` method returns a Boolean, which means it’s a perfect use case
for the `assert!` macro. In Listing 11-6, we write a test that exercises the
`can_hold` method by creating a `Rectangle` instance that has a width of 8 and
a height of 7 and asserting that it can hold another `Rectangle` instance that
has a width of 5 and a height of 1.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-6" file-name="src/lib.rs" caption="A test for `can_hold` that checks whether a larger rectangle can indeed hold a smaller rectangle">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-06/src/lib.rs:here}}
```

<span class="caption">Listing 11-6: A test for `can_hold` that checks whether a
larger rectangle can indeed hold a smaller rectangle</span>
</Listing>

Note that we’ve added a new line inside the `tests` module: `use super::*;`.
The `tests` module is a regular module that follows the usual visibility rules
Expand Down Expand Up @@ -276,14 +274,13 @@ expression, without printing the values that led to the `false` value.
In Listing 11-7, we write a function named `add_two` that adds `2` to its
parameter, then we test this function using the `assert_eq!` macro.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-7" file-name="src/lib.rs" caption="Testing the function `add_two` using the `assert_eq!` macro">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-07/src/lib.rs}}
```

<span class="caption">Listing 11-7: Testing the function `add_two` using the
`assert_eq!` macro</span>
</Listing>

Let’s check that it passes!

Expand Down Expand Up @@ -361,7 +358,6 @@ 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:

<span class="filename">Filename: src/lib.rs</span>

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-05-greeter/src/lib.rs}}
```
Expand Down Expand Up @@ -421,14 +417,13 @@ 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.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-8" file-name="src/lib.rs" caption="Testing that a condition will cause a `panic!`">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-08/src/lib.rs}}
```

<span class="caption">Listing 11-8: Testing that a condition will cause a
`panic!`</span>
</Listing>

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
Expand Down Expand Up @@ -464,14 +459,13 @@ 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.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-9" file-name="src/lib.rs" caption="Testing for a `panic!` with a panic message containing a specified substring">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-09/src/lib.rs:here}}
```

<span class="caption">Listing 11-9: Testing for a `panic!` with a panic message
containing a specified substring</span>
</Listing>

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`
Expand Down
10 changes: 4 additions & 6 deletions src/ch11-02-running-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,14 +58,13 @@ printed to standard output with the rest of the failure message.
As an example, Listing 11-10 has a silly function that prints the value of its
parameter and returns 10, as well as a test that passes and a test that fails.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-10" file-name="src/lib.rs" caption="Tests for a function that calls `println!`">

```rust,panics,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-10/src/lib.rs}}
```

<span class="caption">Listing 11-10: Tests for a function that calls
`println!`</span>
</Listing>

When we run these tests with `cargo test`, we’ll see the following output:

Expand Down Expand Up @@ -102,14 +101,13 @@ or names of the test(s) you want to run as an argument.
To demonstrate how to run a subset of tests, we’ll first create three tests for
our `add_two` function, as shown in Listing 11-11, and choose which ones to run.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-11" file-name="src/lib.rs" caption="Three tests with three different names">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-11/src/lib.rs}}
```

<span class="caption">Listing 11-11: Three tests with three different
names</span>
</Listing>

If we run the tests without passing any arguments, as we saw earlier, all the
tests will run in parallel:
Expand Down
9 changes: 4 additions & 5 deletions src/ch11-03-test-organization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,13 +58,13 @@ impossible to test private functions. Regardless of which testing ideology you
adhere to, Rust’s privacy rules do allow you to test private functions.
Consider the code in Listing 11-12 with the private function `internal_adder`.

<span class="filename">Filename: src/lib.rs</span>
<Listing number="11-12" file-name="src/lib.rs" caption="Testing a private function">

```rust,noplayground
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-12/src/lib.rs}}
```

<span class="caption">Listing 11-12: Testing a private function</span>
</Listing>

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
Expand Down Expand Up @@ -108,14 +108,13 @@ adder

Enter the code in Listing 11-13 into the *tests/integration_test.rs* file:

<span class="filename">Filename: tests/integration_test.rs</span>
<Listing number="11-13" file-name="tests/integration_test.rs" caption="An integration test of a function in the `adder` crate">

```rust,ignore
{{#rustdoc_include ../listings/ch11-writing-automated-tests/listing-11-13/tests/integration_test.rs}}
```

<span class="caption">Listing 11-13: An integration test of a function in the
`adder` crate</span>
</Listing>

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
Expand Down