src/tools/cargo/src/doc/man/cargo-test.adoc

= cargo-test(1)
:idprefix: cargo_test_
:doctype: manpage
:actionverb: Test
:nouns: tests

== NAME

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

== SYNOPSIS

`cargo test [_OPTIONS_] [TESTNAME] [-- _TEST-OPTIONS_]`

== DESCRIPTION

Compile and execute unit and integration 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`.  As an example, this will run all tests with
`foo` in their name on 3 threads in parallel:

    cargo test foo -- --test-threads 3

Tests are built with the `--test` option to `rustc` which creates an
executable with a `main` function that 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.

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 are also run by default, which is handled by `rustdoc`. It
extracts code samples from documentation comments and executes them. See the
link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on
writing doc tests.

== OPTIONS

=== Test Options

include::options-test.adoc[]

=== Package Selection

include::options-packages.adoc[]

=== Target Selection

When no target selection options are given, `cargo test` will build the
following targets of the selected packages:

- lib — used to link with binaries, examples, integration tests, and doc tests
- bins (only if integration tests are built and required features are
  available)
- examples — to ensure they compile
- lib as a unit test
- bins as unit tests
- integration tests
- 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.

include::options-targets.adoc[]

*--doc*::
    Test only the library's documentation. This cannot be mixed with other
    target options.

include::options-features.adoc[]

=== Compilation Options

include::options-target-triple.adoc[]

include::options-release.adoc[]

=== Output Options

include::options-target-dir.adoc[]

=== 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

include::options-display.adoc[]

include::options-message-format.adoc[]

=== Manifest Options

include::options-manifest-path.adoc[]

include::options-locked.adoc[]

=== Common Options

include::options-common.adoc[]

=== 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

include::options-jobs.adoc[]

include::section-profiles.adoc[]

Unit tests are separate executable artifacts which use the `test`/`bench`
profiles. Example targets are built the same as with `cargo build` (using the
`dev`/`release` profiles) unless you are building them with the test harness
(by setting `test = true` in the manifest or using the `--example` flag) in
which case they use the `test`/`bench` profiles. Library targets are built
with the `dev`/`release` profiles when linked to an integration test, binary,
or doctest.

include::section-environment.adoc[]

include::section-exit-status.adoc[]

== EXAMPLES

. Execute all the unit and integration tests of the current package:

    cargo test

. Run only a specific test within a specific integration test:

    cargo test --test int_test_name -- modname::test_name

== SEE ALSO
man:cargo[1], man:cargo-bench[1]