pierre/RustBook
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
918fbf9c09
RustBook/ch11-01-writing-tests.html

913 lines
60 KiB
HTML
Raw Normal View History

Initial commit
2020-01-06 20:57:15 +00:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>How to Write Tests - The Rust Programming Language</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link href="googleFonts/css.css" rel="stylesheet" type="text/css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="ferris.css">
<link rel="stylesheet" href="theme/2018-edition.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
<ol class="chapter"><li class="expanded affix "><a href="title-page.html">The Rust Programming Language</a></li><li class="expanded affix "><a href="foreword.html">Foreword</a></li><li class="expanded affix "><a href="ch00-00-introduction.html">Introduction</a></li><li class="expanded "><a href="ch01-00-getting-started.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li class="expanded "><a href="ch01-01-installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li class="expanded "><a href="ch01-02-hello-world.html"><strong aria-hidden="true">1.2.</strong> Hello, World!</a></li><li class="expanded "><a href="ch01-03-hello-cargo.html"><strong aria-hidden="true">1.3.</strong> Hello, Cargo!</a></li></ol></li><li class="expanded "><a href="ch02-00-guessing-game-tutorial.html"><strong aria-hidden="true">2.</strong> Programming a Guessing Game</a></li><li class="expanded "><a href="ch03-00-common-programming-concepts.html"><strong aria-hidden="true">3.</strong> Common Programming Concepts</a></li><li><ol class="section"><li class="expanded "><a href="ch03-01-variables-and-mutability.html"><strong aria-hidden="true">3.1.</strong> Variables and Mutability</a></li><li class="expanded "><a href="ch03-02-data-types.html"><strong aria-hidden="true">3.2.</strong> Data Types</a></li><li class="expanded "><a href="ch03-03-how-functions-work.html"><strong aria-hidden="true">3.3.</strong> Functions</a></li><li class="expanded "><a href="ch03-04-comments.html"><strong aria-hidden="true">3.4.</strong> Comments</a></li><li class="expanded "><a href="ch03-05-control-flow.html"><strong aria-hidden="true">3.5.</strong> Control Flow</a></li></ol></li><li class="expanded "><a href="ch04-00-understanding-ownership.html"><strong aria-hidden="true">4.</strong> Understanding Ownership</a></li><li><ol class="section"><li class="expanded "><a href="ch04-01-what-is-ownership.html"><strong aria-hidden="true">4.1.</strong> What is Ownership?</a></li><li class="expanded "><a href="ch04-02-references-and-borrowing.html"><strong aria-hidden="true">4.2.</strong> References and Borrowing</a></li><li class="expanded "><a href="ch04-03-slices.html"><strong aria-hidden="true">4.3.</strong> The Slice Type</a></li></ol></li><li class="expanded "><a href="ch05-00-structs.html"><strong aria-hidden="true">5.</strong> Using Structs to Structure Related Data</a></li><li><ol class="section"><li class="expanded "><a href="ch05-01-defining-structs.html"><strong aria-hidden="true">5.1.</strong> Defining and Instantiating Structs</a></li><li class="expanded "><a href="ch05-02-example-structs.html"><strong aria-hidden="true">5.2.</strong> An Example Program Using Structs</a></li><li class="expanded "><a href="ch05-03-method-syntax.html"><strong aria-hidden="true">5.3.</strong> Method Syntax</a></li></ol></li><li class="expanded "><a href="ch06-00-enums.html"><strong aria-hidden="true">6.</strong> Enums and Pattern Matching</a></li><li><ol class="section"><li class="expanded "><a href="ch06-01-defining-an-enum.html"><strong aria-hidden="true">6.1.</strong> Defining an Enum</a></li><li class="expanded "><a href="ch06-02-match.html"><strong aria-hidden="true">6.2.</strong> The match Control Flow Operator</a></li><li class="expanded "><a href="ch06-03-if-let.html"><strong aria-hidden="true">6.3.</strong> Concise Control Flow with if let</a></li></ol></li><li class="expanded "><a href="ch07-00-managing-growing-projects-with-packages-crates-and-modules.html"><strong aria-hidden="true">7.</strong> Managing Growing Projects with Packages, Crates, and Modules</a></li><li><ol class="section"><li class="expanded "><a href="ch07-01-packages-and-crates.html"><strong aria-hidden="true">7.1.</strong> Packages and Crates</a></li><li class="expanded "><a href="ch07-02-defining-modules-to-control-scope-and-privacy.html"><strong aria-hidden="true">7.2.</strong> Defining Modules to Control Scope and Privacy</a></li><li class="expanded "><a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html"><
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Rust Programming Language</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h2><a class="header" href="#how-to-write-tests" id="how-to-write-tests">How to Write Tests</a></h2>
<p>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:</p>
<ol>
<li>Set up any needed data or state.</li>
<li>Run the code you want to test.</li>
<li>Assert the results are what you expect.</li>
</ol>
<p>Let’s look at the features Rust provides specifically for writing tests that
take these actions, which include the <code>test</code> attribute, a few macros, and the
<code>should_panic</code> attribute.</p>
<h3><a class="header" href="#the-anatomy-of-a-test-function" id="the-anatomy-of-a-test-function">The Anatomy of a Test Function</a></h3>
<p>At its simplest, a test in Rust is a function that’s annotated with the <code>test</code>
attribute. Attributes are metadata about pieces of Rust code; one example is
the <code>derive</code> attribute we used with structs in Chapter 5. To change a function
into a test function, add <code>#[test]</code> on the line before <code>fn</code>. When you run your
tests with the <code>cargo test</code> command, Rust builds a test runner binary that runs
the functions annotated with the <code>test</code> attribute and reports on whether each
test function passes or fails.</p>
<p>When we make a new library project with Cargo, a test module with a test
function in it is automatically generated for us. This module helps you start
writing your tests so you don’t have to look up the exact structure and syntax
of test functions every time you start a new project. You can add as many
additional test functions and as many test modules as you want!</p>
<p>We’ll explore some aspects of how tests work by experimenting with the template
test generated for us without actually testing any code. Then we’ll write some
real-world tests that call some code that we’ve written and assert that its
behavior is correct.</p>
<p>Let’s create a new library project called <code>adder</code>:</p>
<pre><code class="language-text">$ cargo new adder --lib
Created library `adder` project
$ cd adder
</code></pre>
<p>The contents of the <em>src/lib.rs</em> file in your <code>adder</code> library should look like
Listing 11-1.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>#[cfg(test)]
mod tests {
#[test]
fn it_works() {
assert_eq!(2 + 2, 4);
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-1: The test module and function generated
automatically by <code>cargo new</code></span></p>
<p>For now, let’s ignore the top two lines and focus on the function to see how it
works. Note the <code>#[test]</code> annotation before the <code>fn</code> line: this attribute
indicates this is a test function, so the test runner knows to treat this
function as a test. We could also have non-test functions in the <code>tests</code> module
to help set up common scenarios or perform common operations, so we need to
indicate which functions are tests by using the <code>#[test]</code> attribute.</p>
<p>The function body uses the <code>assert_eq!</code> macro to assert that 2 + 2 equals 4.
This assertion serves as an example of the format for a typical test. Let’s run
it to see that this test passes.</p>
<p>The <code>cargo test</code> command runs all tests in our project, as shown in Listing
11-2.</p>
<pre><code class="language-text">$ cargo test
Compiling adder v0.1.0 (file:///projects/adder)
Finished dev [unoptimized + debuginfo] target(s) in 0.22 secs
Running target/debug/deps/adder-ce99bcc2479f4607
running 1 test
test tests::it_works ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
Doc-tests adder
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p><span class="caption">Listing 11-2: The output from running the automatically
generated test</span></p>
<p>Cargo compiled and ran the test. After the <code>Compiling</code>, <code>Finished</code>, and
<code>Running</code> lines is the line <code>running 1 test</code>. The next line shows the name
of the generated test function, called <code>it_works</code>, and the result of running
that test, <code>ok</code>. The overall summary of running the tests appears next. The
text <code>test result: ok.</code> means that all the tests passed, and the portion that
reads <code>1 passed; 0 failed</code> totals the number of tests that passed or failed.</p>
<p>Because we don’t have any tests we’ve marked as ignored, the summary shows <code>0 ignored</code>. We also haven’t filtered the tests being run, so the end of the
summary shows <code>0 filtered out</code>. We’ll talk about ignoring and filtering out
tests in the next section, <a href="ch11-02-running-tests.html#controlling-how-tests-are-run">“Controlling How Tests Are
Run.”</a><!-- ignore --></p>
<p>The <code>0 measured</code> statistic is for benchmark tests that measure performance.
Benchmark tests are, as of this writing, only available in nightly Rust. See
<a href="../unstable-book/library-features/test.html">the documentation about benchmark tests</a> to learn more.</p>
<p>The next part of the test output, which starts with <code>Doc-tests adder</code>, 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 us keep our docs and our code in sync! We’ll
discuss how to write documentation tests in the <a href="ch14-02-publishing-to-crates-io.html#documentation-comments-as-tests">“Documentation Comments as
Tests”</a><!-- ignore --> section of Chapter 14. For now, we’ll
ignore the <code>Doc-tests</code> output.</p>
<p>Let’s change the name of our test to see how that changes the test output.
Change the <code>it_works</code> function to a different name, such as <code>exploration</code>, like
so:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>#[cfg(test)]
mod tests {
#[test]
fn exploration() {
assert_eq!(2 + 2, 4);
}
}
</code></pre></pre>
<p>Then run <code>cargo test</code> again. The output now shows <code>exploration</code> instead of
<code>it_works</code>:</p>
<pre><code class="language-text">running 1 test
test tests::exploration ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>Let’s add another test, but this time we’ll make a test that fails! Tests fail
when something in the test function panics. Each test is run in a new thread,
and when the main thread sees that a test thread has died, the test is marked
as failed. We talked about the simplest way to cause a panic in Chapter 9,
which is to call the <code>panic!</code> macro. Enter the new test, <code>another</code>, so your
<em>src/lib.rs</em> file looks like Listing 11-3.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust panics"><span class="boring">fn main() {}
</span>#[cfg(test)]
mod tests {
#[test]
fn exploration() {
assert_eq!(2 + 2, 4);
}
#[test]
fn another() {
panic!(&quot;Make this test fail&quot;);
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-3: Adding a second test that will fail because
we call the <code>panic!</code> macro</span></p>
<p>Run the tests again using <code>cargo test</code>. The output should look like Listing
11-4, which shows that our <code>exploration</code> test passed and <code>another</code> failed.</p>
<pre><code class="language-text">running 2 tests
test tests::exploration ... ok
test tests::another ... FAILED
failures:
---- tests::another stdout ----
thread 'tests::another' panicked at 'Make this test fail', src/lib.rs:10:9
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
tests::another
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
error: test failed
</code></pre>
<p><span class="caption">Listing 11-4: Test results when one test passes and one
test fails</span></p>
<p>Instead of <code>ok</code>, the line <code>test tests::another</code> shows <code>FAILED</code>. Two new
sections appear between the individual results and the summary: the first
section displays the detailed reason for each test failure. In this case,
<code>another</code> failed because it <code>panicked at 'Make this test fail'</code>, which happened
on line 10 in the <em>src/lib.rs</em> file. The next section 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 <a href="ch11-02-running-tests.html#controlling-how-tests-are-run">“Controlling How Tests Are Run”</a><!-- ignore
--> section.</p>
<p>The summary line displays at the end: overall, our test result is <code>FAILED</code>.
We had one test pass and one test fail.</p>
<p>Now that you’ve seen what the test results look like in different scenarios,
let’s look at some macros other than <code>panic!</code> that are useful in tests.</p>
<h3><a class="header" href="#checking-results-with-the-assert-macro" id="checking-results-with-the-assert-macro">Checking Results with the <code>assert!</code> Macro</a></h3>
<p>The <code>assert!</code> macro, provided by the standard library, is useful when you want
to ensure that some condition in a test evaluates to <code>true</code>. We give the
<code>assert!</code> macro an argument that evaluates to a Boolean. If the value is
<code>true</code>, <code>assert!</code> does nothing and the test passes. If the value is <code>false</code>,
the <code>assert!</code> macro calls the <code>panic!</code> macro, which causes the test to fail.
Using the <code>assert!</code> macro helps us check that our code is functioning in the
way we intend.</p>
<p>In Chapter 5, Listing 5-15, we used a <code>Rectangle</code> struct and a <code>can_hold</code>
method, which are repeated here in Listing 11-5. Let’s put this code in the
<em>src/lib.rs</em> file and write some tests for it using the <code>assert!</code> macro.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>#[derive(Debug)]
struct Rectangle {
width: u32,
height: u32,
}
impl Rectangle {
fn can_hold(&amp;self, other: &amp;Rectangle) -&gt; bool {
self.width &gt; other.width &amp;&amp; self.height &gt; other.height
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-5: Using the <code>Rectangle</code> struct and its
<code>can_hold</code> method from Chapter 5</span></p>
<p>The <code>can_hold</code> method returns a Boolean, which means it’s a perfect use case
for the <code>assert!</code> macro. In Listing 11-6, we write a test that exercises the
<code>can_hold</code> method by creating a <code>Rectangle</code> instance that has a width of 8 and
a height of 7 and asserting that it can hold another <code>Rectangle</code> instance that
has a width of 5 and a height of 1.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>#[cfg(test)]
mod tests {
use super::*;
#[test]
fn larger_can_hold_smaller() {
let larger = Rectangle { width: 8, height: 7 };
let smaller = Rectangle { width: 5, height: 1 };
assert!(larger.can_hold(&amp;smaller));
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-6: A test for <code>can_hold</code> that checks whether a
larger rectangle can indeed hold a smaller rectangle</span></p>
<p>Note that we’ve added a new line inside the <code>tests</code> module: <code>use super::*;</code>.
The <code>tests</code> module is a regular module that follows the usual visibility rules
we covered in Chapter 7 in the <a href="ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html">“Paths for Referring to an Item in the Module
Tree”</a><!-- ignore -->
section. Because the <code>tests</code> 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
<code>tests</code> module.</p>
<p>We’ve named our test <code>larger_can_hold_smaller</code>, and we’ve created the two
<code>Rectangle</code> instances that we need. Then we called the <code>assert!</code> macro and
passed it the result of calling <code>larger.can_hold(&amp;smaller)</code>. This expression
is supposed to return <code>true</code>, so our test should pass. Let’s find out!</p>
<pre><code class="language-text">running 1 test
test tests::larger_can_hold_smaller ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>It does pass! Let’s add another test, this time asserting that a smaller
rectangle cannot hold a larger rectangle:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>#[cfg(test)]
mod tests {
use super::*;
#[test]
fn larger_can_hold_smaller() {
// --snip--
}
#[test]
fn smaller_cannot_hold_larger() {
let larger = Rectangle { width: 8, height: 7 };
let smaller = Rectangle { width: 5, height: 1 };
assert!(!smaller.can_hold(&amp;larger));
}
}
</code></pre></pre>
<p>Because the correct result of the <code>can_hold</code> function in this case is <code>false</code>,
we need to negate that result before we pass it to the <code>assert!</code> macro. As a
result, our test will pass if <code>can_hold</code> returns <code>false</code>:</p>
<pre><code class="language-text">running 2 tests
test tests::smaller_cannot_hold_larger ... ok
test tests::larger_can_hold_smaller ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>Two tests that pass! Now let’s see what happens to our test results when we
introduce a bug in our code. Let’s change the implementation of the <code>can_hold</code>
method by replacing the greater than sign with a less than sign when it
compares the widths:</p>
<pre><pre class="playpen"><code class="language-rust not_desired_behavior"><span class="boring">fn main() {}
</span><span class="boring">#[derive(Debug)]
</span><span class="boring">struct Rectangle {
</span><span class="boring"> width: u32,
</span><span class="boring"> height: u32,
</span><span class="boring">}
</span>// --snip--
impl Rectangle {
fn can_hold(&amp;self, other: &amp;Rectangle) -&gt; bool {
self.width &lt; other.width &amp;&amp; self.height &gt; other.height
}
}
</code></pre></pre>
<p>Running the tests now produces the following:</p>
<pre><code class="language-text">running 2 tests
test tests::smaller_cannot_hold_larger ... ok
test tests::larger_can_hold_smaller ... FAILED
failures:
---- tests::larger_can_hold_smaller stdout ----
thread 'tests::larger_can_hold_smaller' panicked at 'assertion failed:
larger.can_hold(&amp;smaller)', src/lib.rs:22:9
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
tests::larger_can_hold_smaller
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>Our tests caught the bug! Because <code>larger.width</code> is 8 and <code>smaller.width</code> is
5, the comparison of the widths in <code>can_hold</code> now returns <code>false</code>: 8 is not
less than 5.</p>
<h3><a class="header" href="#testing-equality-with-the-assert_eq-and-assert_ne-macros" id="testing-equality-with-the-assert_eq-and-assert_ne-macros">Testing Equality with the <code>assert_eq!</code> and <code>assert_ne!</code> Macros</a></h3>
<p>A common way to test functionality is to compare the result of the code under
test to the value you expect the code to return to make sure they’re equal. You
could do this using the <code>assert!</code> macro and passing it an expression using the
<code>==</code> operator. However, this is such a common test that the standard library
provides a pair of macros—<code>assert_eq!</code> and <code>assert_ne!</code>—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
fails, which makes it easier to see <em>why</em> the test failed; conversely, the
<code>assert!</code> macro only indicates that it got a <code>false</code> value for the <code>==</code>
expression, not the values that lead to the <code>false</code> value.</p>
<p>In Listing 11-7, we write a function named <code>add_two</code> that adds <code>2</code> to its
parameter and returns the result. Then we test this function using the
<code>assert_eq!</code> macro.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>pub fn add_two(a: i32) -&gt; i32 {
a + 2
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_adds_two() {
assert_eq!(4, add_two(2));
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-7: Testing the function <code>add_two</code> using the
<code>assert_eq!</code> macro</span></p>
<p>Let’s check that it passes!</p>
<pre><code class="language-text">running 1 test
test tests::it_adds_two ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>The first argument we gave to the <code>assert_eq!</code> macro, <code>4</code>, is equal to the
result of calling <code>add_two(2)</code>. The line for this test is <code>test tests::it_adds_two ... ok</code>, and the <code>ok</code> text indicates that our test passed!</p>
<p>Let’s introduce a bug into our code to see what it looks like when a test that
uses <code>assert_eq!</code> fails. Change the implementation of the <code>add_two</code> function to
instead add <code>3</code>:</p>
<pre><pre class="playpen"><code class="language-rust not_desired_behavior"><span class="boring">fn main() {}
</span>pub fn add_two(a: i32) -&gt; i32 {
a + 3
}
</code></pre></pre>
<p>Run the tests again:</p>
<pre><code class="language-text">running 1 test
test tests::it_adds_two ... FAILED
failures:
---- tests::it_adds_two stdout ----
thread 'tests::it_adds_two' panicked at 'assertion failed: `(left == right)`
left: `4`,
right: `5`', src/lib.rs:11:9
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
tests::it_adds_two
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>Our test caught the bug! The <code>it_adds_two</code> test failed, displaying the message
<code>assertion failed: `(left == right)`</code> and showing that <code>left</code> was <code>4</code> and
<code>right</code> was <code>5</code>. This message is useful and helps us start debugging: it means
the <code>left</code> argument to <code>assert_eq!</code> was <code>4</code> but the <code>right</code> argument, where we
had <code>add_two(2)</code>, was <code>5</code>.</p>
<p>Note that in some languages and test frameworks, the parameters to the
functions that assert two values are equal are called <code>expected</code> and <code>actual</code>,
and the order in which we specify the arguments matters. However, in Rust,
they’re called <code>left</code> and <code>right</code>, and the order in which we specify the value
we expect and the value that the code under test produces doesn’t matter. We
could write the assertion in this test as <code>assert_eq!(add_two(2), 4)</code>, which
would result in a failure message that displays <code>assertion failed: `(left == right)`</code> and that <code>left</code> was <code>5</code> and <code>right</code> was <code>4</code>.</p>
<p>The <code>assert_ne!</code> 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
what a value <em>will</em> be, but we know what the value definitely <em>won’t</em> be if our
code is functioning as we intend. For example, if we’re testing a function that
is guaranteed to change its input in some way, but the way in which the input
is changed depends on the day of the week that we run our tests, the best thing
to assert might be that the output of the function is not equal to the input.</p>
<p>Under the surface, the <code>assert_eq!</code> and <code>assert_ne!</code> macros use the operators
<code>==</code> and <code>!=</code>, respectively. When the assertions fail, these macros print their
arguments using debug formatting, which means the values being compared must
implement the <code>PartialEq</code> and <code>Debug</code> traits. All the primitive types and most
of the standard library types implement these traits. For structs and enums
that you define, you’ll need to implement <code>PartialEq</code> to assert that values of
those types are equal or not equal. You’ll need to implement <code>Debug</code> 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 <code>#[derive(PartialEq, Debug)]</code> annotation to your struct or enum
definition. See Appendix C, <a href="appendix-03-derivable-traits.html">“Derivable Traits,”</a><!-- ignore
--> for more details about these and other derivable traits.</p>
<h3><a class="header" href="#adding-custom-failure-messages" id="adding-custom-failure-messages">Adding Custom Failure Messages</a></h3>
<p>You can also add a custom message to be printed with the failure message as
optional arguments to the <code>assert!</code>, <code>assert_eq!</code>, and <code>assert_ne!</code> macros. Any
arguments specified after the one required argument to <code>assert!</code> or the two
required arguments to <code>assert_eq!</code> and <code>assert_ne!</code> are passed along to the
<code>format!</code> macro (discussed in Chapter 8 in the <a href="ch08-02-strings.html#concatenation-with-the--operator-or-the-format-macro">“Concatenation with the <code>+</code>
Operator or the <code>format!</code>
Macro”</a><!-- ignore -->
section), so you can pass a format string that contains <code>{}</code> placeholders and
values to go in those placeholders. Custom messages are useful to document
what an assertion means; when a test fails, you’ll have a better idea of what
the problem is with the code.</p>
<p>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:</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>pub fn greeting(name: &amp;str) -&gt; String {
format!(&quot;Hello {}!&quot;, name)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn greeting_contains_name() {
let result = greeting(&quot;Carol&quot;);
assert!(result.contains(&quot;Carol&quot;));
}
}
</code></pre></pre>
<p>The requirements for this program haven’t been agreed upon yet, and we’re
pretty sure the <code>Hello</code> 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,
so instead of checking for exact equality to the value returned from the
<code>greeting</code> function, we’ll just assert that the output contains the text of the
input parameter.</p>
<p>Let’s introduce a bug into this code by changing <code>greeting</code> to not include
<code>name</code> to see what this test failure looks like:</p>
<pre><pre class="playpen"><code class="language-rust not_desired_behavior"><span class="boring">fn main() {}
</span>pub fn greeting(name: &amp;str) -&gt; String {
String::from(&quot;Hello!&quot;)
}
</code></pre></pre>
<p>Running this test produces the following:</p>
<pre><code class="language-text">running 1 test
test tests::greeting_contains_name ... FAILED
failures:
---- tests::greeting_contains_name stdout ----
thread 'tests::greeting_contains_name' panicked at 'assertion failed:
result.contains(&quot;Carol&quot;)', src/lib.rs:12:9
note: Run with `RUST_BACKTRACE=1` for a backtrace.
failures:
tests::greeting_contains_name
</code></pre>
<p>This result just indicates that the assertion failed and which line the
assertion is on. A more useful failure message in this case would print the
value we got from the <code>greeting</code> function. Let’s change the test function,
giving it a custom failure message made from a format string with a placeholder
filled in with the actual value we got from the <code>greeting</code> function:</p>
<pre><code class="language-rust ignore">#[test]
fn greeting_contains_name() {
let result = greeting(&quot;Carol&quot;);
assert!(
result.contains(&quot;Carol&quot;),
&quot;Greeting did not contain name, value was `{}`&quot;, result
);
}
</code></pre>
<p>Now when we run the test, we’ll get a more informative error message:</p>
<pre><code class="language-text">---- tests::greeting_contains_name stdout ----
thread 'tests::greeting_contains_name' panicked at 'Greeting did not
contain name, value was `Hello!`', src/lib.rs:12:9
note: Run with `RUST_BACKTRACE=1` for a backtrace.
</code></pre>
<p>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.</p>
<h3><a class="header" href="#checking-for-panics-with-should_panic" id="checking-for-panics-with-should_panic">Checking for Panics with <code>should_panic</code></a></h3>
<p>In addition to checking that our code returns the correct values we expect,
it’s also important to check that our code handles error conditions as we
expect. For example, consider the <code>Guess</code> type that we created in Chapter 9,
Listing 9-10. Other code that uses <code>Guess</code> depends on the guarantee that <code>Guess</code>
instances will contain only values between 1 and 100. We can write a test that
ensures that attempting to create a <code>Guess</code> instance with a value outside that
range panics.</p>
<p>We do this by adding another attribute, <code>should_panic</code>, to our test function.
This attribute makes a test pass if the code inside the function panics; the
test will fail if the code inside the function doesn’t panic.</p>
<p>Listing 11-8 shows a test that checks that the error conditions of <code>Guess::new</code>
happen when we expect them to.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span>pub struct Guess {
value: i32,
}
impl Guess {
pub fn new(value: i32) -&gt; Guess {
if value &lt; 1 || value &gt; 100 {
panic!(&quot;Guess value must be between 1 and 100, got {}.&quot;, value);
}
Guess {
value
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
#[should_panic]
fn greater_than_100() {
Guess::new(200);
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-8: Testing that a condition will cause a
<code>panic!</code></span></p>
<p>We place the <code>#[should_panic]</code> attribute after the <code>#[test]</code> attribute and
before the test function it applies to. Let’s look at the result when this test
passes:</p>
<pre><code class="language-text">running 1 test
test tests::greater_than_100 ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>Looks good! Now let’s introduce a bug in our code by removing the condition
that the <code>new</code> function will panic if the value is greater than 100:</p>
<pre><pre class="playpen"><code class="language-rust not_desired_behavior"><span class="boring">fn main() {}
</span><span class="boring">pub struct Guess {
</span><span class="boring"> value: i32,
</span><span class="boring">}
</span><span class="boring">
</span>// --snip--
impl Guess {
pub fn new(value: i32) -&gt; Guess {
if value &lt; 1 {
panic!(&quot;Guess value must be between 1 and 100, got {}.&quot;, value);
}
Guess {
value
}
}
}
</code></pre></pre>
<p>When we run the test in Listing 11-8, it will fail:</p>
<pre><code class="language-text">running 1 test
test tests::greater_than_100 ... FAILED
failures:
failures:
tests::greater_than_100
test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
</code></pre>
<p>We don’t get a very helpful message in this case, but when we look at the test
function, we see that it’s annotated with <code>#[should_panic]</code>. The failure we got
means that the code in the test function did not cause a panic.</p>
<p>Tests that use <code>should_panic</code> can be imprecise because they only indicate that
the code has caused some panic. A <code>should_panic</code> test would pass even if the
test panics for a different reason from the one we were expecting to happen. To
make <code>should_panic</code> tests more precise, we can add an optional <code>expected</code>
parameter to the <code>should_panic</code> attribute. The test harness will make sure that
the failure message contains the provided text. For example, consider the
modified code for <code>Guess</code> in Listing 11-9 where the <code>new</code> function panics with
different messages depending on whether the value is too small or too large.</p>
<p><span class="filename">Filename: src/lib.rs</span></p>
<pre><pre class="playpen"><code class="language-rust"><span class="boring">fn main() {}
</span><span class="boring">pub struct Guess {
</span><span class="boring"> value: i32,
</span><span class="boring">}
</span><span class="boring">
</span>// --snip--
impl Guess {
pub fn new(value: i32) -&gt; Guess {
if value &lt; 1 {
panic!(&quot;Guess value must be greater than or equal to 1, got {}.&quot;,
value);
} else if value &gt; 100 {
panic!(&quot;Guess value must be less than or equal to 100, got {}.&quot;,
value);
}
Guess {
value
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
#[should_panic(expected = &quot;Guess value must be less than or equal to 100&quot;)]
fn greater_than_100() {
Guess::new(200);
}
}
</code></pre></pre>
<p><span class="caption">Listing 11-9: Testing that a condition will cause a
<code>panic!</code> with a particular panic message</span></p>
<p>This test will pass because the value we put in the <code>should_panic</code> attribute’s
<code>expected</code> parameter is a substring of the message that the <code>Guess::new</code>
function panics with. We could have specified the entire panic message that we
expect, which in this case would be <code>Guess value must be less than or equal to 100, got 200.</code> What you choose to specify in the expected parameter for
<code>should_panic</code> 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 <code>else if value &gt; 100</code> case.</p>
<p>To see what happens when a <code>should_panic</code> test with an <code>expected</code> message
fails, let’s again introduce a bug into our code by swapping the bodies of the
<code>if value &lt; 1</code> and the <code>else if value &gt; 100</code> blocks:</p>
<pre><code class="language-rust ignore not_desired_behavior">if value &lt; 1 {
panic!(&quot;Guess value must be less than or equal to 100, got {}.&quot;, value);
} else if value &gt; 100 {
panic!(&quot;Guess value must be greater than or equal to 1, got {}.&quot;, value);
}
</code></pre>
<p>This time when we run the <code>should_panic</code> test, it will fail:</p>
<pre><code class="language-text">running 1 test
test tests::greater_than_100 ... FAILED
failures:
---- tests::greater_than_100 stdout ----
thread 'tests::greater_than_100' panicked at 'Guess value must be
greater than or equal to 1, got 200.', src/lib.rs:11:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.
note: Panic did not include expected string 'Guess value must be 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
</code></pre>
<p>The failure message indicates that this test did indeed panic as we expected,
but the panic message did not include the expected string <code>'Guess value must be less than or equal to 100'</code>. The panic message that we did get in this case was
<code>Guess value must be greater than or equal to 1, got 200.</code> Now we can start
figuring out where our bug is!</p>
<h3><a class="header" href="#using-resultt-e-in-tests" id="using-resultt-e-in-tests">Using <code>Result&lt;T, E&gt;</code> in Tests</a></h3>
<p>So far, we’ve written tests that panic when they fail. We can also write tests
that use <code>Result&lt;T, E&gt;</code>! Here’s the test from Listing 11-1, rewritten to use
<code>Result&lt;T, E&gt;</code> and return an <code>Err</code> instead of panicking:</p>
<pre><pre class="playpen"><code class="language-rust">
<span class="boring">#![allow(unused_variables)]
</span><span class="boring">fn main() {
</span>#[cfg(test)]
mod tests {
#[test]
fn it_works() -&gt; Result&lt;(), String&gt; {
if 2 + 2 == 4 {
Ok(())
} else {
Err(String::from(&quot;two plus two does not equal four&quot;))
}
}
}
<span class="boring">}
</span></code></pre></pre>
<p>The <code>it_works</code> function now has a return type, <code>Result&lt;(), String&gt;</code>. In the
body of the function, rather than calling the <code>assert_eq!</code> macro, we return
<code>Ok(())</code> when the test passes and an <code>Err</code> with a <code>String</code> inside when the test
fails.</p>
<p>Writing tests so they return a <code>Result&lt;T, E&gt;</code> enables you to use the question
mark operator in the body of tests, which can be a convenient way to write
tests that should fail if any operation within them returns an <code>Err</code> variant.</p>
<p>You can’t use the <code>#[should_panic]</code> annotation on tests that use <code>Result&lt;T, E&gt;</code>. Instead, you should return an <code>Err</code> value directly when the test should
fail.</p>
<p>Now that you know several ways to write tests, let’s look at what is happening
when we run our tests and explore the different options we can use with <code>cargo test</code>.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="ch11-00-testing.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="ch11-02-running-tests.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="ch11-00-testing.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="ch11-02-running-tests.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playpen_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="ferris.js"></script>
</body>
</html>
Reference in New Issue Copy Permalink