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