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