From 36bc7f0e0728e15a371836c0b0c3c5078a7afeee Mon Sep 17 00:00:00 2001
From: bryanzierk <bryan.zierk@gmail.com>
Date: Wed, 12 Jun 2024 08:43:03 -0600
Subject: [PATCH 1/5] Convert chapter 11 to use Listing component

---
 src/ch11-01-writing-tests.md | 57 ++++++++++++++++++------------------
 1 file changed, 29 insertions(+), 28 deletions(-)

diff --git a/src/ch11-01-writing-tests.md b/src/ch11-01-writing-tests.md
index f1295931f4..3b83195fa2 100644
--- a/src/ch11-01-writing-tests.md
+++ b/src/ch11-01-writing-tests.md
@@ -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
@@ -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
@@ -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
@@ -113,12 +113,14 @@ ignore the `Doc-tests` output.
 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:
 
-<span class="filename">Filename: src/lib.rs</span>
+<Listing file-name="src/lib.rs">
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-01-changing-test-name/src/lib.rs}}
 ```
 
+</Listing>
+
 Then run `cargo test` again. The output now shows `exploration` instead of
 `it_works`:
 
@@ -133,24 +135,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/libs.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
@@ -182,14 +184,13 @@ 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
@@ -197,14 +198,13 @@ for the `assert!` macro. In Listing 11-6, we write a test that exercises the
 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
@@ -227,12 +227,14 @@ supposed to return `true`, so our test should pass. Let’s find out!
 It does pass! Let’s add another test, this time asserting that a smaller
 rectangle cannot hold a larger rectangle:
 
-<span class="filename">Filename: src/lib.rs</span>
+<Listing file-name="src/lib.rs">
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-02-adding-another-rectangle-test/src/lib.rs:here}}
 ```
 
+</Listing>
+
 Because the correct result of the `can_hold` function in this case is `false`,
 we need to negate that result before we pass it to the `assert!` macro. As a
 result, our test will pass if `can_hold` returns `false`:
@@ -276,14 +278,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!
 
@@ -360,12 +361,14 @@ 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:
 
-<span class="filename">Filename: src/lib.rs</span>
+<Listing file-name="src/lib.rs">
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-05-greeter/src/lib.rs}}
 ```
 
+</Listing>
+
 The requirements for this program haven’t been agreed upon yet, and we’re
 pretty sure the `Hello` text at the beginning of the greeting will change. We
 decided we don’t want to have to update the test when the requirements change,
@@ -421,14 +424,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
@@ -464,14 +466,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" 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`

From ae41d13cd38e5506ae575a295b1faf1895cd1ba2 Mon Sep 17 00:00:00 2001
From: bryanzierk <bryan.zierk@gmail.com>
Date: Wed, 12 Jun 2024 09:37:02 -0600
Subject: [PATCH 2/5] Fix typo

---
 src/ch11-01-writing-tests.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ch11-01-writing-tests.md b/src/ch11-01-writing-tests.md
index 3b83195fa2..267b3128bf 100644
--- a/src/ch11-01-writing-tests.md
+++ b/src/ch11-01-writing-tests.md
@@ -135,7 +135,7 @@ 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.
 
-<Listing number="11-3" file-name="src/libs.rs" caption="Adding a second test that will fail because we call the `panic!` macro">
+<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}}

From 30559b5e6e010f45c249c1e16a7aecc0188d6133 Mon Sep 17 00:00:00 2001
From: bryanzierk <bryan.zierk@gmail.com>
Date: Wed, 12 Jun 2024 10:21:58 -0600
Subject: [PATCH 3/5] Convert 11-02 and 11-03

---
 src/ch11-01-writing-tests.md     |  9 ++-------
 src/ch11-02-running-tests.md     | 10 ++++------
 src/ch11-03-test-organization.md |  9 ++++-----
 3 files changed, 10 insertions(+), 18 deletions(-)

diff --git a/src/ch11-01-writing-tests.md b/src/ch11-01-writing-tests.md
index 267b3128bf..a5927aea0e 100644
--- a/src/ch11-01-writing-tests.md
+++ b/src/ch11-01-writing-tests.md
@@ -113,14 +113,12 @@ ignore the `Doc-tests` output.
 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:
 
-<Listing file-name="src/lib.rs">
+<span class="filename">Filename: src/lib.rs</span>
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-01-changing-test-name/src/lib.rs}}
 ```
 
-</Listing>
-
 Then run `cargo test` again. The output now shows `exploration` instead of
 `it_works`:
 
@@ -361,14 +359,11 @@ 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:
 
-<Listing file-name="src/lib.rs">
-
+<span class="filename">Filename: src/lib.rs</span>
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-05-greeter/src/lib.rs}}
 ```
 
-</Listing>
-
 The requirements for this program haven’t been agreed upon yet, and we’re
 pretty sure the `Hello` text at the beginning of the greeting will change. We
 decided we don’t want to have to update the test when the requirements change,
diff --git a/src/ch11-02-running-tests.md b/src/ch11-02-running-tests.md
index 194718256c..6445826eff 100644
--- a/src/ch11-02-running-tests.md
+++ b/src/ch11-02-running-tests.md
@@ -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:
 
@@ -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:
diff --git a/src/ch11-03-test-organization.md b/src/ch11-03-test-organization.md
index fb592e909c..a8c19b6a6c 100644
--- a/src/ch11-03-test-organization.md
+++ b/src/ch11-03-test-organization.md
@@ -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
@@ -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

From 533ea4700e369e3775a2c88b0688bc2b5ec0c9d9 Mon Sep 17 00:00:00 2001
From: bryanzierk <bryan.zierk@gmail.com>
Date: Wed, 12 Jun 2024 10:29:42 -0600
Subject: [PATCH 4/5] Revert Listing to span for filename

---
 src/ch11-01-writing-tests.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/ch11-01-writing-tests.md b/src/ch11-01-writing-tests.md
index a5927aea0e..07cef2a623 100644
--- a/src/ch11-01-writing-tests.md
+++ b/src/ch11-01-writing-tests.md
@@ -225,14 +225,12 @@ supposed to return `true`, so our test should pass. Let’s find out!
 It does pass! Let’s add another test, this time asserting that a smaller
 rectangle cannot hold a larger rectangle:
 
-<Listing file-name="src/lib.rs">
+<span class="filename">Filename: src/lib.rs</span>
 
 ```rust,noplayground
 {{#rustdoc_include ../listings/ch11-writing-automated-tests/no-listing-02-adding-another-rectangle-test/src/lib.rs:here}}
 ```
 
-</Listing>
-
 Because the correct result of the `can_hold` function in this case is `false`,
 we need to negate that result before we pass it to the `assert!` macro. As a
 result, our test will pass if `can_hold` returns `false`:

From ab03ebc2cd7c97995a8cd5333123ff515f88d722 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 12 Jun 2024 11:22:29 -0600
Subject: [PATCH 5/5] Include one missing `file-name` in
 src/ch11-01-writing-tests.md Listing

---
 src/ch11-01-writing-tests.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ch11-01-writing-tests.md b/src/ch11-01-writing-tests.md
index 07cef2a623..14bcc95df9 100644
--- a/src/ch11-01-writing-tests.md
+++ b/src/ch11-01-writing-tests.md
@@ -459,7 +459,7 @@ 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.
 
-<Listing number="11-9" caption="Testing for a `panic!` with a panic message containing a specified substring">
+<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}}