# Exécuter en CI

> Source : https://astrallab.dev/fr/docs/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](https://astrallab.dev/#developer-downloads). Une version Windows peut manquer dans une release, car Windows [n’est pas encore vérifié](https://astrallab.dev/fr/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
```

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

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

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