跳至内容

安装 Hex 包

Tuist 提供一个 Hex 包 tuist_ex，可与你的 Elixir 项目集成，以启用构建洞察和测试洞察等功能。本指南将带你完成安装和配置。

该包需要 Elixir 1.18 或更高版本。它不需要 Tuist 命令行界面。

1. 创建项目#

在 Tuist 仪表板中创建一个项目，并选择 Mix (Elixir) 作为其构建系统。其句柄 account/project 用于将你的 Mix 项目与之关联。

2. 添加包#

将 tuist_ex 添加到 mix.exs 的依赖项中：

elixir
defp deps do
[
{:tuist_ex, "~> 0.10", runtime: false}
]
end

然后获取它：

bash
mix deps.get

runtime: false 可确保 Tuist 不会进入你的运行应用程序。继续阅读Elixir 入门，以一起配置缓存、构建洞察和测试洞察。以下部分涵盖身份验证和配置详情。

3. 为你的团队和持续集成进行身份验证#

每位团队成员运行以下命令，以在其机器上访问 Tuist 功能：

bash
mix tuist.login

它会打印一个简短的登录代码，打开浏览器让你输入该代码，并等待你授权。要在不使用浏览器的情况下登录，请传递你的凭据：

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

当你使用自托管或本地 Tuist 服务器时，请在 mix.exs 中设置其基础 URL，或通过 --url 传递：

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

保持主机名拼写一致。例如，为 localhost 存储的登录信息与为 127.0.0.1 存储的登录信息是分开的。

在 GitHub Actions、CircleCI 和 Bitrise 上，持续集成无需登录步骤。任务首次发送报告时，会将提供程序的 OpenID Connect 令牌交换为 Tuist 令牌。将你的 GitHub 仓库连接到你的 Tuist 项目，并在 GitHub Actions 中为作业授予 id-token: write 权限：

yaml
jobs:
test:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v4
- uses: erlef/setup-beam@v1
with:
elixir-version: '1.18'
otp-version: '27'
- run: mix deps.get
- run: mix test

对于任何其他 OpenID Connect 身份提供商（例如 Fly.io Machines），请在账户的设置 → 身份验证页面的工作负载身份部分配置工作负载身份信任策略，这将授予 CI 对该账户拥有所有当前和未来项目的访问权限。将 TUIST_OIDC_ACCOUNT 设置为拥有该项目的 Tuist 账户，并通过 TUIST_OIDC_TOKEN 提供具有策略受众的新颁发身份令牌。当没有账户令牌或有效的存储登录信息时，集成会自动交换它；mix tuist.login 也接受在 CI 之外使用它。自动交换仅对同一服务器、账户和提供的身份令牌重用未过期的会话。更改该身份会触发新的交换，而提供空白身份会导致失败，而不是重用早期会话。Tuist 会话在没有刷新令牌的情况下持续一小时，因此对于长时间运行的工作负载，请在会话过期之前颁发新的身份令牌并再次运行 mix tuist.login。请参阅工作负载身份设置和Fly.io 示例。

来自分叉的拉取请求不会获得 OpenID Connect 令牌，因此它们的运行不会被报告，并且仍会像往常一样通过或失败。在其他提供商上，将 TUIST_TOKEN 环境变量设置为账户令牌。按照持续集成身份验证指南创建一个。

4. 继续使用 mix test 和 mix compile#

共享设置会为你安装编译和测试别名。mix test test/my_app_test.exs:12 --trace 会以相同的输出和退出代码报告运行，并且编译集成涵盖由 mix test 或 mix phx.server 触发的构建。如果编译发现无需执行的操作，则不会报告。

当你按名称调用任务时，它们也能正常工作。Mix 会在 dev 环境中启动以这种方式键入的任务，因此该任务必须在第二个进程中为测试环境重新启动。将任务添加到首选环境中以跳过此操作：

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

配置参考#

以下选项可在 mix.exs 的项目选项中 tuist 下使用：

选项 类型 默认值 描述
project String 无（必需） 采用 account/project 格式的项目标识符。
url String "https://tuist.dev" Tuist 服务器的基础 URL。
cache boolean 或关键字列表 禁用 设置启用依赖缓存。有关排除项和额外输入，请参阅Elixir 缓存。
test_retries integer 0 重试失败测试的次数；请参阅测试重试。
tags String 列表 [] 附加到每次构建的标签；请参阅自定义元数据。
values 映射 %{} 附加到每次构建的键值数据。

环境变量优先于 mix.exs：

变量 描述
TUIST_PROJECT 采用 account/project 格式的项目标识符。
TUIST_URL Tuist 服务器的基础 URL。
TUIST_TOKEN 用于身份验证的令牌，替代存储的登录信息。
TUIST_OIDC_TOKEN 新颁发的 OpenID Connect 身份令牌，可交换为 Tuist 令牌。对于 GitHub Actions 和 Bitrise，其受众必须为 tuist；对于其他提供商，则需与账户的工作负载身份匹配。由 mix tuist.login 使用，或在没有账户令牌或有效存储登录信息时作为回退方案。
TUIST_OIDC_ACCOUNT 拥有该项目的 Tuist 账户句柄。在通过账户工作负载身份交换令牌时需要。它会在现有工作负载身份中进行选择，本身不授予访问权限。
TUIST_TEST_RETRIES 重试失败测试的次数。
TUIST_TAGS 附加到构建的逗号分隔标签。
TUIST_VALUES 附加到构建的逗号分隔 key=value 对。
TUIST_DEBUG 设置为 1 以打印无法发送报告的原因。

报告永远不会改变 mix test 或 mix compile 的退出代码。如果无法发送报告，除非设置了 TUIST_DEBUG=1，否则任务不会输出任何内容。

后续步骤#

安装并配置包后，你可以使用：

  • 依赖缓存，以便在本地和 CI 构建中重用已编译的依赖项。
  • 构建洞察，用于跟踪编译时间、警告以及阻碍构建的因素。
  • 测试洞察，用于跟踪每个测试的性能。
  • 不稳定测试，用于检测和跟踪间歇性失败的测试。
  • 测试分片，以便将测试分散到持续集成运行器上执行。