# Eseguire in CI

> Fonte: https://astrallab.dev/it/docs/ci

`astral-test` esegue i test salvati di un progetto senza aprire Astral e senza includere né scaricare un browser. Usalo in CI, o nel ciclo di un agente per rieseguire i test dopo una correzione.

## Installazione

`astral-test` è un singolo binario per macOS (Apple Silicon e Intel) e Linux x64, collegato dai [download per sviluppatori](https://astrallab.dev/#developer-downloads). Una build per Windows può mancare in una release perché Windows [non è ancora verificato](https://astrallab.dev/it/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
```

Richiede un browser già presente sulla macchina: Google Chrome, Chromium o Microsoft Edge (il motore `cdp`; `ASTRAL_CHROME` indica un binario specifico), qualsiasi browser già avviato con DevTools tramite `--cdp-url`, o Lightpanda nel tuo `PATH` (il motore `lite`). `astral-test doctor` riporta cosa ha trovato e cosa userebbe.

## Comandi

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

- Senza `--test` o `--collection`, vengono eseguiti tutti i test salvati, ordinati per id.
- `--env` accetta un ambiente di `config.json` o un URL http(s).
- `--bail` segnala il resto come saltato dopo il primo fallimento.
- Ogni test gira in un contesto di browser nuovo: nessun cookie o storage viene ereditato.

### Codici di uscita

| Codice | Significato |
| --- | --- |
| 0   | Tutti i test selezionati sono passati (quelli saltati non contano come fallimenti). |
| 1   | Almeno un test è fallito: l’app non ha fatto ciò che il test si aspetta. |
| 2   | Uso o configurazione: argomenti, progetto o `config.json` non validi, test o ambiente sconosciuto, una credenziale che non si può risolvere. |
| 3   | Motore: nessun browser trovato, oppure non si è avviato, non ha risposto o non è rimasto attivo. |

Con più problemi, vince il più grave: 3, poi 2, poi 1.

## Motori

|     | `lite` (Lightpanda) | `cdp` (Chrome, Chromium, Edge) |
| --- | --- | --- |
| Fedeltà | DOM e JavaScript, senza rendering né layout CSS. | Completa. |
| Prove | Alberi di pagina invece di screenshot; nessun video. | Screenshot e una registrazione in PNG animato. |
| Controlli del layout | Segnalati come saltati, mai superati. | Sì, con emulazione del viewport. |
| Uso | Flussi veloci senza dipendenze visive. | Test che dipendono da layout e screenshot. |

Per impostazione predefinita si usa `lite` se Lightpanda è installato, altrimenti `cdp`.

## Credenziali in CI

`{ "env": "ASTRAL_TEST_..." }` legge una variabile d’ambiente del processo, che in CI è un secret. `{ "local": "..." }` legge `.astral/secrets.local.json`. Un riferimento `keychain` non è disponibile fuori dall’app: il test fallisce con un messaggio che indica quale variabile impostare. I valori segreti non compaiono mai nell’output.

In CI il repository è la fonte di verità: in un ambiente protetto, `astral-test` si fida della dichiarazione `readOnly` nel file del test, quindi una modifica sotto `.astral/` richiede una revisione del codice.

## Output

### JUnit e artefatti

Con `--reporter junit` e `--out DIR` ottieni:

- `junit.xml`, un test case per test (e per viewport, con un suffisso come `[mobile]`).
- `<testId>/report.html` e `report.json`, lo stesso report che scrive l’app.
- Screenshot (o alberi di pagina con `lite`) e l’albero di pagina completo nel punto di un fallimento.

### NDJSON per gli agenti

`--reporter json` stampa un oggetto JSON per riga su stdout, svuotato man mano. Ogni riga ha `type`, `schemaVersion` (attualmente 1) e `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)
```

Il `failure` di un test fallito dice quale passaggio è fallito e perché: il suo tipo (assertion, action, script, timeout, config, engine o stopped), l’aspettativa, ciò che era atteso e ciò che è stato trovato, l’elemento bersaglio, l’URL, un breve estratto dell’albero di pagina attorno all’elemento, errori della console e richieste fallite, tutto con i segreti mascherati. `failed` è un verdetto sulla tua app; `error` significa che il test non ha potuto girare come configurato.

## 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 }
```

Su GitLab, pubblica `astral-test-results/junit.xml` sotto `artifacts: reports: junit`.