# `mix tuist.test`

Runs `mix test` with the Tuist analytics ExUnit formatter installed, then
submits the test run to your Tuist dashboard.

    mix tuist.test [--url URL] [--project ACCOUNT/PROJECT] [--retries N] [--no-quarantine] [ARGS...]

Every other argument is forwarded to `mix test` as is, so the task can stand
in for it. Alias it in your `mix.exs` and `mix test` reports to Tuist without
anyone having to remember a different command:

    def project do
      [aliases: [test: "tuist.test"]]
    end

The project handle is read from, in order:

  * `TUIST_PROJECT` (env)
  * `--project account/project`
  * `Mix.Project.config()[:tuist][:project]`

Authentication reuses the credentials `mix tuist.login` stored, or the
`TUIST_TOKEN` environment variable if set. A submission failure never
changes the exit code of `mix test`.

## Running one shard

After `mix tuist.test.build` planned the shards, set `TUIST_SHARD_INDEX` (or
pass `--shard-index`) on each machine. The task then runs only that shard's
tests, using the uploaded build instead of compiling when there is one, and
reports them as part of a single test run.

Use `--prepare-only` to download a shard's build without starting the
application or running tests. This lets database setup run in a separate
process. Then use `--no-download` to run the shard against that prepared
build. Both options require a shard index. `--no-download` explicitly opts
out of the project's test preparation alias: run that preparation separately
with compilation disabled. Ordinary runs, including a shard that downloads
and runs in one command, preserve the project's alias behavior.

On a shard that uses Mix's coverage tool (see "Coverage"), the tool exports
the coverage (`--export-coverage shard-<index>`, unless one is given)
instead of holding the shard to the project's threshold.

`--scheme LABEL` names an execution variant in analytics, such as a database
version. Variants with different labels are not compared as flaky reruns.

## Coverage

With `--cover`, the run's line coverage is reported with it. The task
compiles the project, recompiles the modules a compile wrote since the last
run with the runtime's native line counters (a build
`mix tuist.test.build --cover` made needs none), switches the counters on
and counts with them. Mix's coverage tool, which would compile every module
for `cover` again, is left out, also for the modules Mimic copies. Its
summary and threshold are kept: the task prints each
module's coverage once the suite finishes and fails the run (exit status 3)
below `test_coverage: [summary: [threshold: N]]`, 90 unless set
(`summary: false` turns both off). A shard is never held to the threshold.
No HTML report is written, and setting `:output` warns. An umbrella's root, a project
that sets its own `test_coverage` tool, such as excoveralls, and a runtime
without the JIT, which cannot count natively, use Mix's coverage tool.

## Quarantined tests

Before the run, the task reads the tests the project quarantines in Tuist.
Skipped tests are left out of the run with an `--exclude test:NAME` filter
per test, and a complete run whose only failures are muted tests passes.
`--no-quarantine` runs every test and counts every failure. A run that
cannot read the quarantined tests runs every test.

## Retrying failed tests

ExUnit runs every test once, so a test that fails intermittently looks the
same as one that is broken. With retries enabled, the tests that failed are
run again with `mix test --failed`, up to the given number of times. A test
that passes on a retry is reported to Tuist as flaky, and the task succeeds
if every failed test eventually passes. A run whose failed tests all timed
out is not retried.

Retries are off unless set, in order, by:

  * `--retries N`
  * `TUIST_TEST_RETRIES` (env)
  * `Mix.Project.config()[:tuist][:test_retries]`

# `formatters`

The formatters to run with: the ones already configured, and Tuist's.

# `run`

# `split_args`

Splits the task's own options from the arguments meant for `mix test`.
A `--` separator is accepted for compatibility and dropped.

---

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