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