# In der CI ausführen

> Quelle: https://astrallab.dev/de/docs/ci

`astral-test` führt die gespeicherten Tests eines Projekts aus, ohne Astral zu öffnen und ohne einen Browser mitzuliefern oder herunterzuladen. Verwenden Sie es in der CI oder in der Schleife eines Agenten, um Tests nach einer Korrektur erneut auszuführen.

## Installation

`astral-test` ist eine einzelne Binärdatei für macOS (Apple Silicon und Intel) und Linux x64, verlinkt von den [Entwickler-Downloads](https://astrallab.dev/#developer-downloads). Ein Windows-Build kann in einem Release fehlen, weil Windows [noch nicht verifiziert ist](https://astrallab.dev/de/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
```

Es braucht einen Browser, der bereits auf dem Rechner ist: Google Chrome, Chromium oder Microsoft Edge (die Engine `cdp`; `ASTRAL_CHROME` verweist auf eine bestimmte Binärdatei), einen beliebigen Browser, der bereits mit DevTools über `--cdp-url` gestartet wurde, oder Lightpanda in Ihrem `PATH` (die Engine `lite`). `astral-test doctor` meldet, was es gefunden hat und was es verwenden würde.

## Befehle

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

- Ohne `--test` oder `--collection` laufen alle gespeicherten Tests, nach ID sortiert.
- `--env` nimmt eine Umgebung aus `config.json` oder eine http(s)-URL.
- `--bail` meldet den Rest nach dem ersten Fehlschlag als übersprungen.
- Jeder Test läuft in einem frischen Browser-Kontext: Cookies und Speicher werden nicht übernommen.

### Exit-Codes

| Code | Bedeutung |
| --- | --- |
| 0   | Alle ausgewählten Tests wurden bestanden (übersprungene zählen nicht als Fehlschlag). |
| 1   | Mindestens ein Test ist fehlgeschlagen: Die App hat nicht getan, was der Test erwartet. |
| 2   | Verwendung oder Konfiguration: ungültige Argumente, Projekt oder `config.json`, unbekannter Test oder unbekannte Umgebung, nicht auflösbare Zugangsdaten. |
| 3   | Engine: kein Browser gefunden, oder er startete nicht, antwortete nicht oder blieb nicht am Leben. |

Bei mehreren Problemen gewinnt das schwerwiegendste: 3, dann 2, dann 1.

## Engines

|     | `lite` (Lightpanda) | `cdp` (Chrome, Chromium, Edge) |
| --- | --- | --- |
| Genauigkeit | DOM und JavaScript, kein Rendering und kein CSS-Layout. | Vollständig. |
| Nachweise | Seitenbäume statt Screenshots; kein Video. | Screenshots und eine Aufzeichnung als animiertes PNG. |
| Layout-Prüfungen | Als übersprungen gemeldet, nie als bestanden. | Ja, mit Viewport-Emulation. |
| Einsatz | Schnelle Abläufe ohne visuelle Abhängigkeit. | Tests, die von Layout und Screenshots abhängen. |

Standardmäßig wird `lite` verwendet, wenn Lightpanda installiert ist, sonst `cdp`.

## Zugangsdaten in der CI

`{ "env": "ASTRAL_TEST_..." }` liest eine Umgebungsvariable des Prozesses, die in der CI ein Secret ist. `{ "local": "..." }` liest `.astral/secrets.local.json`. Ein `keychain`\-Verweis ist außerhalb der App nicht verfügbar: Der Test schlägt mit einer Meldung fehl, welche Variable zu setzen ist. Geheime Werte erscheinen nie in der Ausgabe.

In der CI ist das Repository die maßgebliche Quelle: In einer geschützten Umgebung vertraut `astral-test` der `readOnly`\-Deklaration in der Testdatei, sodass eine Änderung unter `.astral/` ein Code-Review braucht.

## Ausgabe

### JUnit und Artefakte

Mit `--reporter junit` und `--out DIR` erhalten Sie:

- `junit.xml`, einen Testfall pro Test (und pro Viewport, mit einem Suffix wie `[mobile]`).
- `<testId>/report.html` und `report.json`, denselben Bericht, den die App schreibt.
- Screenshots (oder Seitenbäume bei `lite`) und den vollständigen Seitenbaum zum Zeitpunkt eines Fehlschlags.

### NDJSON für Agenten

`--reporter json` gibt ein JSON-Objekt pro Zeile auf stdout aus, laufend geleert. Jede Zeile hat `type`, `schemaVersion` (derzeit 1) und `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)
```

Das `failure` eines fehlgeschlagenen Tests sagt, welcher Schritt fehlschlug und warum: seine Art (assertion, action, script, timeout, config, engine oder stopped), die Erwartung, was erwartet wurde und was gefunden wurde, das Zielelement, die URL, einen kurzen Auszug des Seitenbaums um das Element, Konsolenfehler und fehlgeschlagene Anfragen, alles mit maskierten Geheimnissen. `failed` ist ein Urteil über Ihre App; `error` bedeutet, dass der Test nicht wie konfiguriert laufen konnte.

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

Veröffentlichen Sie bei GitLab `astral-test-results/junit.xml` unter `artifacts: reports: junit`.