Ejecutar en CI

astral-test ejecuta las pruebas guardadas de un proyecto sin abrir Astral y sin incluir ni descargar un navegador. Úsalo en CI, o en el bucle de un agente para repetir las pruebas tras una corrección.

Instalación

astral-test es un único binario para macOS (Apple Silicon e Intel) y Linux x64, enlazado desde las descargas para desarrolladores. Puede faltar una versión de Windows en una release porque Windows aún no está verificado.

BASE=https://downloads.perseusoft.tech/astral-test/latest
curl -fsSLO "$BASE/astral-test-x86_64-unknown-linux-gnu.tar.gz"
tar xzf astral-test-x86_64-unknown-linux-gnu.tar.gz
./astral-test --version

Necesita un navegador ya instalado en el equipo: Google Chrome, Chromium o Microsoft Edge (el motor cdp; ASTRAL_CHROME apunta a un binario concreto), cualquier navegador ya iniciado con DevTools mediante --cdp-url, o Lightpanda en tu PATH (el motor lite). astral-test doctor informa de lo que encontró y de lo que usaría.

Comandos

astral-test run [PATH=.] [--env NAME] [--test ID]... [--collection ID]
                [--engine lite|cdp] [--cdp-url ws://...|http://...]
                [--reporter pretty|json|junit]... [--out DIR=astral-test-results]
                [--timeout-ms N=120000] [--bail] [--record off|steps|actions|video]
astral-test list [PATH=.] [--json]
astral-test doctor [PATH=.] [--engine lite|cdp] [--cdp-url ...] [--probe] [--json]

Sin --test ni --collection, se ejecutan todas las pruebas guardadas, ordenadas por id.
--env acepta un entorno de config.json o una URL http(s).
--bail informa del resto como omitidas tras el primer fallo.
Cada prueba se ejecuta en un contexto de navegador nuevo: no se arrastran cookies ni almacenamiento.

Códigos de salida

Código	Significado
0	Todas las pruebas seleccionadas pasaron (las omitidas no cuentan como fallo).
1	Al menos una prueba falló: la app no hizo lo que la prueba espera.
2	Uso o configuración: argumentos, proyecto o `config.json` incorrectos, prueba o entorno desconocidos, o una credencial que no se puede resolver.
3	Motor: no se encontró ningún navegador, o no arrancó, no respondió o no se mantuvo activo.

Si hay varios problemas, gana el más grave: 3, luego 2, luego 1.

Motores

	`lite` (Lightpanda)	`cdp` (Chrome, Chromium, Edge)
Fidelidad	DOM y JavaScript, sin renderizado ni layout CSS.	Completa.
Evidencias	Árboles de página en lugar de capturas; sin vídeo.	Capturas y una grabación en PNG animado.
Comprobaciones de layout	Se informan como omitidas, nunca como superadas.	Sí, con emulación de viewport.
Uso	Flujos rápidos sin dependencia visual.	Pruebas que dependen del layout y de las capturas.

Por defecto se usa lite si Lightpanda está instalado; si no, cdp.

Credenciales en CI

{ "env": "ASTRAL_TEST_..." } lee una variable de entorno del proceso, que en CI es un secreto. { "local": "..." } lee .astral/secrets.local.json. Una referencia keychain no está disponible fuera de la app: la prueba falla con un mensaje que indica qué variable definir. Los valores secretos nunca aparecen en la salida.

En CI la fuente de verdad es el repositorio: en un entorno protegido, astral-test confía en la declaración readOnly del archivo de la prueba, así que un cambio bajo .astral/ necesita revisión de código.

Salida

JUnit y artefactos

Con --reporter junit y --out DIR obtienes:

junit.xml, un caso de prueba por prueba (y por viewport, con un sufijo como [mobile]).
<testId>/report.html y report.json, el mismo informe que escribe la app.
Capturas (o árboles de página en lite) y el árbol de página completo en el punto de un fallo.

NDJSON para agentes

--reporter json imprime un objeto JSON por línea en stdout, vaciando el búfer sobre la marcha. Cada línea tiene type, schemaVersion (actualmente 1) y ts.

run_start
  test_start                (per test)
    step_start / step_end   (per step, live)
  test_end                  (status, steps, failure, artifacts)
run_end                     (always the last line)

El failure de una prueba fallida indica qué paso falló y por qué: su tipo (assertion, action, script, timeout, config, engine o stopped), la expectativa, lo que se esperaba y lo que se encontró, el elemento objetivo, la URL, un breve extracto del árbol de página alrededor del elemento, errores de consola y peticiones fallidas, todo con los secretos enmascarados. failed es un veredicto sobre tu app; error significa que la prueba no pudo ejecutarse tal como está configurada.

GitHub Actions

name: e2e
on: [push, pull_request]
jobs:
  astral-test:
    runs-on: ubuntu-latest          # Google Chrome is preinstalled
    steps:
      - uses: actions/checkout@v4
      - name: Install astral-test
        run: |
          curl -fsSL https://downloads.perseusoft.tech/astral-test/latest/astral-test-x86_64-unknown-linux-gnu.tar.gz \
            | sudo tar xz -C /usr/local/bin astral-test
      - name: Start the app under test
        run: npm ci && npm start &
      - name: Run saved tests
        run: astral-test run . --collection smoke --engine cdp --reporter pretty --reporter junit --out astral-test-results
        env:
          ASTRAL_TEST_SHOP_DEMO_PASSWORD: ${{ secrets.SHOP_DEMO_PASSWORD }}
      - if: always()
        uses: actions/upload-artifact@v4
        with: { name: astral-test-results, path: astral-test-results }

En GitLab, publica astral-test-results/junit.xml en artifacts: reports: junit.