Compiles the project for testing, splits its tests into shards, and uploads the build so every shard can test without compiling again.

mix tuist.test.build --shard-max 4 [ARGS...]

Run it once per pipeline, on one machine. Then run mix tuist.test (or mix test, if you aliased it) on each shard with TUIST_SHARD_INDEX set: it downloads the build, runs only that shard's tests, and reports them as part of one test run.

Tuist balances the shards with how long each test module took in earlier runs. Modules it has not seen yet get an estimate. Modules that use a case with async: true run alongside each other and the others one at a time, and the shards are balanced by that, with how many ran at once in earlier shards.

Options

• --shard-max N - the most shards to split into (default 2)
• --shard-min N - the fewest shards to split into
• --shard-total N - an exact number of shards, instead of a range
• --shard-max-duration MS - the longest a shard should take, in milliseconds; Tuist picks the number of shards to fit
• --shard-reference REF - the name the shards find the plan by. Derived from the pipeline run on GitHub Actions, GitLab, CircleCI and Buildkite; set it, or TUIST_SHARD_REFERENCE, anywhere else
• --no-upload - plan the shards without uploading the build; each shard then compiles for itself
• --cover - instrument the build for native coverage once, so shards running mix tuist.test --cover don't each do it; see "Coverage" below
• --url, --project - as in mix tuist.test

Every other argument is forwarded to mix compile.

What the shards need

The same checkout, the same Elixir and Erlang versions, and mix deps.get. The uploaded build is the _build/test directory; dependency sources stay in deps/.

Coverage

mix tuist.test --cover counts lines with the runtime's native line counters, recompiling the modules with them when they don't carry them yet. With --cover, the project's modules and consolidated protocols are recompiled once, here, so the shards don't each do it.

Output

On GitHub Actions the shard indexes are written to GITHUB_OUTPUT as matrix={"shard":[0,1,...]}, ready for a job matrix. Elsewhere the plan is written to .tuist-shard-matrix.json.