| 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. |
| |
| Working directory of tests |
| The working directory when running each unit and integration test is set |
| to the root directory of the package the test belongs to. Setting the |
| working directory of tests to the package’s root directory makes it |
| possible for tests to reliably access the package’s files using |
| relative paths, regardless from where cargo test was executed from. |
| |
| For documentation tests, the working directory when invoking rustdoc is |
| set to the workspace root directory, and is also the directory rustdoc |
| uses as the compilation directory of each documentation test. The |
| working directory when running each documentation test is set to the |
| root directory of the package the test belongs to, and is controlled via |
| rustdoc’s --test-run-directory option. |
| |
| 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, replacing the example’s main |
| function with the libtest harness. If you don’t want the main function |
| replaced, also include harness = false, in which case the example will |
| be built and executed as-is. |
| |
| Setting targets to test = false will stop them from being tested by |
| default. Target selection options that take a target by name (such as |
| --example foo) 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. |
| |
| See Configuring a target |
| <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target> |
| for more information on per-target settings. |
| |
| 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 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 must appear before the command name, for example cargo -C |
| path/to/my-project build. |
| |
| 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. |
| If a string default is provided, it sets the value back to defaults. |
| Should not be 0. |
| |
| --future-incompat-report |
| Displays a future-incompat report for any future-incompatible |
| warnings produced during execution of this command |
| |
| See cargo-report(1) |
| |
| While cargo test involves compilation, it does not provide a |
| --keep-going flag. Use --no-fail-fast to run as many tests as possible |
| without stopping at the first failure. To “compile” as many tests as |
| possible, use --tests to build test binaries separately. For example: |
| |
| cargo build --tests --keep-going |
| cargo test --tests --no-fail-fast |
| |
| 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> |
| |