src/doc/book/src/ch12-04-testing-the-librarys-functionality.md

   1 ## Developing the Library’s Functionality with Test-Driven Development
   2
   3 Now that we’ve extracted the logic into *src/lib.rs* and left the argument
   4 collecting and error handling in *src/main.rs*, it’s much easier to write tests
   5 for the core functionality of our code. We can call functions directly with
   6 various arguments and check return values without having to call our binary
   7 from the command line. Feel free to write some tests for the functionality in
   8 the `Config::new` and `run` functions on your own.
   9
  10 In this section, we’ll add the searching logic to the `minigrep` program by
  11 using the Test-driven development (TDD) process. This software development
  12 technique follows these steps:
  13
  14 1. Write a test that fails and run it to make sure it fails for the reason you
  15    expect.
  16 2. Write or modify just enough code to make the new test pass.
  17 3. Refactor the code you just added or changed and make sure the tests
  18    continue to pass.
  19 4. Repeat from step 1!
  20
  21 This process is just one of many ways to write software, but TDD can help drive
  22 code design as well. Writing the test before you write the code that makes the
  23 test pass helps to maintain high test coverage throughout the process.
  24
  25 We’ll test drive the implementation of the functionality that will actually do
  26 the searching for the query string in the file contents and produce a list of
  27 lines that match the query. We’ll add this functionality in a function called
  28 `search`.
  29
  30 ### Writing a Failing Test
  31
  32 Because we don’t need them anymore, let’s remove the `println!` statements from
  33 *src/lib.rs* and *src/main.rs* that we used to check the program’s behavior.
  34 Then, in *src/lib.rs*, we’ll add a `tests` module with a test function, as we
  35 did in [Chapter 11][ch11-anatomy]<!-- ignore -->. The test function specifies
  36 the behavior we want the `search` function to have: it will take a query and
  37 the text to search for the query in, and it will return only the lines from the
  38 text that contain the query. Listing 12-15 shows this test, which won’t compile
  39 yet.
  40
  41 <span class="filename">Filename: src/lib.rs</span>
  42
  43 ```rust,ignore,does_not_compile
  44 {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-15/src/lib.rs:here}}
  45 ```
  46
  47 <span class="caption">Listing 12-15: Creating a failing test for the `search`
  48 function we wish we had</span>
  49
  50 This test searches for the string `"duct"`. The text we’re searching is three
  51 lines, only one of which contains `"duct"`. We assert that the value returned
  52 from the `search` function contains only the line we expect.
  53
  54 We aren’t able to run this test and watch it fail because the test doesn’t even
  55 compile: the `search` function doesn’t exist yet! So now we’ll add just enough
  56 code to get the test to compile and run by adding a definition of the `search`
  57 function that always returns an empty vector, as shown in Listing 12-16. Then
  58 the test should compile and fail because an empty vector doesn’t match a vector
  59 containing the line `"safe, fast, productive."`
  60
  61 <span class="filename">Filename: src/lib.rs</span>
  62
  63 ```rust,noplayground
  64 {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-16/src/lib.rs:here}}
  65 ```
  66
  67 <span class="caption">Listing 12-16: Defining just enough of the `search`
  68 function so our test will compile</span>
  69
  70 Notice that we need an explicit lifetime `'a` defined in the signature of
  71 `search` and used with the `contents` argument and the return value. Recall in
  72 [Chapter 10][ch10-lifetimes]<!-- ignore --> that the lifetime parameters
  73 specify which argument lifetime is connected to the lifetime of the return
  74 value. In this case, we indicate that the returned vector should contain string
  75 slices that reference slices of the argument `contents` (rather than the
  76 argument `query`).
  77
  78 In other words, we tell Rust that the data returned by the `search` function
  79 will live as long as the data passed into the `search` function in the
  80 `contents` argument. This is important! The data referenced *by* a slice needs
  81 to be valid for the reference to be valid; if the compiler assumes we’re making
  82 string slices of `query` rather than `contents`, it will do its safety checking
  83 incorrectly.
  84
  85 If we forget the lifetime annotations and try to compile this function, we’ll
  86 get this error:
  87
  88 ```console
  89 {{#include ../listings/ch12-an-io-project/output-only-02-missing-lifetimes/output.txt}}
  90 ```
  91
  92 Rust can’t possibly know which of the two arguments we need, so we need to tell
  93 it. Because `contents` is the argument that contains all of our text and we
  94 want to return the parts of that text that match, we know `contents` is the
  95 argument that should be connected to the return value using the lifetime syntax.
  96
  97 Other programming languages don’t require you to connect arguments to return
  98 values in the signature. Although this might seem strange, it will get easier
  99 over time. You might want to compare this example with the [“Validating
 100 References with Lifetimes”][validating-references-with-lifetimes]<!-- ignore
 101 --> section in Chapter 10.
 102
 103 Now let’s run the test:
 104
 105 ```console
 106 {{#include ../listings/ch12-an-io-project/listing-12-16/output.txt}}
 107 ```
 108
 109 Great, the test fails, exactly as we expected. Let’s get the test to pass!
 110
 111 ### Writing Code to Pass the Test
 112
 113 Currently, our test is failing because we always return an empty vector. To fix
 114 that and implement `search`, our program needs to follow these steps:
 115
 116 * Iterate through each line of the contents.
 117 * Check whether the line contains our query string.
 118 * If it does, add it to the list of values we’re returning.
 119 * If it doesn’t, do nothing.
 120 * Return the list of results that match.
 121
 122 Let’s work through each step, starting with iterating through lines.
 123
 124 #### Iterating Through Lines with the `lines` Method
 125
 126 Rust has a helpful method to handle line-by-line iteration of strings,
 127 conveniently named `lines`, that works as shown in Listing 12-17. Note this
 128 won’t compile yet.
 129
 130 <span class="filename">Filename: src/lib.rs</span>
 131
 132 ```rust,ignore,does_not_compile
 133 {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-17/src/lib.rs:here}}
 134 ```
 135
 136 <span class="caption">Listing 12-17: Iterating through each line in `contents`
 137 </span>
 138
 139 The `lines` method returns an iterator. We’ll talk about iterators in depth in
 140 [Chapter 13][ch13-iterators]<!-- ignore -->, but recall that you saw this way of using an
 141 iterator in [Listing 3-5][ch3-iter]<!-- ignore -->, where we used a `for` loop
 142 with an iterator to run some code on each item in a collection.
 143
 144 #### Searching Each Line for the Query
 145
 146 Next, we’ll check whether the current line contains our query string.
 147 Fortunately, strings have a helpful method named `contains` that does this for
 148 us! Add a call to the `contains` method in the `search` function, as shown in
 149 Listing 12-18. Note this still won’t compile yet.
 150
 151 <span class="filename">Filename: src/lib.rs</span>
 152
 153 ```rust,ignore,does_not_compile
 154 {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-18/src/lib.rs:here}}
 155 ```
 156
 157 <span class="caption">Listing 12-18: Adding functionality to see whether the
 158 line contains the string in `query`</span>
 159
 160 #### Storing Matching Lines
 161
 162 We also need a way to store the lines that contain our query string. For that,
 163 we can make a mutable vector before the `for` loop and call the `push` method
 164 to store a `line` in the vector. After the `for` loop, we return the vector, as
 165 shown in Listing 12-19.
 166
 167 <span class="filename">Filename: src/lib.rs</span>
 168
 169 ```rust,ignore
 170 {{#rustdoc_include ../listings/ch12-an-io-project/listing-12-19/src/lib.rs:here}}
 171 ```
 172
 173 <span class="caption">Listing 12-19: Storing the lines that match so we can
 174 return them</span>
 175
 176 Now the `search` function should return only the lines that contain `query`,
 177 and our test should pass. Let’s run the test:
 178
 179 ```console
 180 {{#include ../listings/ch12-an-io-project/listing-12-19/output.txt}}
 181 ```
 182
 183 Our test passed, so we know it works!
 184
 185 At this point, we could consider opportunities for refactoring the
 186 implementation of the search function while keeping the tests passing to
 187 maintain the same functionality. The code in the search function isn’t too bad,
 188 but it doesn’t take advantage of some useful features of iterators. We’ll
 189 return to this example in [Chapter 13][ch13-iterators]<!-- ignore -->, where we’ll
 190 explore iterators in detail, and look at how to improve it.
 191
 192 #### Using the `search` Function in the `run` Function
 193
 194 Now that the `search` function is working and tested, we need to call `search`
 195 from our `run` function. We need to pass the `config.query` value and the
 196 `contents` that `run` reads from the file to the `search` function. Then `run`
 197 will print each line returned from `search`:
 198
 199 <span class="filename">Filename: src/lib.rs</span>
 200
 201 ```rust,ignore
 202 {{#rustdoc_include ../listings/ch12-an-io-project/no-listing-02-using-search-in-run/src/lib.rs:here}}
 203 ```
 204
 205 We’re still using a `for` loop to return each line from `search` and print it.
 206
 207 Now the entire program should work! Let’s try it out, first with a word that
 208 should return exactly one line from the Emily Dickinson poem, “frog”:
 209
 210 ```console
 211 {{#include ../listings/ch12-an-io-project/no-listing-02-using-search-in-run/output.txt}}
 212 ```
 213
 214 Cool! Now let’s try a word that will match multiple lines, like “body”:
 215
 216 ```console
 217 {{#include ../listings/ch12-an-io-project/output-only-03-multiple-matches/output.txt}}
 218 ```
 219
 220 And finally, let’s make sure that we don’t get any lines when we search for a
 221 word that isn’t anywhere in the poem, such as “monomorphization”:
 222
 223 ```console
 224 {{#include ../listings/ch12-an-io-project/output-only-04-no-matches/output.txt}}
 225 ```
 226
 227 Excellent! We’ve built our own mini version of a classic tool and learned a lot
 228 about how to structure applications. We’ve also learned a bit about file input
 229 and output, lifetimes, testing, and command line parsing.
 230
 231 To round out this project, we’ll briefly demonstrate how to work with
 232 environment variables and how to print to standard error, both of which are
 233 useful when you’re writing command line programs.
 234
 235 [validating-references-with-lifetimes]:
 236 ch10-03-lifetime-syntax.html#validating-references-with-lifetimes
 237 [ch11-anatomy]: ch11-01-writing-tests.html#the-anatomy-of-a-test-function
 238 [ch10-lifetimes]: ch10-03-lifetime-syntax.html
 239 [ch3-iter]: ch03-05-control-flow.html#looping-through-a-collection-with-for
 240 [ch13-iterators]: ch13-02-iterators.html