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.