跳至内容

Elixir 测试分片

Tuist Hex 包内置支持对 Elixir 项目的测试进行分片。它利用 Tuist 服务器根据历史耗时数据创建均衡的分片计划,并只编译一次项目,让每个运行器都能直接执行测试。

要求

工作原理#

测试分片遵循两阶段工作流:

  1. 构建阶段: Tuist 为测试编译你的项目,枚举测试文件,并在服务器上创建分片计划。服务器使用过去 30 天的历史测试耗时数据将测试分配到各个分片,使每个分片的耗时大致相同。构建阶段会上传构建产物,并输出一个分片矩阵,供你的 CI 系统用来生成并行运行器。
  2. 测试阶段: 每个 CI 运行器接收一个分片索引,下载构建产物,并仅执行分配给该分片的测试。
Note

在已注册的 Tuist Linux 运行器上,分片构建可以使用本地制品存储。所有使用该构建的分片必须在同一站点的已注册运行器上运行;如果要将工作流迁移到其他运行器,请禁用本地存储后重新运行构建。

测试按文件分配:文件中的每个测试都在同一个分片上运行。Tuist 尚未见过的测试会获得估算值,因此项目的前几次计划不如后续计划均衡。

构建阶段#

使用 tuist.test.build 任务准备测试分片:

bash
MIX_ENV=test mix compile --warnings-as-errors
MIX_ENV=test mix tuist.test.build --shard-max 5

在调用分片任务之前,先通过共享设置安装的别名进行编译。在冷检出时,Mix 可能在发现 tuist.test.build 的同时编译依赖项,此时 Tuist 的依赖缓存还来不及恢复它们。显式编译在与分片任务相同的测试环境中运行。

此任务:

  1. 在测试环境中编译项目
  2. 使用历史耗时数据在 Tuist 服务器上创建分片计划
  3. 上传构建产物,避免分片再次编译
  4. 为你的 CI 系统输出分片矩阵

构建选项#

选项 描述
--shard-max <N> 最大分片数(默认:2)
--shard-min <N> 最小分片数
--shard-total <N> 精确的分片数,而非范围
--shard-max-duration <MS> 每个分片的目标最大持续时间(毫秒)
--shard-reference <REF> 分片查找计划时使用的名称
--no-upload 规划分片但不上传构建产物;每个分片随后自行编译

所有其他参数都会转发给 mix compile。

分片引用会自动从 CI 环境变量(GITHUB_RUN_ID、CI_PIPELINE_ID、CIRCLE_WORKFLOW_ID、BUILDKITE_BUILD_ID)派生,或者可以通过 TUIST_SHARD_REFERENCE 环境变量显式设置。在这些提供商之外,你必须将其设置为构建阶段和同一次流水线运行的分片共享的值。在 GitHub Actions 上,引用还包括运行尝试:当仅重新运行失败的任务时,请传递原始构建任务的引用,而不是在分片任务中派生新的引用。

测试阶段#

当设置 TUIST_SHARD_INDEX 时,包会从服务器获取分片分配,下载构建产物,并仅运行分配的测试文件而不进行编译。在冷运行器上,请在调用任务之前引导 SDK 并加载其路径:

bash
MIX_ENV=test TUIST_SHARD_INDEX=0 mix do deps.compile tuist_ex --include-children + deps.loadpaths --no-compile --no-deps-check + tuist.test

在 Mix 的工作进程中编译 SDK 不会将其加载到父进程中。显式的 deps.loadpaths 步骤可防止任务发现在下载构建产物之前编译剩余的依赖项。这种单命令形式保留了项目的测试准备别名。如果其设置命令触发了编译,请使用下面的单独设置序列。

你传入的任何测试文件或目录都会进一步缩小分片范围:只有既在分片中又在你的选择范围内的文件才会运行。最终没有测试的分片会成功退出。

所有分片的结果会在仪表板上作为单次测试运行呈现,其分片部分显示每个分片的耗时。

如果必须在测试之前运行设置,请先下载构建产物而不启动应用程序:

bash
MIX_ENV=test TUIST_SHARD_INDEX=0 mix do deps.compile tuist_ex --include-children + deps.loadpaths --no-compile --no-deps-check + tuist.test --prepare-only

在禁用编译的单独进程中运行你的设置。例如,Ecto 项目可以使用以下命令创建并迁移其数据库:

bash
MIX_ENV=test mix run --no-start --no-compile --no-deps-check -e 'Mix.Tasks.Ecto.Create.run([]); Mix.Tasks.Ecto.Migrate.run([])'

在此阶段保留任何其他特定于项目的准备工作。你的编译别名在执行引导工作之前也必须遵守 --no-compile:Mix 仅将标志转发给列表别名的最后一个任务,因此较早的无条件 deps.compile 仍会运行。请参阅手动编译集成中的受保护别名。

然后在执行分片之前加载恢复的 SDK 而不进行编译。这还可以防止任务发现在源文件比下载的构建产物更新时编译路径依赖:

bash
MIX_ENV=test TUIST_SHARD_INDEX=0 mix do deps.loadpaths --no-compile --no-deps-check + tuist.test --no-download

两个命令都需要相同的分片引用。--prepare-only 需要已上传的构建产物,如果缺少准备好的应用程序制品,--no-download 会失败。--no-download 显式跳过项目的测试准备别名(包括重试时),并在跳过设置步骤时打印通知。常规运行保留其别名,即使你转发 --no-compile --no-deps-check。将数据库迁移保持在单独的进程中还可以避免模块重定义警告,因为迁移回归测试会自行加载这些模块。

在测试不同环境时,传递稳定的 --scheme 标签,例如 --scheme clickhouse-current 或 --scheme clickhouse-floor。具有不同标签的结果不会被视作同一配置的不稳定重跑。

分片所需内容#

上传的构建产物是 _build/test 目录。每个分片运行器仍需要:

  • 与构建阶段相同的代码检出
  • 相同的 Elixir 和 Erlang/OTP 版本
  • 依赖源代码,来自 mix deps.get

尚不支持从 umbrella 项目的根目录进行分片。请在其中一个应用程序内运行这两个阶段。

持续集成#

GitHub Actions#

在 GitHub Actions 中,构建阶段会将分片索引写入其步骤的 matrix 输出。使用矩阵策略并行运行分片:

yaml
name: Tests
on: [pull_request]
env:
MIX_ENV: test
TUIST_TOKEN: ${{ secrets.TUIST_TOKEN }}
jobs:
build:
name: Build test shards
runs-on: ubuntu-latest
outputs:
matrix: ${{ steps.build.outputs.matrix }}
steps:
- uses: actions/checkout@v4
- uses: erlef/setup-beam@v1
with:
elixir-version: '1.18'
otp-version: '27'
- run: mix deps.get
- run: mix compile --warnings-as-errors
- id: build
run: mix tuist.test.build --shard-max 5
test:
name: "Shard #${{ matrix.shard }}"
needs: build
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
shard: ${{ fromJson(needs.build.outputs.matrix).shard }}
env:
TUIST_SHARD_INDEX: ${{ matrix.shard }}
steps:
- uses: actions/checkout@v4
- uses: erlef/setup-beam@v1
with:
elixir-version: '1.18'
otp-version: '27'
- run: mix deps.get
- run: mix do deps.compile tuist_ex --include-children + deps.loadpaths --no-compile --no-deps-check + tuist.test --prepare-only
# Ecto example: keep all project-specific test preparation here.
# The project's compile alias must honor --no-compile (see above).
- run: mix run --no-start --no-compile --no-deps-check -e 'Mix.Tasks.Ecto.Create.run([]); Mix.Tasks.Ecto.Migrate.run([])'
- run: mix do deps.loadpaths --no-compile --no-deps-check + tuist.test --no-download

其他提供商#

在 GitHub Actions 之外,构建阶段会将计划写入 .tuist-shard-matrix.json:

json
{
"reference": "gitlab-1234",
"shard_count": 2,
"shards": [
{
"index": 0,
"test_targets": ["MyApp.AccountsTest", "MyApp.CheckoutTest"],
"estimated_duration_ms": 41000
},
{
"index": 1,
"test_targets": ["MyAppWeb.PageControllerTest"],
"estimated_duration_ms": 39500
}
]
}

使用 shard_count 设置你的并行作业,并为每个作业分配其 TUIST_SHARD_INDEX,范围从 0 到 shard_count - 1。对于 Tuist 无法自动派生引用的提供商,还需为每个作业提供相同的 TUIST_SHARD_REFERENCE。