<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/doc/man/cargo-test.md - fork/cargo @ 0.92.0</title>
<meta name="description" content="src/doc/man/cargo-test.md in fork/cargo at 0.92.0.">
<meta property="og:title" content="src/doc/man/cargo-test.md - fork/cargo @ 0.92.0">
<meta property="og:description" content="src/doc/man/cargo-test.md in fork/cargo at 0.92.0.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="0.92.0" data-tip="ea2d97820c16195b0ca3fadb4319fe512c199a43">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/cargo</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/cargo</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Eric Huss</span><span class="commit-message" data-commit="3b379fcc541b39321a7758552d37e5e0cc4277b9">fix: Switch from --nocapture to --no-capture (#15930)</span><span class="snapshot-sha sha" data-commit="3b379fcc541b39321a7758552d37e5e0cc4277b9">3b379fcc5</span><time datetime="2025-09-05T22:49:01+00:00" title="2025-09-05 22:49:01 +0000">2025-09-05</time></p>
<header class="topbar"><details class="switcher"><summary>0.92.0</summary><div class="menu"><strong>branches</strong><a href="/fork/cargo/ref/master/">master</a><strong>tags</strong><a href="/fork/cargo/ref/0.87.0/">0.87.0</a><a href="/fork/cargo/ref/0.88.0/">0.88.0</a><a href="/fork/cargo/ref/0.89.0/">0.89.0</a><a href="/fork/cargo/ref/0.90.0/">0.90.0</a><a href="/fork/cargo/ref/0.91.0/">0.91.0</a><a class="current" href="/fork/cargo/ref/0.92.0/">0.92.0</a><a href="/fork/cargo/ref/0.93.0/">0.93.0</a><a href="/fork/cargo/ref/home-0.5.12/">home-0.5.12</a><a class="all" href="/fork/cargo/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/cargo/">cargo</a> / <a href="/fork/cargo/ref/0.92.0/tree/src/">src</a> / <a href="/fork/cargo/ref/0.92.0/tree/src/doc/">doc</a> / <a href="/fork/cargo/ref/0.92.0/tree/src/doc/man/">man</a> / <span class="cur">cargo-test.md</span></nav>
<span class="view-stats"><span>6.7 KiB</span><span>223 lines</span></span><span class="actions"><a class="raw" href="/fork/cargo/raw/9e0271e12ebe671c0335bf54d868324d16fded25/src/doc/man/cargo-test.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>cargo-test(1)</h1>
<p>{{<del>*set command="test"}}
{{</del>*set actionverb="Test"}}
{{<del>*set nouns="tests"}}
{{</del>*set multitarget=true}}</p>
<h2>NAME</h2>
<p>cargo-test --- Execute unit and integration tests of a package</p>
<h2>SYNOPSIS</h2>
<p><code>cargo test</code> [<em>options</em>] [<em>testname</em>] [<code>--</code> <em>test-options</em>]</p>
<h2>DESCRIPTION</h2>
<p>Compile and execute unit, integration, and documentation tests.</p>
<p>The test filtering argument <code>TESTNAME</code> and all the arguments following the two
dashes (<code>--</code>) are passed to the test binaries and thus to <em>libtest</em> (rustc's
built in unit-test and micro-benchmarking framework).  If you're passing
arguments to both Cargo and the binary, the ones after <code>--</code> go to the binary,
the ones before go to Cargo.  For details about libtest's arguments see the
output of <code>cargo test -- --help</code> and check out the rustc book's chapter on
how tests work at <a href="https://doc.rust-lang.org/rustc/tests/index.html">https://doc.rust-lang.org/rustc/tests/index.html</a>.</p>
<p>As an example, this will filter for tests with <code>foo</code> in their name and run them
on 3 threads in parallel:</p>
<pre><code>cargo test foo -- --test-threads 3
</code></pre>
<p>Tests are built with the <code>--test</code> option to <code>rustc</code> which creates a special
executable by linking your code with libtest. The executable automatically
runs all functions annotated with the <code>#[test]</code> attribute in multiple threads.
<code>#[bench]</code> annotated functions will also be run with one iteration to verify
that they are functional.</p>
<p>If the package contains multiple test targets, each target compiles to a
special executable as aforementioned, and then is run serially.</p>
<p>The libtest harness may be disabled by setting <code>harness = false</code> in the target
manifest settings, in which case your code will need to provide its own <code>main</code>
function to handle running tests.</p>
<h3>Documentation tests</h3>
<p>Documentation tests are also run by default, which is handled by <code>rustdoc</code>. It
extracts code samples from documentation comments of the library target, and
then executes them.</p>
<p>Different from normal test targets, each code block compiles to a doctest
executable on the fly with <code>rustc</code>. These executables run in parallel in
separate processes. The compilation of a code block is in fact a part of test
function controlled by libtest, so some options such as <code>--jobs</code> might not
take effect. Note that this execution model of doctests is not guaranteed
and may change in the future; beware of depending on it.</p>
<p>See the <a href="https://doc.rust-lang.org/rustdoc/">rustdoc book</a> for more information
on writing doc tests.</p>
<h3>Working directory of tests</h3>
<p>The working directory when running each unit and integration test is set to the
root directory of the package the test belongs to.
Setting the working directory of tests to the package's root directory makes it
possible for tests to reliably access the package's files using relative paths,
regardless from where <code>cargo test</code> was executed from.</p>
<p>For documentation tests, the working directory when invoking <code>rustdoc</code> is set to
the workspace root directory, and is also the directory <code>rustdoc</code> uses as the
compilation directory of each documentation test.
The working directory when running each documentation test is set to the root
directory of the package the test belongs to, and is controlled via <code>rustdoc</code>'s
<code>--test-run-directory</code> option.</p>
<h2>OPTIONS</h2>
<h3>Test Options</h3>
<p>{{&gt; options-test }}</p>
<p>{{&gt; section-package-selection }}</p>
<h3>Target Selection</h3>
<p>When no target selection options are given, <code>cargo test</code> will build the
following targets of the selected packages:</p>
<ul>
<li>lib --- used to link with binaries, examples, integration tests, and doc tests</li>
<li>bins (only if integration tests are built and required features are
available)</li>
<li>examples --- to ensure they compile</li>
<li>lib as a unit test</li>
<li>bins as unit tests</li>
<li>integration tests</li>
<li>doc tests for the lib target</li>
</ul>
<p>The default behavior can be changed by setting the <code>test</code> flag for the target
in the manifest settings. Setting examples to <code>test = true</code> will build and run
the example as a test, replacing the example's <code>main</code> function with the
libtest harness. If you don't want the <code>main</code> function replaced, also include
<code>harness = false</code>, in which case the example will be built and executed as-is.</p>
<p>Setting targets to <code>test = false</code> will stop them from being tested by default.
Target selection options that take a target by name (such as <code>--example foo</code>)
ignore the <code>test</code> flag and will always test the given target.</p>
<p>Doc tests for libraries may be disabled by setting <code>doctest = false</code> for the
library in the manifest.</p>
<p>See <a href="../reference/cargo-targets.html#configuring-a-target">Configuring a target</a>
for more information on per-target settings.</p>
<p>{{&gt; options-targets-bin-auto-built }}</p>
<p>{{&gt; options-targets }}</p>
<p>{{#options}}</p>
<p>{{#option "<code>--doc</code>" }}
Test only the library's documentation. This cannot be mixed with other
target options.
{{/option}}</p>
<p>{{/options}}</p>
<p>{{&gt; section-features }}</p>
<h3>Compilation Options</h3>
<p>{{#options}}</p>
<p>{{&gt; options-target-triple }}</p>
<p>{{&gt; options-release }}</p>
<p>{{&gt; options-profile }}</p>
<p>{{&gt; options-timings }}</p>
<p>{{/options}}</p>
<h3>Output Options</h3>
<p>{{#options}}
{{&gt; options-target-dir }}
{{/options}}</p>
<h3>Display Options</h3>
<p>By default the Rust test harness hides output from test execution to keep
results readable. Test output can be recovered (e.g., for debugging) by passing
<code>--no-capture</code> to the test binaries:</p>
<pre><code>cargo test -- --no-capture
</code></pre>
<p>{{#options}}</p>
<p>{{&gt; options-display }}</p>
<p>{{&gt; options-message-format }}</p>
<p>{{/options}}</p>
<h3>Manifest Options</h3>
<p>{{#options}}</p>
<p>{{&gt; options-manifest-path }}</p>
<p>{{&gt; options-ignore-rust-version }}</p>
<p>{{&gt; options-locked }}</p>
<p>{{&gt; options-lockfile-path }}</p>
<p>{{/options}}</p>
<p>{{&gt; section-options-common }}</p>
<h3>Miscellaneous Options</h3>
<p>The <code>--jobs</code> argument affects the building of the test executable but does not
affect how many threads are used when running the tests. The Rust test harness
includes an option to control the number of threads used:</p>
<pre><code>cargo test -j 2 -- --test-threads=2
</code></pre>
<p>{{#options}}</p>
<p>{{&gt; options-jobs }}
{{&gt; options-future-incompat }}</p>
<p>{{/options}}</p>
<p>While <code>cargo test</code> involves compilation, it does not provide a <code>--keep-going</code>
flag. Use <code>--no-fail-fast</code> to run as many tests as possible without stopping at
the first failure. To "compile" as many tests as possible, use <code>--tests</code> to
build test binaries separately. For example:</p>
<pre><code>cargo build --tests --keep-going
cargo test --tests --no-fail-fast
</code></pre>
<p>{{&gt; section-environment }}</p>
<p>{{&gt; section-exit-status }}</p>
<h2>EXAMPLES</h2>
<ol>
<li>
<p>Execute all the unit and integration tests of the current package:</p>
<pre><code>cargo test
</code></pre>
</li>
<li>
<p>Run only tests whose names match against a filter string:</p>
<pre><code>cargo test name_filter
</code></pre>
</li>
<li>
<p>Run only a specific test within a specific integration test:</p>
<pre><code>cargo test --test int_test_name -- modname::test_name
</code></pre>
</li>
</ol>
<h2>SEE ALSO</h2>
<p>{{man "cargo" 1}}, {{man "cargo-bench" 1}}, <a href="../reference/cargo-targets.html#tests">types of tests</a>, <a href="https://doc.rust-lang.org/rustc/tests/index.html">how to write tests</a></p>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>cargo-test(1)</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">{{~*set command=&quot;test&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">{{~*set actionverb=&quot;Test&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">{{~*set nouns=&quot;tests&quot;}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">{{~*set multitarget=true}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>##</a-p> <a-tt>NAME</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">cargo-test --- Execute unit and integration tests of a package</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"><a-p>##</a-p> <a-tt>SYNOPSIS</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">`cargo test` [_options_] [_testname_] [`--` _test-options_]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>##</a-p> <a-tt>DESCRIPTION</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">Compile and execute unit, integration, and documentation tests.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">The test filtering argument `TESTNAME` and all the arguments following the two</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc&#39;s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">built in unit-test and micro-benchmarking framework).  If you&#39;re passing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">arguments to both Cargo and the binary, the ones after `--` go to the binary,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">the ones before go to Cargo.  For details about libtest&#39;s arguments see the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">output of `cargo test -- --help` and check out the rustc book&#39;s chapter on</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">how tests work at &lt;https://doc.rust-lang.org/rustc/tests/index.html&gt;.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">As an example, this will filter for tests with `foo` in their name and run them</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">on 3 threads in parallel:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-tl>    cargo test foo -- --test-threads 3</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">Tests are built with the `--test` option to `rustc` which creates a special</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">executable by linking your code with libtest. The executable automatically</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">runs all functions annotated with the `#[test]` attribute in multiple threads.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">`#[bench]` annotated functions will also be run with one iteration to verify</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">that they are functional.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">If the package contains multiple test targets, each target compiles to a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text">special executable as aforementioned, and then is run serially.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">The libtest harness may be disabled by setting `harness = false` in the target</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">manifest settings, in which case your code will need to provide its own `main`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">function to handle running tests.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>###</a-p> <a-tt>Documentation tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">Documentation tests are also run by default, which is handled by `rustdoc`. It</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">extracts code samples from documentation comments of the library target, and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">then executes them.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">Different from normal test targets, each code block compiles to a doctest</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">executable on the fly with `rustc`. These executables run in parallel in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">separate processes. The compilation of a code block is in fact a part of test</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">function controlled by libtest, so some options such as `--jobs` might not</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">take effect. Note that this execution model of doctests is not guaranteed</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">and may change in the future; beware of depending on it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">on writing doc tests.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>###</a-p> <a-tt>Working directory of tests</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">The working directory when running each unit and integration test is set to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">root directory of the package the test belongs to.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">Setting the working directory of tests to the package&#39;s root directory makes it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">possible for tests to reliably access the package&#39;s files using relative paths,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">regardless from where `cargo test` was executed from.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">For documentation tests, the working directory when invoking `rustdoc` is set to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">the workspace root directory, and is also the directory `rustdoc` uses as the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">compilation directory of each documentation test.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">The working directory when running each documentation test is set to the root</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">directory of the package the test belongs to, and is controlled via `rustdoc`&#39;s</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">`--test-run-directory` option.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>##</a-p> <a-tt>OPTIONS</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>###</a-p> <a-tt>Test Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text">{{&gt; options-test }}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">{{&gt; section-package-selection }}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"><a-p>###</a-p> <a-tt>Target Selection</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">When no target selection options are given, `cargo test` will build the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">following targets of the selected packages:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"><a-p>- </a-p>lib --- used to link with binaries, examples, integration tests, and doc tests</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>- </a-p>bins (only if integration tests are built and required features are</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>  </a-p>available)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"><a-p>- </a-p>examples --- to ensure they compile</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>- </a-p>lib as a unit test</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"><a-p>- </a-p>bins as unit tests</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>- </a-p>integration tests</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>- </a-p>doc tests for the lib target</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>The default behavior can be changed by setting the `test` flag for the target</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"><a-p>in the manifest settings. Setting examples to `test = true` will build and run</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p>the example as a test, replacing the example&#39;s `main` function with the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>libtest harness. If you don&#39;t want the `main` function replaced, also include</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>`harness = false`, in which case the example will be built and executed as-is.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"><a-p>Setting targets to `test = false` will stop them from being tested by default.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p>Target selection options that take a target by name (such as `--example foo`)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>ignore the `test` flag and will always test the given target.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>Doc tests for libraries may be disabled by setting `doctest = false` for the</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>library in the manifest.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"><a-p>See [Configuring a target](../reference/cargo-targets.html#configuring-a-target)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p>for more information on per-target settings.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>{{&gt; options-targets-bin-auto-built }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>{{&gt; options-targets }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"><a-p>{{#option &quot;`--doc`&quot; }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>Test only the library&#39;s documentation. This cannot be mixed with other</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"><a-p>target options.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>{{/option}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>{{&gt; section-features }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>### </a-p><a-tt>Compilation Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>{{&gt; options-target-triple }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>{{&gt; options-release }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>{{&gt; options-profile }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text"><a-p>{{&gt; options-timings }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text"><a-p>### </a-p><a-tt>Output Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text"><a-p>{{&gt; options-target-dir }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text"><a-p>### </a-p><a-tt>Display Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text"><a-p>By default the Rust test harness hides output from test execution to keep</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"><a-p>results readable. Test output can be recovered (e.g., for debugging) by passing</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"><a-p>`--no-capture` to the test binaries:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text"><a-tl>    cargo test -- --no-capture</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"><a-p>{{&gt; options-display }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text"><a-p>{{&gt; options-message-format }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text"><a-p>### </a-p><a-tt>Manifest Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"><a-p>{{&gt; options-manifest-path }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"><a-p>{{&gt; options-ignore-rust-version }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text"><a-p>{{&gt; options-locked }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text"><a-p>{{&gt; options-lockfile-path }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"><a-p>{{&gt; section-options-common }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text"><a-p>### </a-p><a-tt>Miscellaneous Options</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"><a-p>The `--jobs` argument affects the building of the test executable but does not</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text"><a-p>affect how many threads are used when running the tests. The Rust test harness</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"><a-p>includes an option to control the number of threads used:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text"><a-tl>    cargo test -j 2 -- --test-threads=2</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text"><a-p>{{#options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"><a-p>{{&gt; options-jobs }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text"><a-p>{{&gt; options-future-incompat }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text"><a-p>{{/options}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"><a-p>While `cargo test` involves compilation, it does not provide a `--keep-going`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text"><a-p>flag. Use `--no-fail-fast` to run as many tests as possible without stopping at</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"><a-p>the first failure. To &quot;compile&quot; as many tests as possible, use `--tests` to</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text"><a-p>build test binaries separately. For example:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"><a-tl>    cargo build --tests --keep-going</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text"><a-p>    </a-p><a-tl>cargo test --tests --no-fail-fast</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text"><a-p>{{&gt; section-environment }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text"><a-p>{{&gt; section-exit-status }}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text"><a-p>## </a-p><a-tt>EXAMPLES</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text"><a-p>1. Execute all the unit and integration tests of the current package:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text"><a-p>   </a-p><a-tl>    cargo test</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text"><a-p>2. Run only tests whose names match against a filter string:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"><a-p>   </a-p><a-tl>    cargo test name_filter</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"><a-p>3. Run only a specific test within a specific integration test:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"><a-p>   </a-p><a-tl>    cargo test --test int_test_name -- modname::test_name</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"><a-p>## </a-p><a-tt>SEE ALSO</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text">{{man &quot;cargo&quot; 1}}, {{man &quot;cargo-bench&quot; 1}}, [types of tests](../reference/cargo-targets.html#tests), [how to write tests](https://doc.rust-lang.org/rustc/tests/index.html)</span></span></pre></div></div>
</main>
</body>
</html>
