diff options
Diffstat (limited to 'src/doc/man/generated_txt/cargo-test.txt')
| -rw-r--r-- | src/doc/man/generated_txt/cargo-test.txt | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt new file mode 100644 index 0000000..082447d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -0,0 +1,457 @@ +CARGO-TEST(1) + +NAME + cargo-test — Execute unit and integration tests of a package + +SYNOPSIS + cargo test [options] [testname] [-- test-options] + +DESCRIPTION + Compile and execute unit, integration, and documentation tests. + + The test filtering argument TESTNAME and all the arguments following the + two dashes (--) are passed to the test binaries and thus to libtest + (rustc’s built in unit-test and micro-benchmarking framework). If + you’re passing arguments to both Cargo and the binary, the ones after + -- go to the binary, the ones before go to Cargo. For details about + libtest’s arguments see the output of cargo test -- --help and check + out the rustc book’s chapter on how tests work at + <https://doc.rust-lang.org/rustc/tests/index.html>. + + As an example, this will filter for tests with foo in their name and run + them on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + + Tests are built with the --test option to rustc which creates a special + executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[test] attribute in + multiple threads. #[bench] annotated functions will also be run with one + iteration to verify that they are functional. + + If the package contains multiple test targets, each target compiles to a + special executable as aforementioned, and then is run serially. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running tests. + + Documentation tests + Documentation tests are also run by default, which is handled by + rustdoc. It extracts code samples from documentation comments of the + library target, and then executes them. + + Different from normal test targets, each code block compiles to a + doctest executable on the fly with rustc. These executables run in + parallel in separate processes. The compilation of a code block is in + fact a part of test function controlled by libtest, so some options such + as --jobs might not take effect. Note that this execution model of + doctests is not guaranteed and may change in the future; beware of + depending on it. + + See the rustdoc book <https://doc.rust-lang.org/rustdoc/> for more + information on writing doc tests. + +OPTIONS + Test Options + --no-run + Compile, but don’t run tests. + + --no-fail-fast + Run all tests regardless of failure. Without this flag, Cargo will + exit after the first executable fails. The Rust test harness will + run all tests within the executable to completion, this flag only + applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Test only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Test all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo test will build the + following targets of the selected packages: + + o lib — used to link with binaries, examples, integration tests, and + doc tests + + o bins (only if integration tests are built and required features are + available) + + o examples — to ensure they compile + + o lib as a unit test + + o bins as unit tests + + o integration tests + + o doc tests for the lib target + + The default behavior can be changed by setting the test flag for the + target in the manifest settings. Setting examples to test = true will + build and run the example as a test. Setting targets to test = false + will stop them from being tested by default. Target selection options + that take a target by name ignore the test flag and will always test the + given target. + + Doc tests for libraries may be disabled by setting doctest = false for + the library in the manifest. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to test. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will test only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Test the package’s library. + + --bin name… + Test the specified binary. This flag may be specified multiple times + and supports common Unix glob patterns. + + --bins + Test all binary targets. + + --example name… + Test the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Test all example targets. + + --test name… + Test the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Test all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Test the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Test all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Test all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + --doc + Test only the library’s documentation. This cannot be mixed with + other target options. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Test for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Test optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Test with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Test the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + By default the Rust test harness hides output from test execution to + keep results readable. Test output can be recovered (e.g., for + debugging) by passing --nocapture to the test binaries: + + cargo test -- --nocapture + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo’s + own JSON diagnostics and others coming from rustc are still + emitted. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + The --jobs argument affects the building of the test executable but does + not affect how many threads are used when running the tests. The Rust + test harness includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Execute all the unit and integration tests of the current package: + + cargo test + + 2. Run only tests whose names match against a filter string: + + cargo test name_filter + + 3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +SEE ALSO + cargo(1), cargo-bench(1), types of tests + <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests>, + how to write tests <https://doc.rust-lang.org/rustc/tests/index.html> + |