Führen Sie Ihre Tests über CI/CD aus

Der CI/CD-Bildschirm des Studios erstellt die Pipeline-Datei für GitHub Actions oder GitLab CI. Dieser Leitfaden beschreibt, was diese Datei ausführt, die drei Orte, an denen der Job ausgeführt werden kann, Geheimnisse, das JUnit-XML und die hinterlassenen Nachweise sowie die Fehler, auf die eine CI-Maschine stößt.

Die Pipeline-Datei

Wählen Sie auf dem Bildschirm CI/CD GitHub Actions oder GitLab CI, die Browser, die Prüfungen und den Ausführungsort des Jobs aus und generieren Sie die Datei anschließend. Das Studio validiert die Datei zunächst lokal und kann sie über denselben Bildschirm committen und pushen. Über ein Terminal schreibt nexus init --ci github oder nexus init --ci gitlab dieselbe Datei.

Bei mehr als einem Browser führt GitHub einen Job pro Browser aus, mit fail-fast: false, und jeder fügt --project=<browser> hinzu. Die von Ihnen ausgewählten Prüfungen fügen --visual, --a11y, --chaos=, --loop= oder --no-retry hinzu.

Exit-Codes und JUnit-XML

nexus ci führt die von Ihnen angegebenen Tests (TC1,TC2) oder --all aus und beendet mit 0, wenn sie bestanden wurden, 1 bei einem Fehler und 2, wenn nichts ausgeführt wurde oder der Befehl falsch war. Es schreibt JUnit-XML nach evidence/ci/junit.xml; --junit=<path> schreibt es an einen anderen Ort.

Wo der Job ausgeführt wird: drei Optionen

Jede Option erfordert eine Maschine mit einer Aktivierung: Die Engine führt keine Suiten auf einer Maschine aus, die keine besitzt, und jede aktivierte Maschine zählt für Ihren Tarif (Tarife und Maschinen). Ein cloud-gehosteter Runner, runs-on: ubuntu-latest, startet für jeden Job eine neue virtuelle Maschine, sodass er nie eine behält; verwenden Sie einen persistenten eigenen Runner.

Option A: ein selbst gehosteter Runner auf der Maschine des Studios

1. Registrieren Sie auf dem Windows 11 PC oder Mini-PC, auf dem Nexus Studio installiert und aktiviert ist, einen Runner: auf GitHub unter den Settings des Repositorys, Actions, Runners, New self-hosted runner; auf GitLab unter Settings, CI/CD, Runners.
2. Wählen Sie im CI/CD-Bildschirm My machine. Die Datei lautet dann runs-on: [self-hosted] auf GitHub oder tags: [self-hosted] auf GitLab.
3. Führen Sie den Runner als der Windows-Benutzer aus, der das Studio aktiviert hat. Die Engine liest die Aktivierung aus dem Profil dieses Benutzers in .sentinel-studio\license.json, sodass ein Runner-Dienst unter einem anderen Konto keine findet.

Der Job verwendet die Aktivierung dieser Maschine: eine Aktivierung pro Maschine, bereits in Ihrem Tarif gezählt, und kein Schlüssel in der Pipeline. Verwenden Sie einen selbst gehosteten Runner nur bei einem privaten Repository, wie das Studio warnt: Bei einem öffentlichen Repository kann jeder, der einen Pull-Request öffnet, Code auf Ihrer Maschine ausführen.

Option B: ein Runner auf einem VPS, in einem Container

Ein VPS mit Ubuntu 24.04 LTS x86_64, Docker Engine und Compose v2, erreichbar über SSH-Schlüssel-Authentifizierung. Er zählt als eine Maschine Ihres Tarifs.

1. Wählen Sie auf dem CI/CD-Bildschirm Meine Maschine + Docker. Neben der Pipeline-Datei schreibt das Studio docker-compose.sentinel-runner.yml, Dockerfile.runner und die beiden Entrypoint-Skripte des Runners in den Workspace. Dockerfile.runner basiert auf mcr.microsoft.com/playwright:v1.62.1-noble.
2. Der Bildschirm zeigt die Befehle an, die in einer SSH-Sitzung auf dem VPS eingefügt werden müssen, nicht im studioeigenen Terminal. Für GitHub ruft er ein für 1 Stunde gültiges Registrierungs-Token ab und setzt REPO_URL, RUNNER_TOKEN und RUNNER_NAME; für GitLab GITLAB_URL und GITLAB_RUNNER_TOKEN. Danach:

docker compose -f docker-compose.sentinel-runner.yml up -d --build sentinel-runner
docker compose -f docker-compose.sentinel-runner.yml up -d sentinel-runner-gitlab

Die erste Zeile ist für GitHub, die zweite für GitLab. Innerhalb eines Linux-Containers identifiziert die Lizenz die Maschine über /etc/machine-id: Binden Sie die Datei des Hosts schreibgeschützt ein (/etc/machine-id:/etc/machine-id:ro) und behalten Sie den Ordner .sentinel-studio des Runner-Homeverzeichnisses auf einem Volume, damit die Aktivierung einen Rebuild übersteht. Aktivieren Sie einmalig manuell mit nexus license activate und Ihrem Schlüssel, niemals über die Pipeline-Datei.

Aktuell wird das Runner-Image auf dem VPS aus Dockerfile.runner gebaut. Das Repository verfügt noch über keine Container Registry: Ein veröffentlichtes Image in der GitHub Container Registry, genau das, welches die VPS-Laufzeitumgebung des Studios ausführt, wird mit dem nächsten Release ausgeliefert.

Option C: Der CI-Job startet eine Ausführung auf einem Host über SSH

Der Job bleibt schlank, auf einem beliebigen Runner, und die Suites laufen auf einem Host in Ihrem Besitz – mit dem Workspace und der Engine unter einem dortigen Pfad, wie es die SSH-Laufzeitumgebung des Studios erwartet. Der CI/CD-Bildschirm generiert diesen Job nicht; dies sind die Optionen, die die studioeigene SSH-Laufzeitumgebung verwendet:

ssh -o BatchMode=yes -o StrictHostKeyChecking=yes -o ConnectTimeout=8 <user>@<host> "cd <path> && node bin/nexus.js ci --all"
scp -r -o BatchMode=yes -o StrictHostKeyChecking=yes <user>@<host>:<path>/evidence ./evidence

• Nur Schlüssel-Authentifizierung. BatchMode=yes fragt niemals nach einem Passwort. Schreiben Sie den privaten Schlüssel aus einem CI-Secret in eine Datei, die nur für den Job lesbar ist, und löschen Sie sie nach Beendigung des Jobs.
• StrictHostKeyChecking=yes. Der Schlüssel des Hosts muss sich bereits in der known_hosts des Runners befinden: Hinterlegen Sie die öffentliche Schlüsselzeile des Hosts in einer CI-Variable und schreiben Sie sie vor dem ersten ssh dorthin. Setzen Sie dies niemals auf no.
• Der Exit-Code wird zurückgegeben. ssh beendet sich mit dem Code des Remote-Befehls, sodass der Schritt fehlschlägt, wenn die Suite fehlschlägt, und scp überträgt die Nachweise, einschließlich JUnit-XML, für den Artefakt-Schritt zurück.
• Der Host prüft seine eigene Lizenz und zählt als eine Maschine Ihres Tarifs.

Geheimnisse

• Speichern Sie Tokens, Webhook-URLs und private SSH-Schlüssel als CI-Secrets: auf GitHub unter Settings, Secrets and variables, Actions oder mit gh secret set <KEY>; auf GitLab als maskierte Variablen unter Settings, CI/CD, Variables. Niemals im Repository, der Pipeline-Datei oder einem Protokoll.
• Der generierte GitHub-Workflow liest nur die Integrationsschlüssel aus secrets.<KEY> und ausschließlich bei den Nexus-Schritten: TELEGRAM_*, SLACK_ENABLED, SLACK_WEBHOOK_URL, JIRA_* und den Benachrichtigungsschaltern. Der CI/CD-Bildschirm listet für jeden einen gh secret set-Befehl auf; gh fragt nach dem Wert, und es wird nichts ausgegeben.
• Der Lizenzschlüssel gehört nicht in die CI. Aktivieren Sie einen persistenten Runner einmalig manuell: Der Schlüssel wird einmal übertragen und nicht gespeichert. Falls Ihr Prozess den Schlüssel dennoch im CI-System erfordert, speichern Sie ihn ausschließlich als maskiertes Secret; nichts in der generierten Pipeline liest ihn aus.
• Geben Sie ein Secret niemals in einem Schritt aus. Die Engine bereinigt Secrets aus dem Text, den sie als Nachweis speichert, wie beispielsweise JUnit-Fehlermeldungen und Logs; sie bereinigt jedoch nicht die Konsolenausgabe des Jobs selbst, und der CI-Dienst maskiert nur Werte, die als Secrets gespeichert sind.

JUnit-XML und Nachweise als Artefakte

• GitHub lädt evidence/ als nexus-evidence hoch, ein nexus-evidence-<browser> pro Browser bei einer Matrix, unabhängig davon, ob der Durchlauf erfolgreich war oder fehlgeschlagen ist. Die JUnit-XML befindet sich darin unter evidence/ci/junit.xml.
• GitLab behält evidence/ und meldet evidence/ci/junit.xml als JUnit-Bericht, sodass fehlgeschlagene Tests im Merge Request angezeigt werden.
• Aus dem Studio kann die CI/CD-Ansicht einen GitHub-Workflow-Lauf starten und dessen Nachweise nach evidence/ci-remote/run-<id> im Workspace herunterladen.
• Wo sich die Kopie befindet. Ein Artefakt ist eine Kopie der Nachweise, einschließlich Screenshots und Logs, auf dem Speicher Ihres CI-Dienstes; bei einem gehosteten Dienst ist dies die Hardware eines Dritten. Legen Sie die Aufbewahrungsdauer für Artefakte fest, die Ihre Richtlinie erlaubt, oder behalten Sie die Nachweise auf Ihrem Runner und laden Sie nur evidence/ci/junit.xml hoch.

Fehlerbehebung

SEAT_LIMIT auf einem Cloud-gehosteten oder kurzlebigen Runner

Jede neue virtuelle Maschine gilt für die Lizenz als neue Maschine, daher würde ein kurzlebiger Runner für jeden Job eine Aktivierung benötigen. Sobald jede Maschine Ihres Tarifs aktiv ist, wird die Aktivierung mit SEAT_LIMIT verweigert: „All machines on your plan are in use. Deactivate one in your account.“ Verwenden Sie einen persistenten, selbst gehosteten Runner (Option A oder B) und deaktivieren Sie Maschinen, die Sie nicht mehr verwenden, unter License & machines in Ihrem Konto (mehr zu SEAT_LIMIT).

Der Runner war tagelang offline

Die Lizenz einer Maschine muss mindestens alle 7 Tage validiert werden. Danach erhält sie 4 weitere Tage mit einem Hinweis und wechselt dann in den schreibgeschützten Modus: Test-Suites werden erst wieder ausgeführt, wenn eine Überprüfung erfolgreich ist, und die Nachweise bleiben lesbar. Auf einem Runner, der wieder online ist, führt nexus license renew eine erneute Überprüfung durch (Offline-Arbeiten).

„no /etc/machine-id“ in einem Container

Der Container hat keine Machine-ID, die von der Lizenz gelesen werden kann. Binden Sie die des Hosts ein: -v /etc/machine-id:/etc/machine-id:ro oder dieselbe Zeile unter volumes: in der Compose-Datei.

Der Job wird mit Code 2 beendet

Es wurde nichts ausgeführt: Kein Test stimmte mit den IDs überein oder der Befehl war falsch. Überprüfen Sie die an nexus ci übergebenen IDs in tc_ids auf GitHub oder TC_IDS auf GitLab.

Host-Schlüssel-Verifizierung fehlgeschlagen

StrictHostKeyChecking=yes hat einen Host abgelehnt, der nicht in known_hosts enthalten ist oder dessen Schlüssel geändert wurde. Fügen Sie den Schlüssel des Hosts aus einer vertrauenswürdigen Quelle hinzu, nachdem Sie dessen Fingerabdruck auf dem Host selbst überprüft haben. Deaktivieren Sie die Überprüfung nicht.