コンテンツへスキップ

Install the Hex package

Tuist provides a Hex package, tuist_ex, that integrates with your Elixir project to enable features like build insights and test insights. This guide walks you through installing and configuring it.

The package requires Elixir 1.18 or later. It does not need the Tuist command-line interface.

1. Create the project#

Create a project in the Tuist dashboard and choose Mix (Elixir) as its build system. Its handle, account/project, is what connects your Mix project to it.

2. Add the package#

Add tuist_ex to the dependencies in your mix.exs and set the project handle:

elixir
def project do
[
app: :my_app,
deps: deps(),
tuist: [project: "account/project"]
]
end
defp deps do
[
{:tuist_ex, "~> 0.3", runtime: false}
]
end

Then fetch it:

bash
mix deps.get

The package only adds Mix tasks, so runtime: false keeps it out of your running application.

3. Authenticate your team and continuous integration#

Each teammate runs the following to get access to the Tuist features on their machine:

bash
mix tuist.login

It opens a browser and waits for you to authorize. To log in without a browser, pass your credentials:

bash
mix tuist.login --email [email protected] --password secret

When you use a self-hosted or local Tuist server, set its base URL in mix.exs, or pass it with --url:

bash
mix tuist.login --url http://localhost:8080

Keep the hostname spelling consistent. For example, a login stored for localhost is separate from one stored for 127.0.0.1.

For automated runners, set the TUIST_TOKEN environment variable to a project token instead of logging in. Follow the continuous integration authentication guide to create one.

4. Keep using mix test and mix compile#

The package adds mix tuist.test and mix tuist.compile, which run mix test and mix compile and report the result. Both take the same command line as the task they wrap, so you can alias them and nobody, person or coding agent, has to learn a different command:

elixir
def project do
[
app: :my_app,
aliases: [test: "tuist.test", compile: "tuist.compile"],
tuist: [project: "account/project"]
]
end

mix test test/my_app_test.exs:12 --trace then runs and reports exactly as mix tuist.test would. 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.

The tasks also work when you call them by their own name. Mix starts a task typed that way in the dev environment, so the task has to start over in a second process for the test environment. Add the tasks to the preferred environments to skip that:

elixir
def cli do
[preferred_envs: ["tuist.test": :test, "tuist.test.build": :test]]
end

Configuration reference#

The following options are available under tuist in the project options of mix.exs:

OptionTypeDefaultDescription
projectStringnone (required)The project identifier in account/project format.
urlString"https://tuist.dev"The base URL of the Tuist server.
test_retriesinteger0How many times to retry the tests that failed; see test retries.
tagslist of String[]Tags to attach to every build; see custom metadata.
valuesmap%{}Key-value data to attach to every build.

Environment variables take precedence over mix.exs:

VariableDescription
TUIST_PROJECTThe project identifier in account/project format.
TUIST_URLThe base URL of the Tuist server.
TUIST_TOKENThe token to authenticate with, instead of the stored login.
TUIST_TEST_RETRIESHow many times to retry the tests that failed.
TUIST_TAGSComma-separated tags to attach to the build.
TUIST_VALUESComma-separated key=value pairs to attach to the build.
TUIST_DEBUGSet to 1 to print why a report could not be sent.

Reporting never changes the exit code of mix test or mix compile. If a report cannot be sent, the task says nothing unless TUIST_DEBUG=1 is set.

Next steps#

Once the package is installed and configured, you can use:

  • Build insights to track compile times, warnings, and what holds your builds back.
  • Test insights to track test performance down to each test.
  • Flaky tests to detect and track tests that fail intermittently.
  • Test sharding to split your tests across continuous integration runners.