Перейти к содержимому

Шардирование тестов Elixir

Пакет Tuist для Hex включает встроенную поддержку шардирования тестов проекта на Elixir. Он использует сервер Tuist для создания сбалансированных планов шардов на основе исторических данных о времени выполнения и компилирует ваш проект один раз, чтобы каждый раннер мог сразу приступить к запуску тестов.

Требования

Как это работает#

Шардирование тестов следует двухэтапному рабочему процессу:

  1. Фаза сборки: Tuist компилирует ваш проект для тестирования, перечисляет файлы тестов и создает план шардов на сервере. Сервер использует исторические данные о времени выполнения тестов за последние 30 дней, чтобы распределить тесты по шардам так, чтобы каждый шард занимал примерно одинаковое время. Фаза сборки загружает сборку и выводит матрицу шардов, которую ваша система CI использует для запуска параллельных раннеров.
  2. Фаза тестирования: Каждый раннер CI получает индекс шарда, скачивает сборку и выполняет только те тесты, которые назначены этому шарду.
Note

На зарегистрированных Linux-раннерах Tuist сборки шардов могут использовать локальное хранилище артефактов. Все шарды, использующие такую сборку, должны выполняться на зарегистрированных раннерах в одном месте; при переносе рабочего процесса на другие раннеры перезапустите сборку с отключенным локальным хранилищем.

Тесты распределяются по файлам: все тесты в одном файле выполняются на одном шарде. Для тестов, которые 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

Компиляция SDK в рабочих процессах Mix не загружает его в родительский процесс. Явный шаг 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 без компиляции перед выполнением шарда. Это также предотвращает компиляцию path-зависимости при обнаружении задач, если ее исходники новее скачанной сборки:

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.