cargo/src/doc/contrib/src/tests/running.md

# Running Tests

Using `cargo test` is usually sufficient for running the full test suite. This
can take a few minutes, so you may want to use more targeted flags to pick the
specific test you want to run, such as `cargo test --test testsuite
-- check::check_success`.

## Running nightly tests

Some tests only run on the nightly toolchain, and will be ignored on other
channels. It is recommended that you run tests with both nightly and stable to
ensure everything is working as expected.

Some of the nightly tests require the `rustc-dev` and `llvm-tools-preview`
rustup components installed. These components include the compiler as a
library. This may already be installed with your nightly toolchain, but if it
isn't, run `rustup component add rustc-dev llvm-tools-preview
--toolchain=nightly`.

## Running cross tests

Some tests exercise cross compiling to a different target. This will require
you to install the appropriate target. This typically is the 32-bit target of
your host platform. For example, if your host is a 64-bit
`x86_64-unknown-linux-gnu`, then you should install the 32-bit target with
`rustup target add i686-unknown-linux-gnu`. If you don't have the alternate
target installed, there should be an error message telling you what to do. You
may also need to install additional tools for the target. For example, on Ubuntu
you should install the `gcc-multilib` package.

If you can't install an alternate target, you can set the
`CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests. The
Windows cross tests only support the MSVC toolchain.

## Running build-std tests

The `build-std` tests are disabled by default, but you can run them by setting
the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test
--test build-std`. This requires the nightly channel, and also requires the
`rust-src` component installed with `rustup component add rust-src
--toolchain=nightly`.

## Running public network tests

Some (very rare) tests involve connecting to the public internet.
These tests are disabled by default,
but you can run them by setting the `CARGO_PUBLIC_NETWORK_TESTS=1` environment variable.
Additionally our CI suite has a smoke test for fetching dependencies.
For most contributors, you will never need to bother with this.

## Running container tests

Tests marked with `container_test` involve running Docker to test more complex configurations.
These tests are disabled by default,
but you can run them by setting the `CARGO_CONTAINER_TESTS=1` environment variable.
You will need to have Docker installed and running to use these.

> Note: Container tests mostly do not work on Windows.
> * The SSH tests require ssh-agent, but the two versions of ssh-agent
> on Windows are not suitable for testing.
>     * The Microsoft version of ssh-agent runs as a global service, and can't be isolated per test.
>     * The mingw/cygwin one can't be accessed from a Windows executable like cargo.
>     * Pageant similarly does not seem to have a way to isolate it (and I'm not certain it can be driven completely from the command-line).
>
> The tests also can't run on Windows CI because the Docker that is preinstalled doesn't support Linux containers, and setting up Windows containers is a pain.
>
> macOS should work with Docker installed and running,
> but unfortunately the tests are not run on CI because Docker is not available.