cargo-test(1)

1CARGO-TEST(1)               General Commands Manual              CARGO-TEST(1)
2
3
4

NAME

6       cargo-test - Execute unit and integration tests of a package
7

SYNOPSIS

9       cargo test [options] [testname] [-- test-options]
10

DESCRIPTION

12       Compile and execute unit and integration tests.
13
14       The test filtering argument TESTNAME and all the arguments following
15       the two dashes (--) are passed to the test binaries and thus to libtest
16       (rustc's built in unit-test and micro-benchmarking framework). If
17       you're passing arguments to both Cargo and the binary, the ones after
18       -- go to the binary, the ones before go to Cargo. For details about
19       libtest's arguments see the output of cargo test -- --help and check
20       out the rustc book's chapter on how tests work at
21       <https://doc.rust-lang.org/rustc/tests/index.html>.
22
23       As an example, this will filter for tests with foo in their name and
24       run them on 3 threads in parallel:
25
26           cargo test foo -- --test-threads 3
27
28       Tests are built with the --test option to rustc which creates an
29       executable with a main function that automatically runs all functions
30       annotated with the #[test] attribute in multiple threads. #[bench]
31       annotated functions will also be run with one iteration to verify that
32       they are functional.
33
34       The libtest harness may be disabled by setting harness = false in the
35       target manifest settings, in which case your code will need to provide
36       its own main function to handle running tests.
37
38       Documentation tests are also run by default, which is handled by
39       rustdoc. It extracts code samples from documentation comments and
40       executes them. See the rustdoc book
41       <https://doc.rust-lang.org/rustdoc/> for more information on writing
42       doc tests.
43

OPTIONS

45   Test Options
46       --no-run
47           Compile, but don't run tests.
48
49       --no-fail-fast
50           Run all tests regardless of failure. Without this flag, Cargo will
51           exit after the first executable fails. The Rust test harness will
52           run all tests within the executable to completion, this flag only
53           applies to the executable as a whole.
54
55   Package Selection
56       By default, when no package selection options are given, the packages
57       selected depend on the selected manifest file (based on the current
58       working directory if --manifest-path is not given). If the manifest is
59       the root of a workspace then the workspaces default members are
60       selected, otherwise only the package defined by the manifest will be
61       selected.
62
63       The default members of a workspace can be set explicitly with the
64       workspace.default-members key in the root manifest. If this is not set,
65       a virtual workspace will include all workspace members (equivalent to
66       passing --workspace), and a non-virtual workspace will include only the
67       root crate itself.
68
69       -p spec..., --package spec...
70           Test only the specified packages. See cargo-pkgid(1) for the SPEC
71           format. This flag may be specified multiple times and supports
72           common Unix glob patterns like *, ? and []. However, to avoid your
73           shell accidentally expanding glob patterns before Cargo handles
74           them, you must use single quotes or double quotes around each
75           pattern.
76
77       --workspace
78           Test all members in the workspace.
79
80       --all
81           Deprecated alias for --workspace.
82
83       --exclude SPEC...
84           Exclude the specified packages. Must be used in conjunction with
85           the --workspace flag. This flag may be specified multiple times and
86           supports common Unix glob patterns like *, ? and []. However, to
87           avoid your shell accidentally expanding glob patterns before Cargo
88           handles them, you must use single quotes or double quotes around
89           each pattern.
90
91   Target Selection
92       When no target selection options are given, cargo test will build the
93       following targets of the selected packages:
94
95       •  lib — used to link with binaries, examples, integration tests, and
96           doc tests
97
98       •  bins (only if integration tests are built and required features are
99           available)
100
101       •  examples — to ensure they compile
102
103       •  lib as a unit test
104
105       •  bins as unit tests
106
107       •  integration tests
108
109       •  doc tests for the lib target
110
111       The default behavior can be changed by setting the test flag for the
112       target in the manifest settings. Setting examples to test = true will
113       build and run the example as a test. Setting targets to test = false
114       will stop them from being tested by default. Target selection options
115       that take a target by name ignore the test flag and will always test
116       the given target.
117
118       Doc tests for libraries may be disabled by setting doctest = false for
119       the library in the manifest.
120
121       Binary targets are automatically built if there is an integration test
122       or benchmark. This allows an integration test to execute the binary to
123       exercise and test its behavior. The CARGO_BIN_EXE_<name> environment
124       variable
125       <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates>
126       is set when the integration test is built so that it can use the env
127       macro <https://doc.rust-lang.org/std/macro.env.html> to locate the
128       executable.
129
130       Passing target selection flags will test only the specified targets.
131
132       Note that --bin, --example, --test and --bench flags also support
133       common Unix glob patterns like *, ? and []. However, to avoid your
134       shell accidentally expanding glob patterns before Cargo handles them,
135       you must use single quotes or double quotes around each glob pattern.
136
137       --lib
138           Test the package's library.
139
140       --bin name...
141           Test the specified binary. This flag may be specified multiple
142           times and supports common Unix glob patterns.
143
144       --bins
145           Test all binary targets.
146
147       --example name...
148           Test the specified example. This flag may be specified multiple
149           times and supports common Unix glob patterns.
150
151       --examples
152           Test all example targets.
153
154       --test name...
155           Test the specified integration test. This flag may be specified
156           multiple times and supports common Unix glob patterns.
157
158       --tests
159           Test all targets in test mode that have the test = true manifest
160           flag set. By default this includes the library and binaries built
161           as unittests, and integration tests. Be aware that this will also
162           build any required dependencies, so the lib target may be built
163           twice (once as a unittest, and once as a dependency for binaries,
164           integration tests, etc.). Targets may be enabled or disabled by
165           setting the test flag in the manifest settings for the target.
166
167       --bench name...
168           Test the specified benchmark. This flag may be specified multiple
169           times and supports common Unix glob patterns.
170
171       --benches
172           Test all targets in benchmark mode that have the bench = true
173           manifest flag set. By default this includes the library and
174           binaries built as benchmarks, and bench targets. Be aware that this
175           will also build any required dependencies, so the lib target may be
176           built twice (once as a benchmark, and once as a dependency for
177           binaries, benchmarks, etc.). Targets may be enabled or disabled by
178           setting the bench flag in the manifest settings for the target.
179
180       --all-targets
181           Test all targets. This is equivalent to specifying --lib --bins
182           --tests --benches --examples.
183
184       --doc
185           Test only the library's documentation. This cannot be mixed with
186           other target options.
187
188   Feature Selection
189       The feature flags allow you to control which features are enabled. When
190       no feature options are given, the default feature is activated for
191       every selected package.
192
193       See the features documentation
194       <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
195       for more details.
196
197       -F features, --features features
198           Space or comma separated list of features to activate. Features of
199           workspace members may be enabled with package-name/feature-name
200           syntax. This flag may be specified multiple times, which enables
201           all specified features.
202
203       --all-features
204           Activate all available features of all selected packages.
205
206       --no-default-features
207           Do not activate the default feature of the selected packages.
208
209   Compilation Options
210       --target triple
211           Test for the given architecture. The default is the host
212           architecture. The general format of the triple is
213           <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
214           a list of supported targets.
215
216           This may also be specified with the build.target config value
217           <https://doc.rust-lang.org/cargo/reference/config.html>.
218
219           Note that specifying this flag makes Cargo run in a different mode
220           where the target artifacts are placed in a separate directory. See
221           the build cache
222           <https://doc.rust-lang.org/cargo/guide/build-cache.html>
223           documentation for more details.
224
225       -r, --release
226           Test optimized artifacts with the release profile. See also the
227           --profile option for choosing a specific profile by name.
228
229       --profile name
230           Test with the given profile. See the the reference
231           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
232           details on profiles.
233
234       --ignore-rust-version
235           Test the target even if the selected Rust compiler is older than
236           the required Rust version as configured in the project's
237           rust-version field.
238
239       --timings=fmts
240           Output information how long each compilation takes, and track
241           concurrency information over time. Accepts an optional
242           comma-separated list of output formats; --timings without an
243           argument will default to --timings=html. Specifying an output
244           format (rather than the default) is unstable and requires
245           -Zunstable-options. Valid output formats:
246
247           •  html: Write a human-readable file cargo-timing.html to the
248               target/cargo-timings directory with a report of the
249               compilation. Also write a report to the same directory with a
250               timestamp in the filename if you want to look at older runs.
251               HTML output is suitable for human consumption only, and does
252               not provide machine-readable timing data.
253
254           •  json (unstable, requires -Zunstable-options): Emit
255               machine-readable JSON information about timing information.
256
257   Output Options
258       --target-dir directory
259           Directory for all generated artifacts and intermediate files. May
260           also be specified with the CARGO_TARGET_DIR environment variable,
261           or the build.target-dir config value
262           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
263           to target in the root of the workspace.
264
265   Display Options
266       By default the Rust test harness hides output from test execution to
267       keep results readable. Test output can be recovered (e.g., for
268       debugging) by passing --nocapture to the test binaries:
269
270           cargo test -- --nocapture
271
272       -v, --verbose
273           Use verbose output. May be specified twice for "very verbose"
274           output which includes extra output such as dependency warnings and
275           build script output. May also be specified with the term.verbose
276           config value
277           <https://doc.rust-lang.org/cargo/reference/config.html>.
278
279       -q, --quiet
280           Do not print cargo log messages. May also be specified with the
281           term.quiet config value
282           <https://doc.rust-lang.org/cargo/reference/config.html>.
283
284       --color when
285           Control when colored output is used. Valid values:
286
287           •  auto (default): Automatically detect if color support is
288               available on the terminal.
289
290           •  always: Always display colors.
291
292           •  never: Never display colors.
293
294           May also be specified with the term.color config value
295           <https://doc.rust-lang.org/cargo/reference/config.html>.
296
297       --message-format fmt
298           The output format for diagnostic messages. Can be specified
299           multiple times and consists of comma-separated values. Valid
300           values:
301
302           •  human (default): Display in a human-readable text format.
303               Conflicts with short and json.
304
305           •  short: Emit shorter, human-readable text messages. Conflicts
306               with human and json.
307
308           •  json: Emit JSON messages to stdout. See the reference
309               <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
310               for more details. Conflicts with human and short.
311
312           •  json-diagnostic-short: Ensure the rendered field of JSON
313               messages contains the "short" rendering from rustc. Cannot be
314               used with human or short.
315
316           •  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
317               messages contains embedded ANSI color codes for respecting
318               rustc's default color scheme. Cannot be used with human or
319               short.
320
321           •  json-render-diagnostics: Instruct Cargo to not include rustc
322               diagnostics in in JSON messages printed, but instead Cargo
323               itself should render the JSON diagnostics coming from rustc.
324               Cargo's own JSON diagnostics and others coming from rustc are
325               still emitted. Cannot be used with human or short.
326
327   Manifest Options
328       --manifest-path path
329           Path to the Cargo.toml file. By default, Cargo searches for the
330           Cargo.toml file in the current directory or any parent directory.
331
332       --frozen, --locked
333           Either of these flags requires that the Cargo.lock file is
334           up-to-date. If the lock file is missing, or it needs to be updated,
335           Cargo will exit with an error. The --frozen flag also prevents
336           Cargo from attempting to access the network to determine if it is
337           out-of-date.
338
339           These may be used in environments where you want to assert that the
340           Cargo.lock file is up-to-date (such as a CI build) or want to avoid
341           network access.
342
343       --offline
344           Prevents Cargo from accessing the network for any reason. Without
345           this flag, Cargo will stop with an error if it needs to access the
346           network and the network is not available. With this flag, Cargo
347           will attempt to proceed without the network if possible.
348
349           Beware that this may result in different dependency resolution than
350           online mode. Cargo will restrict itself to crates that are
351           downloaded locally, even if there might be a newer version as
352           indicated in the local copy of the index. See the cargo-fetch(1)
353           command to download dependencies before going offline.
354
355           May also be specified with the net.offline config value
356           <https://doc.rust-lang.org/cargo/reference/config.html>.
357
358   Common Options
359       +toolchain
360           If Cargo has been installed with rustup, and the first argument to
361           cargo begins with +, it will be interpreted as a rustup toolchain
362           name (such as +stable or +nightly). See the rustup documentation
363           <https://rust-lang.github.io/rustup/overrides.html> for more
364           information about how toolchain overrides work.
365
366       -h, --help
367           Prints help information.
368
369       -Z flag
370           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
371           details.
372
373   Miscellaneous Options
374       The --jobs argument affects the building of the test executable but
375       does not affect how many threads are used when running the tests. The
376       Rust test harness includes an option to control the number of threads
377       used:
378
379           cargo test -j 2 -- --test-threads=2
380
381       -j N, --jobs N
382           Number of parallel jobs to run. May also be specified with the
383           build.jobs config value
384           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
385           to the number of CPUs.
386
387       --keep-going
388           Build as many crates in the dependency graph as possible, rather
389           than aborting the build on the first one that fails to build.
390           Unstable, requires -Zunstable-options.
391
392       --future-incompat-report
393           Displays a future-incompat report for any future-incompatible
394           warnings produced during execution of this command
395
396           See cargo-report(1)
397

ENVIRONMENT

399       See the reference
400       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
401       for details on environment variables that Cargo reads.
402

EXIT STATUS

404       •  0: Cargo succeeded.
405
406       •  101: Cargo failed to complete.
407

EXAMPLES

409        1. Execute all the unit and integration tests of the current package:
410
411               cargo test
412
413        2. Run only tests whose names match against a filter string:
414
415               cargo test name_filter
416
417        3. Run only a specific test within a specific integration test:
418
419               cargo test --test int_test_name -- modname::test_name
420