Exécuter en CI

astral-test exécute les tests enregistrés d’un projet sans ouvrir Astral et sans embarquer ni télécharger de navigateur. Utilisez-le en CI, ou dans la boucle d’un agent pour relancer les tests après une correction.

Installation

astral-test est un binaire unique pour macOS (Apple Silicon et Intel) et Linux x64, accessible depuis les téléchargements développeur. Une version Windows peut manquer dans une release, car Windows n’est pas encore vérifié.

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

Il a besoin d’un navigateur déjà présent sur la machine : Google Chrome, Chromium ou Microsoft Edge (le moteur cdp ; ASTRAL_CHROME désigne un binaire précis), tout navigateur déjà lancé avec DevTools via --cdp-url, ou Lightpanda dans votre PATH (le moteur lite). astral-test doctor indique ce qu’il a trouvé et ce qu’il utiliserait.

Commandes

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]

Sans --test ni --collection, tous les tests enregistrés s’exécutent, triés par identifiant.
--env accepte un environnement de config.json ou une URL http(s).
--bail signale le reste comme ignoré après le premier échec.
Chaque test s’exécute dans un contexte de navigateur neuf : aucun cookie ni stockage n’est conservé.

Codes de sortie

Code	Signification
0	Tous les tests sélectionnés ont réussi (les tests ignorés ne comptent pas comme des échecs).
1	Au moins un test a échoué : l’application n’a pas fait ce que le test attend.
2	Utilisation ou configuration : arguments, projet ou `config.json` invalides, test ou environnement inconnu, identifiant impossible à résoudre.
3	Moteur : aucun navigateur trouvé, ou il n’a pas démarré, pas répondu ou pas tenu.

En cas de plusieurs problèmes, le plus grave l’emporte : 3, puis 2, puis 1.

Moteurs

	`lite` (Lightpanda)	`cdp` (Chrome, Chromium, Edge)
Fidélité	DOM et JavaScript, sans rendu ni mise en page CSS.	Complète.
Preuves	Arbres de page au lieu de captures d’écran ; pas de vidéo.	Captures d’écran et enregistrement en PNG animé.
Vérifications de la mise en page	Signalées comme ignorées, jamais comme réussies.	Oui, avec émulation du viewport.
Usage	Parcours rapides sans dépendance visuelle.	Tests dépendant de la mise en page et des captures d’écran.

Par défaut, lite est utilisé si Lightpanda est installé, sinon cdp.

Identifiants en CI

{ "env": "ASTRAL_TEST_..." } lit une variable d’environnement du processus, qui en CI est un secret. { "local": "..." } lit .astral/secrets.local.json. Une référence keychain n’est pas disponible en dehors de l’application : le test échoue avec un message indiquant quelle variable définir. Les valeurs secrètes n’apparaissent jamais dans la sortie.

En CI, le dépôt fait foi : sur un environnement protégé, astral-test se fie à la déclaration readOnly du fichier du test ; une modification sous .astral/ nécessite donc une revue de code.

Sortie

JUnit et artefacts

Avec --reporter junit et --out DIR, vous obtenez :

junit.xml, un cas de test par test (et par viewport, avec un suffixe comme [mobile]).
<testId>/report.html et report.json, le même rapport que celui écrit par l’application.
Des captures d’écran (ou des arbres de page avec lite) et l’arbre de page complet au moment d’un échec.

NDJSON pour les agents

--reporter json écrit un objet JSON par ligne sur stdout, vidé au fur et à mesure. Chaque ligne comporte type, schemaVersion (actuellement 1) et 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)

Le failure d’un test échoué indique quelle étape a échoué et pourquoi : son type (assertion, action, script, timeout, config, engine ou stopped), l’attente, ce qui était attendu et ce qui a été trouvé, l’élément cible, l’URL, un court extrait de l’arbre de page autour de l’élément, les erreurs de la console et les requêtes en échec, le tout avec les secrets masqués. failed est un verdict sur votre application ; error signifie que le test n’a pas pu s’exécuter tel que configuré.

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 }

Sur GitLab, publiez astral-test-results/junit.xml sous artifacts: reports: junit.