# `mix tuist.test.build`

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

# `run`

---

*Consult [api-reference.md](api-reference.md) for complete listing*