Rust test sharding
Tuist distributes Cargo test targets across CI workers using historical target durations. Unit-test targets, integration-test targets, and each library's doctests are separate modules. Tests within one target stay together.
- Configure Rust Test Insights and authenticate the CLI on the planning job and workers.
- Select one package, using
-p <package>in a workspace. Multi-package sharding is not supported. - Use the same revision, Rust toolchain, package selection, features, and test filters in every job.
Create a plan#
Add a shard count to --no-run to compile and enumerate targets without executing tests:
TUIST_SHARD_REFERENCE=my-ci-run tuist cargo test -p store --no-run --shard-max 4
The command prints JSON containing shard_plan_id and a zero-based shards array. In GitHub Actions, it also writes shard-plan-id and shards to GITHUB_OUTPUT. Without an explicit reference, Tuist derives one from the supported CI environment.
| Option | Description |
|---|---|
--shard-max N | Maximum number of shards |
--shard-min N | Minimum number of shards |
--shard-total N | Exact count, up to the available targets |
--shard-max-duration N | Target maximum shard duration in milliseconds |
Use --shard-total alone or combine --shard-min and --shard-max. Without historical durations, the planner uses default target estimates. Ordinary --no-run without shard options remains a build-only command.
Execute each shard#
Set the plan ID and shard index on each worker, then use the same Cargo test arguments:
TUIST_SHARD_PLAN_ID=<plan-id> TUIST_SHARD_INDEX=0 tuist cargo test -p store
Alternatively, set TUIST_SHARD_REFERENCE to the planning job's reference instead of passing the plan ID. Tuist fetches the assignment and asks Cargo to execute only those targets. Invalid or incompatible assignments fail the command rather than running all tests. Empty assignments execute no tests. Results from the workers are linked to the plan in Test Insights, and quarantine applies within each shard.
Limits#
This is target-level sharding, not build-once distribution. Each worker needs the source checkout and builds its own targets; the Cargo compilation cache can reuse eligible compilation outputs. Tuist does not upload test executables or require another Rust test runner.
Sharding requires one selected package. Narrowing a multi-package command can change Cargo's unified dependency features, so Tuist rejects it instead of running tests with a different feature graph. Plan each package separately until multi-package sharding is supported.
Sharding requires standard libtest harnesses and captured default output. Quiet, verbose, alternate-format, uncaptured-output, and custom-harness commands are rejected. If Cargo cannot uniquely identify a target, select an exact workspace package with -p <package>. Dependency packages, version-qualified selectors, package/target-name globs, and Cargo's nightly -C option are unsupported for sharding. Keep test selection identical between planning and execution.