Archiving and reusing builds
In some cases, it can be useful to separate out building tests from running them. Nextest supports archiving builds on one machine, and then extracting the archive to run tests on another machine.
Terms
- Build machine: The computer that builds tests.
- Target machine: The computer that runs tests.
Use cases
- Cross-compilation. The build machine has a different architecture, or runs a different operating system, from the target machine.
- Test partitioning. Build once on the build machine, then partition test execution across multiple target machines.
- Saving execution time on more valuable machines. For example, build tests on a regular machine, then run them on a machine with a GPU attached to it.
Requirements
- The project source must be checked out to the same revision on the target machine. This might be needed for test fixtures and other assets, and nextest sets the right working directory relative to the workspace root when executing tests.
- It is your responsibility to transfer over the archive. Use the examples below as a template.
- Nextest must be installed on the target machine. For best results, use the same version of nextest on both machines.
Non-requirements
- Cargo does not need to be installed on the target machine. If
cargo
is unavailable, replacecargo nextest
withcargo-nextest nextest
in the following examples.
Creating archives
cargo nextest archive --archive-file <name-of-archive.tar.zst>
creates an archive with the following contents:
- Cargo-related metadata, at the location
target/nextest/cargo-metadata.json
. - Metadata about test binaries, at the location
target/nextest/binaries-metadata.json
. - All test binaries
- Other relevant files:
- Dynamic libraries that test binaries might link to
- Non-test binaries used by integration tests
Note that archives do not include the source code for your project. It is your responsibility to ensure that the source code for your workspace is transferred over to the target machine and has the same contents.
Currently, the only format supported is a Zstandard-compressed tarball (.tar.zst
).
Running tests from archives
cargo nextest list
and run
support a new --archive-file
option. This option accepts archives created by cargo nextest archive
as above.
By default, archives are extracted to a temporary directory, and nextest remaps paths to use the new
target directory. To specify the directory archives should be extracted to, use the --extract-to
option.
Specifying a new location for the source code
By default, nextest expects the workspace's source code to be in the same location on both the build and target machines. To specify a new location for the workspace, use the --workspace-remap <path-to-workspace-root>
option with the list
or run
commands.
Example: Simple build/run split
- Build and archive tests:
cargo nextest archive --archive-file my-archive.tar.zst
- Run the tests:
cargo nextest run --archive-file my-archive.tar.zst
Example: Use in GitHub Actions
See this working example for how to reuse builds and partition test runs on GitHub Actions.
Example: Cross-compilation
While cross-compiling code, some tests may need to be run on the host platform. (See the note about Filtering by build platform for more.)
On the build machine
- Build and run host-only tests:
cargo nextest run --target <TARGET> -E 'platform(host)'
- Archive tests:
cargo nextest archive --target <TARGET> --archive-file my-archive.tar.zst
- Copy
my-archive.tar.zst
to the target machine.
On the target machine
- Check out the project repository to a path
<REPO-PATH>
, to the same revision as the build machine. - List target-only tests:
cargo nextest list -E 'platform(target)' \ --archive-file my-archive.tar.zst \ --workspace-remap <REPO-PATH>
- Run target-only tests:
cargo nextest run -E 'platform(target)' \ --archive-file my-archive.tar.zst \ --workspace-remap <REPO-PATH>
Manually creating your own archives
You can also create and manage your own archives, with the following options to cargo nextest list
and run
:
--binaries-metadata
: The path to JSON metadata generated bycargo nextest list --list-type binaries-only --message-format json
.--target-dir-remap
: A possible new location for the target directory. Requires--binaries-metadata
.--cargo-metadata
: The path to JSON metadata generated bycargo metadata --format-version 1
.
Making tests relocatable
Some tests may need to be modified to handle changes in the workspace and target directories. Some common situations:
-
To obtain the path to the source directory, Cargo provides the
CARGO_MANIFEST_DIR
option at both build time and runtime. For relocatable tests, use the value ofCARGO_MANIFEST_DIR
at runtime. This meansstd::env::var("CARGO_MANIFEST_DIR")
, notenv!("CARGO_MANIFEST_DIR")
.If the workspace is remapped, nextest automatically sets
CARGO_MANIFEST_DIR
to the new location. -
To obtain the path to a crate's executables, Cargo provides the
CARGO_BIN_EXE_<name>
option to integration tests at build time. To handle target directory remapping, use the value ofNEXTEST_BIN_EXE_<name>
at runtime.To retain compatibility with
cargo test
, you can fall back to the value ofCARGO_BIN_EXE_<name>
at build time.
Options and arguments for cargo nextest archive
Build and archive tests
Usage: cargo nextest archive [OPTIONS] --archive-file <PATH>
Options:
--manifest-path <PATH> Path to Cargo.toml
-v, --verbose Verbose output [env: NEXTEST_VERBOSE=]
--color <WHEN> Produce color output: auto, always, never [env: CARGO_TERM_COLOR=] [default: auto]
-h, --help Print help information (use `--help` for more detail)
Cargo options:
--lib Test only this package's library unit tests
--bin <BIN> Test only the specified binary
--bins Test all binaries
--example <EXAMPLE> Test only the specified example
--examples Test all examples
--test <TEST> Test only the specified test target
--tests Test all targets
--bench <BENCH> Test only the specified bench target
--benches Test all benches
--all-targets Test all targets
-p, --package <PACKAGES> Package to test
--workspace Build all packages in the workspace
--exclude <EXCLUDE> Exclude packages from the test
--all Alias for workspace (deprecated)
-r, --release Build artifacts in release mode, with optimizations
--cargo-profile <NAME> Build artifacts with the specified Cargo profile
--build-jobs <JOBS> Number of build jobs to run
-F, --features <FEATURES> Space or comma separated list of features to activate
--all-features Activate all available features
--no-default-features Do not activate the `default` feature
--target <TRIPLE> Build for the target triple
--target-dir <DIR> Directory for all generated artifacts
--ignore-rust-version Ignore `rust-version` specification in packages
--unit-graph Output build graph in JSON (unstable)
--future-incompat-report Outputs a future incompatibility report at the end of the build
--frozen Require Cargo.lock and cache are up to date
--locked Require Cargo.lock is up to date
--offline Run without accessing the network
--config <KEY=VALUE> Override a configuration value
-Z <FLAG> Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
Archive options:
--archive-file <PATH> File to write archive to
--archive-format <FORMAT> Archive format [default: auto] [possible values: auto, tar-zst]
--zstd-level <LEVEL> Zstandard compression level (-7 to 22, higher is more compressed + slower) [default: 0]
Config options:
--config-file <PATH>
Config file [default: workspace-root/.config/nextest.toml]
--tool-config-file <TOOL:ABS_PATH>
Tool-specific config files