In der CI ausführen

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. Ein Windows-Build kann in einem Release fehlen, weil Windows noch nicht verifiziert ist.

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

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.