Eseguire in 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. Una build per Windows può mancare in una release perché Windows non è ancora verificato.

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

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.