Cómo generar archivos de prueba en un pipeline de CI

Un fixture binario en un repositorio se queda para siempre en su historial, no se puede revisar en un diff y deja de ser posible cuando el archivo es grande. Genera los archivos dentro del pipeline a partir de una receta. La receta es texto, los bytes salen iguales cada vez y un último paso demuestra que nada se movió.

La respuesta corta

Instala tfg, ejecuta tfg generate fixtures.yaml --out ./fixtures antes de las pruebas y tfg verify ./fixtures/manifest.json después. Los dos pasos hacen fallar la compilación por sí solos, con un código de salida que dice por qué.

Por qué no subirlos

Por qué un fixture no debe vivir en el repositorio

Se queda en el historial. Borrar un binario más tarde no hace más pequeño un clon, porque todas sus versiones siguen ahí.
Un diff no muestra qué cambió. El revisor ve que un PDF es distinto y nada más. Una receta cambia en una línea.
Los archivos grandes no caben. GitHub rechaza un push que contenga un archivo de más de 100 MB, así que una prueba de un límite de subida de 500 MB no tiene nada que subir.

Lo que hay que subir es la receta. La misma receta y la misma semilla escriben los mismos bytes en cualquier máquina, así que el archivo generado en el pipeline es el que tenías en tu portátil.

La receta

Una receta que vive junto a las pruebas

Esta escribe veinticinco facturas que deben aceptarse y dos imágenes por encima de un límite que deben rechazarse, y el manifiesto registra las dos expectativas:

version: 1
seed: 7741

targets:
  - id: invoices
    format: pdf
    count: 25
    size: 300kb
    expected: accept

  - id: over_the_limit
    format: png
    count: 2
    size: 12mb
    expected:
      outcome: reject
      reason: size_limit

tfg validate fixtures.yaml la comprueba sin escribir nada y nombra todos los problemas a la vez.

GitHub Actions

Un workflow que instala la herramienta y construye los fixtures

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TFG_VERSION: "0.4.0"
    steps:
      - uses: actions/checkout@v4

      - name: install tfg
        run: |
          base=https://github.com/donislawdev/TestingFilesGenerator/releases/download/v$TFG_VERSION
          curl -fsSLO "$base/tfg_${TFG_VERSION}_linux_amd64.tar.gz"
          curl -fsSLO "$base/verify-SHA256SUMS.txt"
          sha256sum --check --ignore-missing verify-SHA256SUMS.txt
          tar -xzf "tfg_${TFG_VERSION}_linux_amd64.tar.gz" ./tfg
          sudo mv tfg /usr/local/bin/

      - name: build the fixtures
        run: tfg generate fixtures.yaml --out ./fixtures

      - name: run the tests
        run: pytest tests/

      - name: nothing moved
        run: tfg verify ./fixtures/manifest.json

La línea de la suma de comprobación compara el archivo con verify-SHA256SUMS.txt de la misma versión. La versión está fijada, así que una versión nueva nunca cambia una compilación que no tocaste.

GitLab CI

Lo mismo como job de GitLab

fixtures:
  image: ubuntu:24.04
  variables:
    TFG_VERSION: "0.4.0"
  script:
    - apt-get update -qq && apt-get install -y -qq curl ca-certificates
    - base=https://github.com/donislawdev/TestingFilesGenerator/releases/download/v$TFG_VERSION
    - curl -fsSLO "$base/tfg_${TFG_VERSION}_linux_amd64.tar.gz"
    - curl -fsSLO "$base/verify-SHA256SUMS.txt"
    - sha256sum --check --ignore-missing verify-SHA256SUMS.txt
    - tar -xzf "tfg_${TFG_VERSION}_linux_amd64.tar.gz" ./tfg
    - ./tfg generate fixtures.yaml --out ./fixtures
    - pytest tests/
    - ./tfg verify ./fixtures/manifest.json

Cuando se pone en rojo

Qué hace fallar un paso, y por qué

Cada final tiene su propio código de salida, así que el paso falla por sí solo y el registro dice cuál fue. Los que encuentra un pipeline:

3 - la receta no es válida. No se escribió nada y se nombra cada problema
4 - el formato no puede hacer lo pedido, por ejemplo un tamaño por debajo de su mínimo
6 - no hay suficiente espacio en disco
7 - tfg verify encontró un archivo que no coincide con su manifiesto
8 - la ejecución terminó, pero no se produjo todo

Una ejecución fallida no imprime nada en la salida estándar, así que un analizador de registros nunca toma un error por datos. La tabla completa está en la página de documentación.

PowerShell

Un script de PowerShell necesita una línea más

PowerShell no saca el código de salida de un programa fuera de un archivo .ps1. Ejecuta uno con -File y el script responde 0 incluso cuando la herramienta de dentro rechazó el trabajo, así que una compilación que debería estar en rojo pasa a verde. La última línea es toda la solución:

tfg generate fixtures.yaml --out ./fixtures
exit $LASTEXITCODE

Así se comporta PowerShell, no es algo de esta herramienta. cmd, bash y zsh no necesitan nada más.

Varios jobs

Compartir los fixtures entre jobs

Normalmente no hace falta subirlos. Como la misma receta escribe los mismos bytes, cada job puede ejecutar su propio tfg generate, que es más rápido que subir y bajar. Cuando un job tiene que recibir archivos de otro, ejecuta tfg verify sobre el manifiesto tras la transferencia y te dice si lo que llegó es lo que se escribió.

Archivos de prueba corruptos añade a la misma receta archivos rotos a propósito.
Los casos de uso muestran qué más puede comprobar una ejecución en un pipeline.
La documentación recoge cada comando, cada clave de receta y cada código de salida.