Tuist for Elixir

This package connects an Elixir project to Tuist: it reports your test runs and builds to the dashboard, flags flaky tests, and splits a test suite across machines. It adds mix tuist.login, mix tuist.test, mix tuist.compile and mix tuist.test.build, and writes to the same Tuist server the command line tool and the Gradle plugin use.

The guides live in the Tuist documentation: start with Elixir project, and see Install the Hex package for every option.

Configure the server and project

You can share the Tuist server address and the project handle with your team in mix.exs:

def project do
  [
    app: :my_app,
    tuist: [
      url: "https://tuist.example.com",
      project: "your-account/your-project"
    ]
  ]
end

TUIST_URL and TUIST_PROJECT override those values, as they do in the Tuist command line tool. --url and --project are also accepted when the env overrides are unset. The default URL is https://tuist.dev.

Log in

mix tuist.login
mix tuist.login --email person@example.com --password secret
mix tuist.login --url https://tuist.example.com

Without credentials, the task opens a browser and waits for authorization. If you provide only --email or --password, it prompts for the missing value. On a continuous integration provider, it exchanges an OpenID Connect identity token from GitHub Actions, CircleCI, or Bitrise, matching the Tuist command line flow. On those providers a login step is optional: when no other credentials are available, the reporting tasks make the same exchange the first time they need a token. On GitHub Actions the job needs the id-token: write permission.

Credentials are saved under the Tuist configuration directory. The task writes them atomically with access restricted to the current user. Refreshes take a lock at the Tuist command line tool's lock path and reread the file before exchanging the refresh token, so parallel processes do not refresh the same token twice.

Run tests with analytics

mix tuist.test
mix tuist.test --project your-account/your-project
mix tuist.test --trace        # forwards --trace to mix test

mix tuist.test installs an ExUnit formatter alongside the default one and runs mix test. When the suite finishes, it POSTs a summary of the run, each module, each suite (from describe blocks), and each test case, including failure messages and source locations, to the Tuist server. Test timings are converted from microseconds to milliseconds. Every argument other than the task's own (--url, --project, --retries) is forwarded to mix test verbatim.

Elixir, OTP, Mix environment, the current git ref, and any recognised continuous integration provider metadata travel with the payload so a dashboard can group runs by branch, commit, and CI run.

Analytics submission never changes the exit code of mix test. If a request fails, set TUIST_DEBUG=1 to print the reason to standard error. Authentication uses the TUIST_TOKEN environment variable if set, then the credentials from mix tuist.login, then an OpenID Connect exchange on a supported continuous integration provider.

Keep using mix test and mix compile

Run the shared setup once:

mix tuist.setup --project your-account/your-project

Commit the updated mix.exs. Setup enables dependency caching and installs both compile and test integration, preserving other options and standard Phoenix test preparation. It refuses unsupported custom actions instead of removing them. Retries and CI sharding remain opt-in. No evaluation snippets or script paths are needed; see Get started with Elixir.

mix test test/my_test.exs:12 --trace then runs and reports exactly as mix tuist.test would. The alias also gets the environment right: Mix runs mix test in the test environment, whereas a task typed as mix tuist.test starts in dev and has to start over in a new process. If you call the tasks by name, set MIX_ENV=test or add preferred_envs: ["tuist.test": :test, "tuist.test.build": :test] to def cli in your mix.exs. Aliasing compile covers every compile, including the ones mix test or mix phx.server trigger; a compile that finds nothing to do is not reported.

Cache compiled dependencies

Enable dependency caching with cache: true to select supported dependencies automatically. It uses the same Kura REAPI ActionCache and CAS/ByteStream protocol as Bazel: an input key maps to an ActionResult whose output is a content-addressed dependency compilation bundle. A verified local snapshot store remains the fail-open fallback. The shared setup above enables this alongside build and test insights. mix compile restores matching dependency builds before Mix compiles the rest. The generated alias exposes compiled bootstrap modules without compiling other dependencies, including when Mix uses separate OS compiler workers. The wrapper re-enables Mix's normal dependency checks afterward, so local dependencies and unsupported chains still compile and changed locks are checked. Non-allowlisted fetched dependencies compile in batches, retaining Mix's OS-worker parallelism. Without an alias, use mix do deps.compile tuist_ex --include-children + deps.loadpaths --no-compile --no-deps-check + tuist.compile. Dependencies needed to bootstrap Tuist itself compile normally and, when already current, do not produce cache lookups. Jason and Decimal are bootstrap dependencies, so they are not useful demonstration allowlist entries; replace any restore demonstration with dependencies your project actually uses. A standalone mix tuist.compile may compile dependencies while discovering the task, before caching is available. It caches fetched, pure Elixir dependencies, not the project's own code. Native and custom compilers, local dependencies, and inputs it cannot model compile normally. Dependencies Mix already considers up to date need no lookup and are not counted as hits.

Declare extra compile-time file or directory inputs with inputs: ["path"] and environment-variable names with env: ["NAME"] in cache. Source contents, locked dependency identities, upstream sources and BEAMs, effective application configuration (explicit configured keys, with application defaults covered by dependency sources), dependency and VM-wide compiler options, dependency-specific env: and system_env:, Mix environment/target, and the Elixir build, full OTP version (when available), ERTS, compiler bytecode, OS version, architecture, word size and byte order enter the key. Standard compiler/runtime inputs (ERL_COMPILER_OPTIONS, ELIXIR_ERL_OPTIONS, ERL_AFLAGS, ERL_FLAGS, ERL_ZFLAGS, SOURCE_DATE_EPOCH, ERL_LIBS, MIX_PATH, and MIX_ARCHIVES) are included automatically; declare other compile-time environment variables explicitly. Inputs and effective configuration are captured before each dependency lookup and rechecked before publishing, so an earlier compilation cannot leave later lookups using stale inputs. Custom global tracers bypass caching so their side effects are not skipped.

Elixir macros can read arbitrary inputs. Declare additional inputs, exclude non-deterministic dependencies with exclude: [:dependency], or restrict selection with dependencies: [:dependency] when you need an audited allowlist. This is not automatic hermetic input discovery; changing undeclared external inputs can still make a bundle stale.

Verified local snapshots are tried before the remote cache. Idle builds and builds fully served locally do not contact cache endpoints or resolve credentials. A compile lazily opens one remote session, closes it even on compiler failure, and enforces a 30-second client RPC deadline independently of the server.

Remote caching uses the existing account endpoint discovery and project-scoped cache-token exchange. Kura reports signed action-cache and CAS analytics with client_kind: "mix", the Mix build ID and dependency name. There is no separate Mix storage or analytics API. Set remote: false for local-only caching; endpoint: can select a self-hosted HTTPS REAPI endpoint (HTTP is limited to loopback development hosts). Authentication, unavailable endpoints, quota refusals and storage failures fall back without hiding compiler failures. Set upload: false to read remote bundles without publishing new ones; local snapshots still populate. This is a client behavior option, not an authorization boundary. Dependency snapshots and remote bundles are capped at 64 MiB. Compiler manifests and BEAMs may embed producer checkout paths and compile-time values, including secrets. Audit selected dependencies and restrict project cache access accordingly. Writers are trusted code producers: a writer can publish executable BEAMs under computed keys. Digest verification detects corruption, not malicious producers. Do not provide cache-write credentials to untrusted branches or dependencies.

The local fallback is stored under the user's Tuist cache directory; path: selects a different location. Checkout paths are keyed by default. portable: true enables reuse across checkouts, but cached BEAMs retain producer paths, including compile-time __DIR__, __ENV__.file, and File.cwd!() values. Only enable it for dependencies whose behavior does not rely on those paths. Resource links are recreated for the current dependency checkout. Upstream BEAMs still enter portable keys and can embed absolute paths, so cross-checkout hits may require restoring the upstream dependency closure from the same cache too.

The Mix Cache dashboard shows average/percentile hit rates, cache I/O and recent builds. Successful REAPI operations report actual CAS payload bytes and client transfer durations with read_source/write_source set to remote; local fallback operations report local provenance, copied artifact and manifest bytes and verification/installation durations. Neither includes compilation or linked source resources. Legacy and failed observations remain unavailable rather than becoming measured zero. Open a build's Mix cache tab for task hits/misses, hit rate and transfer totals. Expanded tasks show only their real CAS output rows and digest links; diagnostics and measurement provenance remain in the analytics records. CAS Outputs uses Bazel's shared REAPI analytics queries and Kura-signed records for its download/upload graph, time-weighted throughput widgets, searchable/sortable table and copyable content hashes. Local-only builds do not invent remote outputs or throughput. Compressed sizes are not reported. Estimated compilation time avoided is the original compilation duration, not elapsed build time saved. Cache-only compiles are reported too. There is no automatic eviction for the local fallback store; Kura uses its existing shared cache retention and eviction. See Elixir cache for the full behavior and limitations.

Detect flaky tests with retries

ExUnit runs each test once, so a test that fails intermittently looks the same as a broken one. Turn retries on and the tests that failed are run again with mix test --failed, in a fresh process, up to the number of times you set:

tuist: [project: "your-account/your-project", test_retries: 2]

--retries 2 and TUIST_TEST_RETRIES=2 do the same for one invocation. A test that passes on a retry is reported with every attempt and shows up as flaky in the dashboard, and the command succeeds if every failed test eventually passes. Retries are off by default, in which case the exit code is always that of mix test.

A run that --max-failures cut short is never retried: the tests it did not reach are unknown, so the run is reported as it is and stays failed. Retries are also skipped with --warnings-as-errors, which mix test would no longer enforce, and from an umbrella's root: run the tests inside one of its applications to retry them.

Without retries, Tuist still flags a failure as flaky when the same test has also passed on the same commit in continuous integration, for example after someone reruns a failed job.

Build once, test on several machines

Sharding splits your tests across machines, balanced by how long each test module took in earlier runs, and reports them as one test run. Only one machine compiles; the others download its build.

On one machine, once per pipeline:

mix tuist.test.build --shard-max 4

This compiles the project for testing, asks Tuist to split the test files into at most four shards, and uploads the _build/test directory. A test file runs as a whole and is planned under the first module it defines; a file that cannot be parsed stops the plan, since the suite could not run either. On GitHub Actions it writes matrix={"shard":[0,1,2,3]} to the job outputs; elsewhere it writes the plan to .tuist-shard-matrix.json.

Then on each shard, after checking out the code and running mix deps.get:

TUIST_SHARD_INDEX=0 mix tuist.test

or plain mix test if you aliased it. The task downloads the build, runs only that shard's test files without compiling, and reports the results. Shards need the same Elixir and Erlang versions as the machine that built.

The shards find their plan by a reference derived from the pipeline run on GitHub Actions, GitLab, CircleCI and Buildkite. Anywhere else, set TUIST_SHARD_REFERENCE to the same value on every machine. Pass --no-upload to mix tuist.test.build if you would rather have each shard compile.

Test paths given on a shard's command line narrow what that shard runs. Run both commands inside an application: sharding from an umbrella's root is not supported yet.

Report code coverage

Pass --cover to mix tuist.test and the run's line coverage is reported with it, along with the run's Git history. Once every job that measures the commit's coverage has finished, tell Tuist the commit's coverage is complete with mix tuist.coverage.complete; until then the commit is shown as in progress and stays out of the branch's coverage trend.

Without shards

Run the whole suite with coverage, then mark the commit complete:

mix tuist.test --cover
mix tuist.coverage.complete

Tuist reads the counters Erlang's cover collected once the suite finishes, so your coverage tool keeps working as before: mix test's HTML report and threshold, or excoveralls.

With shards

Build the shards with --cover, run each one with --cover, and mark the commit complete from a job that runs after all of them:

# once, on the machine that builds
mix tuist.test.build --shard-total 4 --cover

# on each shard
TUIST_SHARD_INDEX=0 mix tuist.test --cover

# once every shard has finished
mix tuist.coverage.complete

On GitHub Actions, for example:

permissions:
  contents: read
  id-token: write # the tasks sign in with GitHub's identity token
jobs:
  build:
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
    steps:
      # checkout, Elixir, mix deps.get
      - id: plan
        run: mix tuist.test.build --shard-total 4 --cover
  test:
    needs: build
    strategy:
      matrix: ${{ fromJson(needs.build.outputs.matrix) }}
    env:
      TUIST_SHARD_INDEX: ${{ matrix.shard }}
    steps:
      # checkout, Elixir, mix deps.get
      - run: mix tuist.test --cover
  complete:
    needs: test
    # A shard with a failing test still reported its coverage.
    if: ${{ !cancelled() }}
    steps:
      # checkout, Elixir, mix deps.get
      - run: mix tuist.coverage.complete

Each shard reports its share and Tuist merges them into one run. Erlang's cover compiles every module of the project again at the start of each run, which on a large project costs every shard a minute or more, so with --cover the build's modules are recompiled once, on the machine that builds, with the runtime's native line counters. Each shard switches the counters on and counts with them instead of running Mix's coverage tool, so no Mix coverage report is written. Only the modules Mimic copies are compiled for cover, because Mimic keeps a cover compiled module's counts across the swaps it makes and reloading a module resets its native counters.

A shard on a runtime without the JIT cannot count natively and uses Mix's coverage tool, as does one built without --cover. Its coverage is then exported, under cover/shard-<index> unless you pass --export-coverage yourself, rather than held to the project's threshold, which a shard running part of the suite would not meet.

What is reported

Each covered file is reported with the OTP application it belongs to and the Git blob it had, and files under your test paths count as test code, which no figure includes. Each file also lists its functions; lines that hold only code the compiler or a macro generates, such as the line defmodule, schema or use sits on, count for the file but belong to no function.

A run that picks its tests (--only, --exclude, --failed, --stale, or test files on the command line) is reported as partial and stays out of the branch's coverage trend.

The run's Git history is the merge base with the branch a pull request merges into and the commits Tuist does not have yet. A shallow clone is deepened, within a time budget, until the merge base is found.

Optional reported actor

Build and test reports include an optional x-tuist-actor-id header only when explicitly configured. No claim is sent by default, and operating-system usernames are not detected. This is an unverified label, not a credential or a verified user identity. Existing authentication and report payloads are unchanged. Older servers ignore the header; displaying the claim requires server support.

Use TUIST_ACTOR_ID=employee-123, a runtime actor_id: "employee-123" option, or tuist: [actor_id: "employee-123"] in your Mix project to opt in, in that order. Values must be 1–128 bytes of printable, non-space ASCII. An explicitly empty or invalid override omits the claim instead of falling back to a lower-precedence setting.

Set TUIST_ACTOR_ID="" to suppress a configured claim, including when a custom proxy rejects unfamiliar headers. Claims may be visible to report viewers on supporting servers; avoid sensitive personal identifiers.

Tag runs with custom metadata

Every submitted run can carry customer-supplied tags (labels for filtering) and values (key/value pairs). Sources merge with the environment last:

def project do
  [
    app: :my_app,
    tuist: [
      url: "https://tuist.example.com",
      project: "your-account/your-project",
      tags: ["nightly"],
      values: %{"team" => "platform"}
    ]
  ]
end

TUIST_TAGS (comma-separated) and TUIST_VALUES (key=value pairs, comma-separated) override the mix.exs config. The Tuist dashboards use those labels to group and filter runs across ecosystems.

Compile with analytics

mix tuist.compile
mix tuist.compile --force

mix tuist.compile wraps mix compile, attaches an after-compiler hook to the Elixir and .app compilers, and submits a build record to your Tuist dashboard when the compile finishes. The record carries duration and status, each warning and error as a distinct diagnostic (file, module, message, line, and column), a per-file profile (when each file started compiling, how long it compiled, the project files it depends on and how strongly, and how long it sat paused waiting on other files) and the other work the compiler reports (type checking each module, writing modules to disk, the other Mix compilers), which together feed the build's timeline, machine samples taken once a second (processor, memory, network and disk throughput), plus the same environment metadata (Elixir and Open Telecom Platform versions, Mix environment, git ref, and continuous integration provider) that mix tuist.test submits. Every argument other than --url and --project is forwarded to mix compile. Submission failures never change the exit code of mix compile.

Development

Requires Elixir 1.18 or later. From tuist_ex/:

mix deps.get
mix format --check-formatted
mix compile --warnings-as-errors
mix test --warnings-as-errors
mix hex.build
mix docs --warnings-as-errors

Quokka is configured as a formatter plugin. mix format applies its fixes; mix format --check-formatted enforces them in automated checks. Mimic is available for test mocks. Register modules with Mimic.copy/1 in test/test_helper.exs as tests are added. The package currently has focused authentication and locking tests.

Automated checks and releases

The check workflow runs compilation, documentation, tests, formatting, and package assembly as separate jobs. Compilation checks Elixir 1.18 and the repository's current Elixir version; the other jobs use the current version.

The tuist-ex release component uses tuist-ex@ tags and scoped commits such as feat(tuist-ex): add build instrumentation. On main, the release workflow checks for a version bump, runs the same validation, publishes the package and documentation to Hex, and creates a GitHub release. Publication is serialized and never cancelled mid-release. If package publication succeeds but the GitHub release fails, a retry verifies the published package contents and resumes documentation and release creation without replacing the package. Manual releases are restricted to main.

The release workflow sets the package version from the shared release checker; the version in mix.exs is the development baseline. Release notes are generated from scoped commits using cliff.toml.

Publication reuses the repository's HEX_API_KEY secret, which also publishes Noora. Its Hex account must be the intended owner of tuist_ex and the key must have package publishing permission. The first publication requires the package name to be available. TUIST_RELEASE_GITHUB_TOKEN is used for GitHub releases when available, with the workflow token as the fallback.