Saltar al contenido

Fragmentación de tests en Elixir

El paquete Hex de Tuist incluye soporte integrado para fragmentar los tests de un proyecto Elixir. Utiliza el servidor de Tuist para crear planes de fragmentación equilibrados basados en datos históricos de tiempos de ejecución, y compila tu proyecto una sola vez para que cada runner pueda pasar directamente a ejecutar los tests.

Requisitos

Cómo funciona#

La fragmentación de tests sigue un flujo de trabajo en dos fases:

  1. Fase de compilación: Tuist compila tu proyecto para testing, enumera tus archivos de test y crea un plan de fragmentación en el servidor. El servidor utiliza datos históricos de tiempos de ejecución de los últimos 30 días para distribuir los tests entre las fragmentaciones, de modo que cada una tarde aproximadamente lo mismo. La fase de compilación sube el build y genera una matriz de fragmentación que tu sistema de CI utiliza para lanzar runners en paralelo.
  2. Fase de test: Cada runner de CI recibe un índice de fragmentación, descarga el build y ejecuta únicamente los tests asignados a esa fragmentación.
Note

En los runners Linux de Tuist inscritos, las compilaciones de fragmentación pueden usar el almacenamiento local de artefactos. Todas las fragmentaciones que consuman dicho build deben ejecutarse en runners inscritos en el mismo sitio; vuelve a ejecutar la compilación con el almacenamiento local desactivado al mover el flujo de trabajo a otros runners.

Los tests se distribuyen por archivo: todos los tests de un archivo se ejecutan en la misma fragmentación. Los tests que Tuist aún no ha visto reciben una estimación, por lo que los primeros planes de un proyecto están menos equilibrados que los posteriores.

Fase de compilación#

Prepara las fragmentaciones de test usando la tarea tuist.test.build:

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

Compila a través del alias instalado por la configuración compartida antes de invocar la tarea de fragmentación. En un checkout limpio, Mix puede compilar dependencias mientras descubre tuist.test.build, antes de que la caché de dependencias de Tuist tenga oportunidad de restaurarlas. La compilación explícita se ejecuta en el mismo entorno de test que la tarea de fragmentación.

Esta tarea:

  1. Compila el proyecto en el entorno de test
  2. Crea un plan de fragmentación en el servidor de Tuist utilizando datos históricos de tiempos
  3. Sube el build para que las fragmentaciones no vuelvan a compilar
  4. Genera una matriz de fragmentación para tu sistema de CI

Opciones de compilación#

Opción Descripción
--shard-max <N> Número máximo de fragmentaciones (predeterminado: 2)
--shard-min <N> Número mínimo de fragmentaciones
--shard-total <N> Número exacto de fragmentaciones, en lugar de un rango
--shard-max-duration <MS> Duración máxima objetivo por fragmentación en milisegundos
--shard-reference <REF> El nombre con el que las fragmentaciones encuentran el plan
--no-upload Planifica las fragmentaciones sin subir el build; cada fragmentación compila por su cuenta

Cualquier otro argumento se reenvía a mix compile.

La referencia de fragmentación se deriva automáticamente de las variables de entorno de CI (GITHUB_RUN_ID, CI_PIPELINE_ID, CIRCLE_WORKFLOW_ID, BUILDKITE_BUILD_ID) o se puede establecer explícitamente mediante la variable de entorno TUIST_SHARD_REFERENCE. Fuera de esos proveedores, debes configurarla con un valor que compartan la fase de compilación y las fragmentaciones de una misma ejecución de pipeline. En GitHub Actions, las referencias también incluyen el intento de ejecución: al volver a ejecutar solo los jobs fallidos, pasa la referencia del job de compilación original en lugar de derivar una nueva en los jobs de fragmentación.

Fase de test#

Cuando TUIST_SHARD_INDEX está configurada, el paquete obtiene la asignación de fragmentación del servidor, descarga el build y ejecuta solo los archivos de test asignados sin compilar. En un runner limpio, inicializa el SDK y carga sus rutas antes de invocar la tarea:

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

Compilar el SDK en los procesos worker de Mix no lo carga en el proceso padre. El paso explícito deps.loadpaths evita que el descubrimiento de tareas compile las dependencias restantes antes de descargar el build. Esta forma de comando único preserva el alias de preparación de tests de tu proyecto. Si sus comandos de configuración activan la compilación, usa la secuencia de configuración separada que aparece más abajo.

Cualquier archivo o directorio de test que pases reduce aún más la fragmentación: solo se ejecutan los archivos que están tanto en la fragmentación como en tu selección. Una fragmentación que queda sin tests finaliza con éxito.

Los resultados de todas las fragmentaciones llegan al dashboard como una única ejecución de tests, y su sección Fragmentaciones muestra cuánto tardó cada una.

Si la configuración debe ejecutarse antes de los tests, descarga primero el build sin iniciar la aplicación:

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

Ejecuta tu configuración en un proceso separado con la compilación desactivada. Por ejemplo, un proyecto Ecto puede crear y migrar sus bases de datos usando:

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

Mantén cualquier otra preparación específica del proyecto en esta fase. Tu alias de compilación también debe respetar --no-compile antes de realizar el trabajo de inicialización: Mix solo reenvía flags a la última tarea de un alias de lista, por lo que un deps.compile incondicional anterior sigue ejecutándose. Consulta el alias protegido en integración manual de compilación.

Luego carga el SDK restaurado sin compilación antes de ejecutar la fragmentación. Esto también evita que el descubrimiento de tareas compile una dependencia de ruta cuando sus fuentes son más recientes que el build descargado:

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

Ambos comandos necesitan la misma referencia de fragmentación. --prepare-only requiere un build subido, y --no-download falla si falta el artefacto de aplicación preparado. --no-download omite explícitamente el alias de preparación de tests de tu proyecto, incluso en reintentos, e imprime un aviso cuando omite pasos de configuración. Las ejecuciones normales mantienen sus aliases, incluso cuando reenvías --no-compile --no-deps-check. Mantener las migraciones de base de datos en un proceso separado también evita advertencias de redefinición de módulos cuando los tests de regresión de migraciones cargan esos módulos por sí mismos.

Al probar diferentes entornos, pasa una etiqueta --scheme estable, como --scheme clickhouse-current o --scheme clickhouse-floor. Los resultados con etiquetas diferentes no se tratan como reejecuciones inestables de la misma configuración.

Qué necesitan las fragmentaciones#

El build subido es el directorio _build/test. Cada runner de fragmentación aún necesita:

  • El mismo checkout que en la fase de build
  • Las mismas versiones de Elixir y Erlang/OTP
  • Las fuentes de las dependencias, obtenidas con mix deps.get

La fragmentación desde la raíz de un proyecto umbrella aún no está soportada. Ejecuta ambas fases dentro de una de sus aplicaciones.

Integración continua#

GitHub Actions#

En GitHub Actions, la fase de build escribe los índices de fragmentación en la salida matrix de su paso. Usa una estrategia de matriz para ejecutar las fragmentaciones en paralelo:

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

Otros proveedores#

Fuera de GitHub Actions, la fase de build escribe el plan en .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
}
]
}

Usa shard_count para configurar tus jobs paralelos y asigna a cada job su TUIST_SHARD_INDEX, desde 0 hasta shard_count - 1. En un proveedor del que Tuist no derive la referencia, asigna también a cada job el mismo TUIST_SHARD_REFERENCE.