]>
Commit | Line | Data |
---|---|---|
2d4aa38b EH |
1 | # cargo-test(1) |
2 | ||
3 | ||
4 | ||
3e177e0f | 5 | |
2d4aa38b EH |
6 | ## NAME |
7 | ||
8 | cargo-test - Execute unit and integration tests of a package | |
9 | ||
10 | ## SYNOPSIS | |
11 | ||
12 | `cargo test` [_options_] [_testname_] [`--` _test-options_] | |
13 | ||
14 | ## DESCRIPTION | |
15 | ||
af0fbf42 | 16 | Compile and execute unit, integration, and documentation tests. |
2d4aa38b EH |
17 | |
18 | The test filtering argument `TESTNAME` and all the arguments following the two | |
19 | dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's | |
20 | built in unit-test and micro-benchmarking framework). If you're passing | |
21 | arguments to both Cargo and the binary, the ones after `--` go to the binary, | |
22 | the ones before go to Cargo. For details about libtest's arguments see the | |
c2e0d756 EH |
23 | output of `cargo test -- --help` and check out the rustc book's chapter on |
24 | how tests work at <https://doc.rust-lang.org/rustc/tests/index.html>. | |
2d4aa38b EH |
25 | |
26 | As an example, this will filter for tests with `foo` in their name and run them | |
27 | on 3 threads in parallel: | |
28 | ||
29 | cargo test foo -- --test-threads 3 | |
30 | ||
af0fbf42 WL |
31 | Tests are built with the `--test` option to `rustc` which creates a special |
32 | executable by linking your code with libtest. The executable automatically | |
33 | runs all functions annotated with the `#[test]` attribute in multiple threads. | |
34 | `#[bench]` annotated functions will also be run with one iteration to verify | |
35 | that they are functional. | |
36 | ||
37 | If the package contains multiple test targets, each target compiles to a | |
38 | special executable as aforementioned, and then is run serially. | |
2d4aa38b EH |
39 | |
40 | The libtest harness may be disabled by setting `harness = false` in the target | |
41 | manifest settings, in which case your code will need to provide its own `main` | |
42 | function to handle running tests. | |
43 | ||
fc6b3cc3 WL |
44 | ### Documentation tests |
45 | ||
2d4aa38b | 46 | Documentation tests are also run by default, which is handled by `rustdoc`. It |
78604581 | 47 | extracts code samples from documentation comments of the library target, and |
fc6b3cc3 WL |
48 | then executes them. |
49 | ||
50 | Different from normal test targets, each code block compiles to a doctest | |
dd8841f6 | 51 | executable on the fly with `rustc`. These executables run in parallel in |
fc6b3cc3 WL |
52 | separate processes. The compilation of a code block is in fact a part of test |
53 | function controlled by libtest, so some options such as `--jobs` might not | |
dd8841f6 WL |
54 | take effect. Note that this execution model of doctests is not guaranteed |
55 | and may change in the future; beware of depending on it. | |
fc6b3cc3 WL |
56 | |
57 | See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information | |
58 | on writing doc tests. | |
2d4aa38b EH |
59 | |
60 | ## OPTIONS | |
61 | ||
62 | ### Test Options | |
63 | ||
64 | <dl> | |
65 | ||
66 | <dt class="option-term" id="option-cargo-test---no-run"><a class="option-anchor" href="#option-cargo-test---no-run"></a><code>--no-run</code></dt> | |
67 | <dd class="option-desc">Compile, but don't run tests.</dd> | |
68 | ||
69 | ||
70 | <dt class="option-term" id="option-cargo-test---no-fail-fast"><a class="option-anchor" href="#option-cargo-test---no-fail-fast"></a><code>--no-fail-fast</code></dt> | |
71 | <dd class="option-desc">Run all tests regardless of failure. Without this flag, Cargo will exit | |
72 | after the first executable fails. The Rust test harness will run all tests | |
73 | within the executable to completion, this flag only applies to the executable | |
74 | as a whole.</dd> | |
75 | ||
76 | ||
77 | </dl> | |
78 | ||
79 | ||
80 | ### Package Selection | |
81 | ||
82 | By default, when no package selection options are given, the packages selected | |
83 | depend on the selected manifest file (based on the current working directory if | |
84 | `--manifest-path` is not given). If the manifest is the root of a workspace then | |
85 | the workspaces default members are selected, otherwise only the package defined | |
86 | by the manifest will be selected. | |
87 | ||
88 | The default members of a workspace can be set explicitly with the | |
89 | `workspace.default-members` key in the root manifest. If this is not set, a | |
90 | virtual workspace will include all workspace members (equivalent to passing | |
91 | `--workspace`), and a non-virtual workspace will include only the root crate itself. | |
92 | ||
93 | <dl> | |
94 | ||
95 | <dt class="option-term" id="option-cargo-test--p"><a class="option-anchor" href="#option-cargo-test--p"></a><code>-p</code> <em>spec</em>...</dt> | |
96 | <dt class="option-term" id="option-cargo-test---package"><a class="option-anchor" href="#option-cargo-test---package"></a><code>--package</code> <em>spec</em>...</dt> | |
1a86f232 | 97 | <dd class="option-desc">Test only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the |
4a61d8a4 WL |
98 | SPEC format. This flag may be specified multiple times and supports common Unix |
99 | glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally | |
100 | expanding glob patterns before Cargo handles them, you must use single quotes or | |
101 | double quotes around each pattern.</dd> | |
2d4aa38b EH |
102 | |
103 | ||
104 | <dt class="option-term" id="option-cargo-test---workspace"><a class="option-anchor" href="#option-cargo-test---workspace"></a><code>--workspace</code></dt> | |
105 | <dd class="option-desc">Test all members in the workspace.</dd> | |
106 | ||
107 | ||
108 | ||
109 | <dt class="option-term" id="option-cargo-test---all"><a class="option-anchor" href="#option-cargo-test---all"></a><code>--all</code></dt> | |
110 | <dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> | |
111 | ||
112 | ||
113 | ||
114 | <dt class="option-term" id="option-cargo-test---exclude"><a class="option-anchor" href="#option-cargo-test---exclude"></a><code>--exclude</code> <em>SPEC</em>...</dt> | |
115 | <dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the | |
4a61d8a4 WL |
116 | <code>--workspace</code> flag. This flag may be specified multiple times and supports |
117 | common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell | |
118 | accidentally expanding glob patterns before Cargo handles them, you must use | |
119 | single quotes or double quotes around each pattern.</dd> | |
2d4aa38b EH |
120 | |
121 | ||
122 | </dl> | |
123 | ||
124 | ||
125 | ### Target Selection | |
126 | ||
127 | When no target selection options are given, `cargo test` will build the | |
128 | following targets of the selected packages: | |
129 | ||
130 | - lib — used to link with binaries, examples, integration tests, and doc tests | |
131 | - bins (only if integration tests are built and required features are | |
132 | available) | |
133 | - examples — to ensure they compile | |
134 | - lib as a unit test | |
135 | - bins as unit tests | |
136 | - integration tests | |
137 | - doc tests for the lib target | |
138 | ||
139 | The default behavior can be changed by setting the `test` flag for the target | |
140 | in the manifest settings. Setting examples to `test = true` will build and run | |
141 | the example as a test. Setting targets to `test = false` will stop them from | |
142 | being tested by default. Target selection options that take a target by name | |
143 | ignore the `test` flag and will always test the given target. | |
144 | ||
145 | Doc tests for libraries may be disabled by setting `doctest = false` for the | |
146 | library in the manifest. | |
147 | ||
148 | Binary targets are automatically built if there is an integration test or | |
dd8841f6 WL |
149 | benchmark being selected to test. This allows an integration |
150 | test to execute the binary to exercise and test its behavior. | |
151 | The `CARGO_BIN_EXE_<name>` | |
2d4aa38b EH |
152 | [environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) |
153 | is set when the integration test is built so that it can use the | |
154 | [`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the | |
155 | executable. | |
156 | ||
370a481b | 157 | |
2d4aa38b | 158 | Passing target selection flags will test only the specified |
4a61d8a4 WL |
159 | targets. |
160 | ||
161 | Note that `--bin`, `--example`, `--test` and `--bench` flags also | |
162 | support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your | |
163 | shell accidentally expanding glob patterns before Cargo handles them, you must | |
164 | use single quotes or double quotes around each glob pattern. | |
2d4aa38b EH |
165 | |
166 | <dl> | |
167 | ||
168 | <dt class="option-term" id="option-cargo-test---lib"><a class="option-anchor" href="#option-cargo-test---lib"></a><code>--lib</code></dt> | |
169 | <dd class="option-desc">Test the package's library.</dd> | |
170 | ||
171 | ||
172 | <dt class="option-term" id="option-cargo-test---bin"><a class="option-anchor" href="#option-cargo-test---bin"></a><code>--bin</code> <em>name</em>...</dt> | |
4a61d8a4 WL |
173 | <dd class="option-desc">Test the specified binary. This flag may be specified multiple times |
174 | and supports common Unix glob patterns.</dd> | |
2d4aa38b EH |
175 | |
176 | ||
177 | <dt class="option-term" id="option-cargo-test---bins"><a class="option-anchor" href="#option-cargo-test---bins"></a><code>--bins</code></dt> | |
178 | <dd class="option-desc">Test all binary targets.</dd> | |
179 | ||
180 | ||
181 | ||
182 | <dt class="option-term" id="option-cargo-test---example"><a class="option-anchor" href="#option-cargo-test---example"></a><code>--example</code> <em>name</em>...</dt> | |
4a61d8a4 WL |
183 | <dd class="option-desc">Test the specified example. This flag may be specified multiple times |
184 | and supports common Unix glob patterns.</dd> | |
2d4aa38b EH |
185 | |
186 | ||
187 | <dt class="option-term" id="option-cargo-test---examples"><a class="option-anchor" href="#option-cargo-test---examples"></a><code>--examples</code></dt> | |
188 | <dd class="option-desc">Test all example targets.</dd> | |
189 | ||
190 | ||
191 | <dt class="option-term" id="option-cargo-test---test"><a class="option-anchor" href="#option-cargo-test---test"></a><code>--test</code> <em>name</em>...</dt> | |
192 | <dd class="option-desc">Test the specified integration test. This flag may be specified | |
4a61d8a4 | 193 | multiple times and supports common Unix glob patterns.</dd> |
2d4aa38b EH |
194 | |
195 | ||
196 | <dt class="option-term" id="option-cargo-test---tests"><a class="option-anchor" href="#option-cargo-test---tests"></a><code>--tests</code></dt> | |
197 | <dd class="option-desc">Test all targets in test mode that have the <code>test = true</code> manifest | |
198 | flag set. By default this includes the library and binaries built as | |
199 | unittests, and integration tests. Be aware that this will also build any | |
200 | required dependencies, so the lib target may be built twice (once as a | |
201 | unittest, and once as a dependency for binaries, integration tests, etc.). | |
202 | Targets may be enabled or disabled by setting the <code>test</code> flag in the | |
203 | manifest settings for the target.</dd> | |
204 | ||
205 | ||
206 | <dt class="option-term" id="option-cargo-test---bench"><a class="option-anchor" href="#option-cargo-test---bench"></a><code>--bench</code> <em>name</em>...</dt> | |
4a61d8a4 WL |
207 | <dd class="option-desc">Test the specified benchmark. This flag may be specified multiple |
208 | times and supports common Unix glob patterns.</dd> | |
2d4aa38b EH |
209 | |
210 | ||
211 | <dt class="option-term" id="option-cargo-test---benches"><a class="option-anchor" href="#option-cargo-test---benches"></a><code>--benches</code></dt> | |
212 | <dd class="option-desc">Test all targets in benchmark mode that have the <code>bench = true</code> | |
213 | manifest flag set. By default this includes the library and binaries built | |
214 | as benchmarks, and bench targets. Be aware that this will also build any | |
215 | required dependencies, so the lib target may be built twice (once as a | |
216 | benchmark, and once as a dependency for binaries, benchmarks, etc.). | |
217 | Targets may be enabled or disabled by setting the <code>bench</code> flag in the | |
218 | manifest settings for the target.</dd> | |
219 | ||
220 | ||
221 | <dt class="option-term" id="option-cargo-test---all-targets"><a class="option-anchor" href="#option-cargo-test---all-targets"></a><code>--all-targets</code></dt> | |
222 | <dd class="option-desc">Test all targets. This is equivalent to specifying <code>--lib --bins --tests --benches --examples</code>.</dd> | |
223 | ||
224 | ||
225 | </dl> | |
226 | ||
227 | ||
228 | <dl> | |
229 | ||
230 | <dt class="option-term" id="option-cargo-test---doc"><a class="option-anchor" href="#option-cargo-test---doc"></a><code>--doc</code></dt> | |
231 | <dd class="option-desc">Test only the library's documentation. This cannot be mixed with other | |
232 | target options.</dd> | |
233 | ||
234 | ||
235 | </dl> | |
236 | ||
237 | ### Feature Selection | |
238 | ||
d087aeb8 EH |
239 | The feature flags allow you to control which features are enabled. When no |
240 | feature options are given, the `default` feature is activated for every | |
241 | selected package. | |
2d4aa38b | 242 | |
d087aeb8 EH |
243 | See [the features documentation](../reference/features.html#command-line-feature-options) |
244 | for more details. | |
2d4aa38b EH |
245 | |
246 | <dl> | |
247 | ||
f7280457 | 248 | <dt class="option-term" id="option-cargo-test--F"><a class="option-anchor" href="#option-cargo-test--F"></a><code>-F</code> <em>features</em></dt> |
2d4aa38b | 249 | <dt class="option-term" id="option-cargo-test---features"><a class="option-anchor" href="#option-cargo-test---features"></a><code>--features</code> <em>features</em></dt> |
d087aeb8 EH |
250 | <dd class="option-desc">Space or comma separated list of features to activate. Features of workspace |
251 | members may be enabled with <code>package-name/feature-name</code> syntax. This flag may | |
252 | be specified multiple times, which enables all specified features.</dd> | |
2d4aa38b EH |
253 | |
254 | ||
255 | <dt class="option-term" id="option-cargo-test---all-features"><a class="option-anchor" href="#option-cargo-test---all-features"></a><code>--all-features</code></dt> | |
256 | <dd class="option-desc">Activate all available features of all selected packages.</dd> | |
257 | ||
258 | ||
259 | <dt class="option-term" id="option-cargo-test---no-default-features"><a class="option-anchor" href="#option-cargo-test---no-default-features"></a><code>--no-default-features</code></dt> | |
d087aeb8 | 260 | <dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> |
2d4aa38b EH |
261 | |
262 | ||
263 | </dl> | |
264 | ||
265 | ||
266 | ### Compilation Options | |
267 | ||
268 | <dl> | |
269 | ||
270 | <dt class="option-term" id="option-cargo-test---target"><a class="option-anchor" href="#option-cargo-test---target"></a><code>--target</code> <em>triple</em></dt> | |
08734a66 | 271 | <dd class="option-desc">Test for the given architecture. The default is the host architecture. The general format of the triple is |
2d4aa38b | 272 | <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a |
3e177e0f | 273 | list of supported targets. This flag may be specified multiple times.</p> |
2d4aa38b | 274 | <p>This may also be specified with the <code>build.target</code> |
1a86f232 | 275 | <a href="../reference/config.html">config value</a>.</p> |
2d4aa38b EH |
276 | <p>Note that specifying this flag makes Cargo run in a different mode where the |
277 | target artifacts are placed in a separate directory. See the | |
1a86f232 | 278 | <a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> |
2d4aa38b EH |
279 | |
280 | ||
281 | ||
c92d917f | 282 | <dt class="option-term" id="option-cargo-test--r"><a class="option-anchor" href="#option-cargo-test--r"></a><code>-r</code></dt> |
2d4aa38b | 283 | <dt class="option-term" id="option-cargo-test---release"><a class="option-anchor" href="#option-cargo-test---release"></a><code>--release</code></dt> |
895f5271 EH |
284 | <dd class="option-desc">Test optimized artifacts with the <code>release</code> profile. |
285 | See also the <code>--profile</code> option for choosing a specific profile by name.</dd> | |
286 | ||
287 | ||
288 | ||
289 | <dt class="option-term" id="option-cargo-test---profile"><a class="option-anchor" href="#option-cargo-test---profile"></a><code>--profile</code> <em>name</em></dt> | |
290 | <dd class="option-desc">Test with the given profile. | |
291 | See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> | |
2d4aa38b EH |
292 | |
293 | ||
294 | ||
db3776cf DO |
295 | <dt class="option-term" id="option-cargo-test---ignore-rust-version"><a class="option-anchor" href="#option-cargo-test---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> |
296 | <dd class="option-desc">Test the target even if the selected Rust compiler is older than the | |
297 | required Rust version as configured in the project's <code>rust-version</code> field.</dd> | |
298 | ||
299 | ||
300 | ||
c8542471 | 301 | <dt class="option-term" id="option-cargo-test---timings=fmts"><a class="option-anchor" href="#option-cargo-test---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> |
c0669189 JT |
302 | <dd class="option-desc">Output information how long each compilation takes, and track concurrency |
303 | information over time. Accepts an optional comma-separated list of output | |
086e71da | 304 | formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. |
81e1998e JT |
305 | Specifying an output format (rather than the default) is unstable and requires |
306 | <code>-Zunstable-options</code>. Valid output formats:</p> | |
c0669189 | 307 | <ul> |
a6e6b89d | 308 | <li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the |
e23f5f41 JT |
309 | <code>target/cargo-timings</code> directory with a report of the compilation. Also write |
310 | a report to the same directory with a timestamp in the filename if you want | |
311 | to look at older runs. HTML output is suitable for human consumption only, | |
312 | and does not provide machine-readable timing data.</li> | |
c0669189 JT |
313 | <li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON |
314 | information about timing information.</li> | |
315 | </ul></dd> | |
316 | ||
317 | ||
318 | ||
319 | ||
2d4aa38b EH |
320 | </dl> |
321 | ||
322 | ### Output Options | |
323 | ||
324 | <dl> | |
325 | <dt class="option-term" id="option-cargo-test---target-dir"><a class="option-anchor" href="#option-cargo-test---target-dir"></a><code>--target-dir</code> <em>directory</em></dt> | |
326 | <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be | |
327 | specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the | |
ee53210f WL |
328 | <code>build.target-dir</code> <a href="../reference/config.html">config value</a>. |
329 | Defaults to <code>target</code> in the root of the workspace.</dd> | |
2d4aa38b EH |
330 | |
331 | ||
332 | </dl> | |
333 | ||
334 | ### Display Options | |
335 | ||
336 | By default the Rust test harness hides output from test execution to keep | |
337 | results readable. Test output can be recovered (e.g., for debugging) by passing | |
338 | `--nocapture` to the test binaries: | |
339 | ||
340 | cargo test -- --nocapture | |
341 | ||
342 | <dl> | |
343 | ||
344 | <dt class="option-term" id="option-cargo-test--v"><a class="option-anchor" href="#option-cargo-test--v"></a><code>-v</code></dt> | |
345 | <dt class="option-term" id="option-cargo-test---verbose"><a class="option-anchor" href="#option-cargo-test---verbose"></a><code>--verbose</code></dt> | |
346 | <dd class="option-desc">Use verbose output. May be specified twice for "very verbose" output which | |
347 | includes extra output such as dependency warnings and build script output. | |
348 | May also be specified with the <code>term.verbose</code> | |
1a86f232 | 349 | <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
350 | |
351 | ||
352 | <dt class="option-term" id="option-cargo-test--q"><a class="option-anchor" href="#option-cargo-test--q"></a><code>-q</code></dt> | |
353 | <dt class="option-term" id="option-cargo-test---quiet"><a class="option-anchor" href="#option-cargo-test---quiet"></a><code>--quiet</code></dt> | |
cd4e2804 SJ |
354 | <dd class="option-desc">Do not print cargo log messages. |
355 | May also be specified with the <code>term.quiet</code> | |
356 | <a href="../reference/config.html">config value</a>.</dd> | |
2d4aa38b EH |
357 | |
358 | ||
359 | <dt class="option-term" id="option-cargo-test---color"><a class="option-anchor" href="#option-cargo-test---color"></a><code>--color</code> <em>when</em></dt> | |
360 | <dd class="option-desc">Control when colored output is used. Valid values:</p> | |
361 | <ul> | |
362 | <li><code>auto</code> (default): Automatically detect if color support is available on the | |
363 | terminal.</li> | |
364 | <li><code>always</code>: Always display colors.</li> | |
365 | <li><code>never</code>: Never display colors.</li> | |
366 | </ul> | |
367 | <p>May also be specified with the <code>term.color</code> | |
1a86f232 | 368 | <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
369 | |
370 | ||
371 | ||
372 | <dt class="option-term" id="option-cargo-test---message-format"><a class="option-anchor" href="#option-cargo-test---message-format"></a><code>--message-format</code> <em>fmt</em></dt> | |
373 | <dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times | |
374 | and consists of comma-separated values. Valid values:</p> | |
375 | <ul> | |
d174b773 CR |
376 | <li><code>human</code> (default): Display in a human-readable text format. Conflicts with |
377 | <code>short</code> and <code>json</code>.</li> | |
378 | <li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> | |
379 | and <code>json</code>.</li> | |
2d4aa38b | 380 | <li><code>json</code>: Emit JSON messages to stdout. See |
1a86f232 | 381 | <a href="../reference/external-tools.html#json-messages">the reference</a> |
d174b773 | 382 | for more details. Conflicts with <code>human</code> and <code>short</code>.</li> |
2d4aa38b | 383 | <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains |
d174b773 | 384 | the "short" rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> |
2d4aa38b EH |
385 | <li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages |
386 | contains embedded ANSI color codes for respecting rustc's default color | |
d174b773 | 387 | scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> |
195b1e0e | 388 | <li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics |
2d4aa38b EH |
389 | in JSON messages printed, but instead Cargo itself should render the |
390 | JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others | |
d174b773 | 391 | coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> |
2d4aa38b EH |
392 | </ul></dd> |
393 | ||
394 | ||
395 | ||
396 | </dl> | |
397 | ||
398 | ### Manifest Options | |
399 | ||
400 | <dl> | |
401 | ||
402 | <dt class="option-term" id="option-cargo-test---manifest-path"><a class="option-anchor" href="#option-cargo-test---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt> | |
403 | <dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the | |
404 | <code>Cargo.toml</code> file in the current directory or any parent directory.</dd> | |
405 | ||
406 | ||
407 | ||
408 | <dt class="option-term" id="option-cargo-test---frozen"><a class="option-anchor" href="#option-cargo-test---frozen"></a><code>--frozen</code></dt> | |
409 | <dt class="option-term" id="option-cargo-test---locked"><a class="option-anchor" href="#option-cargo-test---locked"></a><code>--locked</code></dt> | |
410 | <dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is | |
411 | up-to-date. If the lock file is missing, or it needs to be updated, Cargo will | |
412 | exit with an error. The <code>--frozen</code> flag also prevents Cargo from | |
413 | attempting to access the network to determine if it is out-of-date.</p> | |
414 | <p>These may be used in environments where you want to assert that the | |
415 | <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network | |
416 | access.</dd> | |
417 | ||
418 | ||
419 | <dt class="option-term" id="option-cargo-test---offline"><a class="option-anchor" href="#option-cargo-test---offline"></a><code>--offline</code></dt> | |
420 | <dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this | |
421 | flag, Cargo will stop with an error if it needs to access the network and | |
422 | the network is not available. With this flag, Cargo will attempt to | |
423 | proceed without the network if possible.</p> | |
424 | <p>Beware that this may result in different dependency resolution than online | |
425 | mode. Cargo will restrict itself to crates that are downloaded locally, even | |
426 | if there might be a newer version as indicated in the local copy of the index. | |
1a86f232 | 427 | See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going |
2d4aa38b | 428 | offline.</p> |
1a86f232 | 429 | <p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> |
2d4aa38b EH |
430 | |
431 | ||
432 | ||
433 | </dl> | |
434 | ||
435 | ### Common Options | |
436 | ||
437 | <dl> | |
438 | ||
439 | <dt class="option-term" id="option-cargo-test-+toolchain"><a class="option-anchor" href="#option-cargo-test-+toolchain"></a><code>+</code><em>toolchain</em></dt> | |
440 | <dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> | |
441 | begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such | |
442 | as <code>+stable</code> or <code>+nightly</code>). | |
fac70ee7 | 443 | See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> |
2d4aa38b EH |
444 | for more information about how toolchain overrides work.</dd> |
445 | ||
446 | ||
65332bc9 WL |
447 | <dt class="option-term" id="option-cargo-test---config"><a class="option-anchor" href="#option-cargo-test---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> |
448 | <dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, | |
449 | or provided as a path to an extra configuration file. This flag may be specified multiple times. | |
450 | See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> | |
7eefb422 JG |
451 | |
452 | ||
2d4aa38b EH |
453 | <dt class="option-term" id="option-cargo-test--h"><a class="option-anchor" href="#option-cargo-test--h"></a><code>-h</code></dt> |
454 | <dt class="option-term" id="option-cargo-test---help"><a class="option-anchor" href="#option-cargo-test---help"></a><code>--help</code></dt> | |
455 | <dd class="option-desc">Prints help information.</dd> | |
456 | ||
457 | ||
458 | <dt class="option-term" id="option-cargo-test--Z"><a class="option-anchor" href="#option-cargo-test--Z"></a><code>-Z</code> <em>flag</em></dt> | |
459 | <dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> | |
460 | ||
461 | ||
462 | </dl> | |
463 | ||
464 | ||
465 | ### Miscellaneous Options | |
466 | ||
467 | The `--jobs` argument affects the building of the test executable but does not | |
468 | affect how many threads are used when running the tests. The Rust test harness | |
469 | includes an option to control the number of threads used: | |
470 | ||
471 | cargo test -j 2 -- --test-threads=2 | |
472 | ||
473 | <dl> | |
474 | ||
475 | <dt class="option-term" id="option-cargo-test--j"><a class="option-anchor" href="#option-cargo-test--j"></a><code>-j</code> <em>N</em></dt> | |
476 | <dt class="option-term" id="option-cargo-test---jobs"><a class="option-anchor" href="#option-cargo-test---jobs"></a><code>--jobs</code> <em>N</em></dt> | |
477 | <dd class="option-desc">Number of parallel jobs to run. May also be specified with the | |
1a86f232 | 478 | <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to |
5b76fb3d YT |
479 | the number of logical CPUs. If negative, it sets the maximum number of |
480 | parallel jobs to the number of logical CPUs plus provided value. | |
481 | Should not be 0.</dd> | |
2d4aa38b EH |
482 | |
483 | ||
4e45f588 DT |
484 | <dt class="option-term" id="option-cargo-test---keep-going"><a class="option-anchor" href="#option-cargo-test---keep-going"></a><code>--keep-going</code></dt> |
485 | <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting | |
486 | the build on the first one that fails to build. Unstable, requires | |
487 | <code>-Zunstable-options</code>.</dd> | |
488 | ||
489 | ||
8c7c35ec AH |
490 | <dt class="option-term" id="option-cargo-test---future-incompat-report"><a class="option-anchor" href="#option-cargo-test---future-incompat-report"></a><code>--future-incompat-report</code></dt> |
491 | <dd class="option-desc">Displays a future-incompat report for any future-incompatible warnings | |
492 | produced during execution of this command</p> | |
493 | <p>See <a href="cargo-report.html">cargo-report(1)</a></dd> | |
494 | ||
495 | ||
2d4aa38b EH |
496 | |
497 | </dl> | |
498 | ||
2d4aa38b EH |
499 | ## ENVIRONMENT |
500 | ||
501 | See [the reference](../reference/environment-variables.html) for | |
502 | details on environment variables that Cargo reads. | |
503 | ||
504 | ||
505 | ## EXIT STATUS | |
506 | ||
507 | * `0`: Cargo succeeded. | |
508 | * `101`: Cargo failed to complete. | |
509 | ||
510 | ||
511 | ## EXAMPLES | |
512 | ||
513 | 1. Execute all the unit and integration tests of the current package: | |
514 | ||
515 | cargo test | |
516 | ||
517 | 2. Run only tests whose names match against a filter string: | |
518 | ||
519 | cargo test name_filter | |
520 | ||
521 | 3. Run only a specific test within a specific integration test: | |
522 | ||
523 | cargo test --test int_test_name -- modname::test_name | |
524 | ||
525 | ## SEE ALSO | |
4464aa43 | 526 | [cargo(1)](cargo.html), [cargo-bench(1)](cargo-bench.html), [types of tests](../reference/cargo-targets.html#tests), [how to write tests](https://doc.rust-lang.org/rustc/tests/index.html) |