Führen Sie Ihre Tests über CI/CD aus
Die CI/CD-Ansicht von Studio erstellt die Pipeline-Datei für GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI oder Bitbucket. Dieser Leitfaden erklärt, was diese Datei ausführt, die zentrale Gesamtprüfung, die optionale Bereitstellung nach einem erfolgreichen Lauf, die drei möglichen Ausführungsorte des Jobs, Secrets, die erzeugten JUnit-XML-Dateien und Nachweise sowie Fehler, die auf einem CI-Rechner auftreten können.
Zuletzt aktualisiert:
Vom Nexus StudioQA-Team, Verdict System LLC.
Die Pipeline-Datei
Wählen Sie in der CI/CD-Ansicht den Anbieter, die Browser, die Prüfungen und den Ausführungsort des Jobs aus und starten Sie dann die Generierung. Studio validiert die Datei zunächst lokal und kann sie direkt aus derselben Ansicht committen und pushen. Im Terminal erstellt nexus init --ci github oder nexus init --ci gitlab dieselbe Datei.
| Teil | GitHub Actions | GitLab CI |
|---|---|---|
| Datei | .github/workflows/nexus-ci.yml | .gitlab-ci.yml |
| Auslöser | Pull Requests, Pushes auf main oder master und eine manuelle Ausführung (workflow_dispatch) mit einer tc_ids-Eingabe. Bei aktivierter nächtlicher Regression ein schedule-Cron in UTC, standardmäßig 0 6 * * *. | Die Pipeline-Regeln Ihres Projekts. Die Datei enthält keinen Zeitplan: Fügen Sie für einen nächtlichen Lauf einen Pipeline-Zeitplan in GitLab hinzu. |
| Runner | runs-on: ubuntu-latest für einen in der Cloud gehosteten Runner, im Image mcr.microsoft.com/playwright:v1.62.1-noble; runs-on: [self-hosted] für Ihren eigenen | Das Image mcr.microsoft.com/playwright:v1.62.1-noble; tags: [self-hosted] für Ihren eigenen Runner |
| Schritte | actions/checkout@v4; actions/setup-node@v4 mit Node.js 22, nur auf Ihrem eigenen Rechner ohne Docker (das Image enthält bereits Node.js und die Systembibliotheken); npm ci; npx playwright install, auf demselben Rechner mit --with-deps; node bin/nexus.js ci --all oder die ausgewählten Test-IDs | npm ci; node bin/nexus.js ci mit der Variablen TC_IDS oder --all. Das Image enthält bereits die Browser. |
| Artefakte | actions/upload-artifact@v4, if: always(), Name nexus-evidence, Pfad evidence/ | artifacts: when: always, reports: junit: evidence/ci/junit.xml, paths: evidence/ |
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.
Jenkins, Azure DevOps, CircleCI und Bitbucket
Die anderen vier Anbieter erhalten denselben Befehl, node bin/nexus.js ci --all, einen Lauf pro Browser, die anbietereigene JUnit-Veröffentlichung und evidence/ als Artefakt, auch wenn der Lauf fehlschlägt. Jenkins, CircleCI und Bitbucket laufen im Image mcr.microsoft.com/playwright:v1.62.1-noble; Azure DevOps läuft auf einem ubuntu-latest-Agenten und installiert zuerst die Browser.
| Anbieter | Datei | Fehlgeschlagene Tests erscheinen unter |
|---|---|---|
| Jenkins | Jenkinsfile | Der Seite „Testergebnis“ des Builds |
| Azure DevOps | azure-pipelines.yml | Dem Reiter „Tests“ des Laufs sowie unter „Testpläne“, „Läufe“ |
| CircleCI | .circleci/config.yml | Dem Reiter „Tests“ des Jobs |
| Bitbucket | bitbucket-pipelines.yml | Dem Reiter „Tests“ der Pipeline |
Diese vier lesen Secrets aus ihrem eigenen Speicher. Studio listet die dort hinzuzufügenden Schlüssel ohne Werte auf und schreibt nicht in diesen Speicher. Die Gesamtprüfung und der unten beschriebene Bereitstellungsjob sind für GitHub Actions und GitLab CI vorgesehen.
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.
Eine Gesamtprüfung für die gesamte Matrix
Bei mehreren Browsern zeigt GitHub eine Prüfung pro Browser an. Der generierte Workflow fügt einen Job namens Nexus verdict hinzu, der nach allen anderen läuft, auch wenn einer fehlgeschlagen ist, und nur dann grün ist, wenn alle Browser bestanden haben. Legen Sie in Ihrer Branch-Schutzregel diese eine Prüfung als erforderlich fest, statt einer Prüfung pro Browser.
Bereitstellung nach erfolgreichem Lauf
Aktivieren Sie in der CI/CD-Ansicht Bereitstellung nach erfolgreichem Lauf, um einen Bereitstellungsjob hinzuzufügen. Er läuft nur bei einem Push auf den Hauptbranch und nur nach erfolgreichem Abschluss der Testsuite: Bei einem fehlgeschlagenen Lauf wird er übersprungen. Auf GitHub wartet er auf die Gesamtprüfung und läuft in der Umgebung production, sodass die Schutzregeln dieser Umgebung gelten.
| Ziel | Funktionsumfang | Gelesene Secrets |
|---|---|---|
| Bereitstellungs-Hook (GitHub, GitLab) | Sendet eine POST-Anfrage an eine Bereitstellungs-URL Ihres Hostinganbieters | NEXUS_DEPLOY_HOOK |
| Cloudflare (GitHub) | wrangler deploy | CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID |
| Vercel (GitHub) | vercel pull, build und deploy --prebuilt --prod | VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID |
| SSH und Docker Compose (GitHub) | docker compose pull und up -d in einem Ordner auf Ihrem Server | DEPLOY_SSH_HOST, DEPLOY_SSH_USER, DEPLOY_SSH_KEY, DEPLOY_SSH_KNOWN_HOSTS, DEPLOY_SSH_DIR |
- Secrets nur über ihren Namen. Jedes Secret wird dem Schritt als Umgebungsvariable übergeben, niemals im Skripttext, und der Job prüft jedes vorab: Fehlt ein Secret, schlägt er unter Angabe des Secret-Namens fehl.
- SSH prüft den Serverschlüssel. Der Hostschlüssel stammt aus
DEPLOY_SSH_KNOWN_HOSTS; die Hostschlüsselprüfung wird niemals deaktiviert. - Minimale Berechtigungen. Die Jobs für den Bereitstellungs-Hook und SSH erhalten keine Repository-Berechtigungen; Cloudflare und Vercel erhalten Lesezugriff, um den Code auszuchecken.
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
- Registrieren Sie auf dem Windows 11 PC oder Mini-PC, auf dem Nexus StudioQA 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.
- Wählen Sie im CI/CD-Bildschirm My machine. Die Datei lautet dann
runs-on: [self-hosted]auf GitHub odertags: [self-hosted]auf GitLab. - 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
.nexus-studioqa\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.
- Wählen Sie auf dem CI/CD-Bildschirm Meine Maschine + Docker. Neben der Pipeline-Datei schreibt das Studio
docker-compose.nexus-studioqa-runner.yml,Dockerfile.runnerund die beiden Entrypoint-Skripte des Runners in den Workspace.Dockerfile.runnerbasiert aufmcr.microsoft.com/playwright:v1.62.1-noble. - 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_TOKENundRUNNER_NAME; für GitLabGITLAB_URLundGITLAB_RUNNER_TOKEN. Danach:
docker compose -f docker-compose.nexus-studioqa-runner.yml up -d --build nexus-studioqa-runner
docker compose -f docker-compose.nexus-studioqa-runner.yml up -d nexus-studioqa-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 .nexus-studioqa 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=yesfragt 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 derknown_hostsdes Runners befinden: Hinterlegen Sie die öffentliche Schlüsselzeile des Hosts in einer CI-Variable und schreiben Sie sie vor dem erstensshdorthin. Setzen Sie dies niemals aufno.- Der Exit-Code wird zurückgegeben.
sshbeendet sich mit dem Code des Remote-Befehls, sodass der Schritt fehlschlägt, wenn die Suite fehlschlägt, undscpü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 und das CI-Token aus
secrets.<KEY>, und zwar nur in den Nexus-Schritten: die Schlüssel für Telegram, Slack, Teams, Jira, Azure Boards und GitHub Issues, die Benachrichtigungsschalter undNEXUS_CI_LICENSE. Die CI/CD-Ansicht richtet sie für Sie ein: über die GitHub-API, wenn Sie einGITHUB_CI_TOKENin den Einstellungen gespeichert haben, andernfalls mitgh secret set. Nichts wird ausgegeben. - Der Lizenzschlüssel gehört nicht in die CI. Ein gehosteter Runner verwendet das separate CI-Token
NEXUS_CI_LICENSEaus dem Kontoportal: Speichern Sie es ausschließlich als maskiertes Geheimnis. Ein dauerhaft eingerichteter Runner kann stattdessen einmalig von Hand aktiviert werden: Der Schlüssel wird einmal gesendet und nicht gespeichert. - 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/alsnexus-evidencehoch, einnexus-evidence-<browser>pro Browser bei einer Matrix, unabhängig davon, ob der Durchlauf erfolgreich war oder fehlgeschlagen ist. Die JUnit-XML befindet sich darin unterevidence/ci/junit.xml. - GitLab behält
evidence/und meldetevidence/ci/junit.xmlals 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.xmlhoch.
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.