doc/contrib/src/tests/running.md - cargo - Git at Google

 # 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 with `gitoxide` as default git backend in tests

 By default, the `git2` backend is used for most git operations. As tests need to explicitly
 opt-in to use nightly features and feature flags, adjusting all tests to run with nightly
 and `-Zgitoxide` is unfeasible.

 This is why the private environment variable named `__CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2` can be
 set while running tests to automatically enable the `-Zgitoxide` flag implicitly, allowing to
 test `gitoxide` for the entire cargo test suite.

 ## 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.
	# 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 with `gitoxide` as default git backend in tests

	By default, the `git2` backend is used for most git operations. As tests need to explicitly
	opt-in to use nightly features and feature flags, adjusting all tests to run with nightly
	and `-Zgitoxide` is unfeasible.

	This is why the private environment variable named `__CARGO_USE_GITOXIDE_INSTEAD_OF_GIT2` can be
	set while running tests to automatically enable the `-Zgitoxide` flag implicitly, allowing to
	test `gitoxide` for the entire cargo test suite.

	## 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.