# Ejecutar en CI

> Fuente: https://astrallab.dev/es/docs/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](https://astrallab.dev/#developer-downloads). Puede faltar una versión de Windows en una release porque Windows [aún no está verificado](https://astrallab.dev/es/docs/platforms.md).

```bash
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

```yaml
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`.