fork/cargo
git clone https://git.julia.blue/fork/cargo
f2932725b
master
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 specified target architecture. Flag may be specified 246 multiple times. The default is the host architecture. The general 247 format of the triple is <arch><sub>-<vendor>-<sys>-<abi>. 248 249 Possible values: 250 251 o Any supported target in rustc --print target-list. 252 253 o "host-tuple", which will internally be substituted by the 254 host’s target. This can be particularly useful if you’re 255 cross-compiling some crates, and don’t want to specify your 256 host’s machine as a target (for instance, an xtask in a shared 257 project that may be worked on by many hosts). 258 259 o A path to a custom target specification. See Custom Target Lookup 260 Path 261 <https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path> 262 for more information. 263 264 This may also be specified with the build.target config value 265 <https://doc.rust-lang.org/cargo/reference/config.html>. 266 267 Note that specifying this flag makes Cargo run in a different mode 268 where the target artifacts are placed in a separate directory. See 269 the build cache 270 <https://doc.rust-lang.org/cargo/reference/build-cache.html> 271 documentation for more details. 272 273 -r, --release 274 Test optimized artifacts with the release profile. See also the 275 --profile option for choosing a specific profile by name. 276 277 --profile name 278 Test with the given profile. See the reference 279 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more 280 details on profiles. 281 282 --timings=fmts 283 Output information how long each compilation takes, and track 284 concurrency information over time. Accepts an optional 285 comma-separated list of output formats; --timings without an 286 argument will default to --timings=html. Specifying an output format 287 (rather than the default) is unstable and requires 288 -Zunstable-options. Valid output formats: 289 290 o html (unstable, requires -Zunstable-options): Write a 291 human-readable file cargo-timing.html to the target/cargo-timings 292 directory with a report of the compilation. Also write a report 293 to the same directory with a timestamp in the filename if you 294 want to look at older runs. HTML output is suitable for human 295 consumption only, and does not provide machine-readable timing 296 data. 297 298 o json (unstable, requires -Zunstable-options): Emit 299 machine-readable JSON information about timing information. 300 301 Output Options 302 --target-dir directory 303 Directory for all generated artifacts and intermediate files. May 304 also be specified with the CARGO_TARGET_DIR environment variable, or 305 the build.target-dir config value 306 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 307 target in the root of the workspace. 308 309 Display Options 310 By default the Rust test harness hides output from test execution to 311 keep results readable. Test output can be recovered (e.g., for 312 debugging) by passing --no-capture to the test binaries: 313 314 cargo test -- --no-capture 315 316 -v, --verbose 317 Use verbose output. May be specified twice for “very verbose” 318 output which includes extra output such as dependency warnings and 319 build script output. May also be specified with the term.verbose 320 config value 321 <https://doc.rust-lang.org/cargo/reference/config.html>. 322 323 -q, --quiet 324 Do not print cargo log messages. May also be specified with the 325 term.quiet config value 326 <https://doc.rust-lang.org/cargo/reference/config.html>. 327 328 --color when 329 Control when colored output is used. Valid values: 330 331 o auto (default): Automatically detect if color support is 332 available on the terminal. 333 334 o always: Always display colors. 335 336 o never: Never display colors. 337 338 May also be specified with the term.color config value 339 <https://doc.rust-lang.org/cargo/reference/config.html>. 340 341 --message-format fmt 342 The output format for diagnostic messages. Can be specified multiple 343 times and consists of comma-separated values. Valid values: 344 345 o human (default): Display in a human-readable text format. 346 Conflicts with short and json. 347 348 o short: Emit shorter, human-readable text messages. Conflicts with 349 human and json. 350 351 o json: Emit JSON messages to stdout. See the reference 352 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> 353 for more details. Conflicts with human and short. 354 355 o json-diagnostic-short: Ensure the rendered field of JSON messages 356 contains the “short” rendering from rustc. Cannot be used 357 with human or short. 358 359 o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON 360 messages contains embedded ANSI color codes for respecting 361 rustc’s default color scheme. Cannot be used with human or 362 short. 363 364 o json-render-diagnostics: Instruct Cargo to not include rustc 365 diagnostics in JSON messages printed, but instead Cargo itself 366 should render the JSON diagnostics coming from rustc. Cargo’s 367 own JSON diagnostics and others coming from rustc are still 368 emitted. Cannot be used with human or short. 369 370 Manifest Options 371 --manifest-path path 372 Path to the Cargo.toml file. By default, Cargo searches for the 373 Cargo.toml file in the current directory or any parent directory. 374 375 --ignore-rust-version 376 Ignore rust-version specification in packages. 377 378 --locked 379 Asserts that the exact same dependencies and versions are used as 380 when the existing Cargo.lock file was originally generated. Cargo 381 will exit with an error when either of the following scenarios 382 arises: 383 384 o The lock file is missing. 385 386 o Cargo attempted to change the lock file due to a different 387 dependency resolution. 388 389 It may be used in environments where deterministic builds are 390 desired, such as in CI pipelines. 391 392 --offline 393 Prevents Cargo from accessing the network for any reason. Without 394 this flag, Cargo will stop with an error if it needs to access the 395 network and the network is not available. With this flag, Cargo will 396 attempt to proceed without the network if possible. 397 398 Beware that this may result in different dependency resolution than 399 online mode. Cargo will restrict itself to crates that are 400 downloaded locally, even if there might be a newer version as 401 indicated in the local copy of the index. See the cargo-fetch(1) 402 command to download dependencies before going offline. 403 404 May also be specified with the net.offline config value 405 <https://doc.rust-lang.org/cargo/reference/config.html>. 406 407 --frozen 408 Equivalent to specifying both --locked and --offline. 409 410 --lockfile-path PATH 411 Changes the path of the lockfile from the default 412 (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock 413 (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that 414 providing --lockfile-path will ignore existing lockfile at the 415 default path, and instead will either use the lockfile from PATH, or 416 write a new lockfile into the provided PATH if it doesn’t exist. 417 This flag can be used to run most commands in read-only directories, 418 writing lockfile into the provided PATH. 419 420 This option is only available on the nightly channel 421 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and 422 requires the -Z unstable-options flag to enable (see #14421 423 <https://github.com/rust-lang/cargo/issues/14421>). 424 425 Common Options 426 +toolchain 427 If Cargo has been installed with rustup, and the first argument to 428 cargo begins with +, it will be interpreted as a rustup toolchain 429 name (such as +stable or +nightly). See the rustup documentation 430 <https://rust-lang.github.io/rustup/overrides.html> for more 431 information about how toolchain overrides work. 432 433 --config KEY=VALUE or PATH 434 Overrides a Cargo configuration value. The argument should be in 435 TOML syntax of KEY=VALUE, or provided as a path to an extra 436 configuration file. This flag may be specified multiple times. See 437 the command-line overrides section 438 <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> 439 for more information. 440 441 -C PATH 442 Changes the current working directory before executing any specified 443 operations. This affects things like where cargo looks by default 444 for the project manifest (Cargo.toml), as well as the directories 445 searched for discovering .cargo/config.toml, for example. This 446 option must appear before the command name, for example cargo -C 447 path/to/my-project build. 448 449 This option is only available on the nightly channel 450 <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and 451 requires the -Z unstable-options flag to enable (see #10098 452 <https://github.com/rust-lang/cargo/issues/10098>). 453 454 -h, --help 455 Prints help information. 456 457 -Z flag 458 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for 459 details. 460 461 Miscellaneous Options 462 The --jobs argument affects the building of the test executable but does 463 not affect how many threads are used when running the tests. The Rust 464 test harness includes an option to control the number of threads used: 465 466 cargo test -j 2 -- --test-threads=2 467 468 -j N, --jobs N 469 Number of parallel jobs to run. May also be specified with the 470 build.jobs config value 471 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to 472 the number of logical CPUs. If negative, it sets the maximum number 473 of parallel jobs to the number of logical CPUs plus provided value. 474 If a string default is provided, it sets the value back to defaults. 475 Should not be 0. 476 477 --future-incompat-report 478 Displays a future-incompat report for any future-incompatible 479 warnings produced during execution of this command 480 481 See cargo-report(1) 482 483 While cargo test involves compilation, it does not provide a 484 --keep-going flag. Use --no-fail-fast to run as many tests as possible 485 without stopping at the first failure. To “compile” as many tests as 486 possible, use --tests to build test binaries separately. For example: 487 488 cargo build --tests --keep-going 489 cargo test --tests --no-fail-fast 490 491ENVIRONMENT 492 See the reference 493 <https://doc.rust-lang.org/cargo/reference/environment-variables.html> 494 for details on environment variables that Cargo reads. 495 496EXIT STATUS 497 o 0: Cargo succeeded. 498 499 o 101: Cargo failed to complete. 500 501EXAMPLES 502 1. Execute all the unit and integration tests of the current package: 503 504 cargo test 505 506 2. Run only tests whose names match against a filter string: 507 508 cargo test name_filter 509 510 3. Run only a specific test within a specific integration test: 511 512 cargo test --test int_test_name -- modname::test_name 513 514SEE ALSO 515 cargo(1), cargo-bench(1), types of tests 516 <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests>, 517 how to write tests <https://doc.rust-lang.org/rustc/tests/index.html> 518