CI-Integration

Führe deine gescaffoldeten TestCases in einer Pipeline aus und steuere Run-Mode, Self-Healing und Zugangsdaten, ohne eine Datei zu bearbeiten.

← Zurück zur Übersicht · 🇬🇧 English · ← Self-Healing Locators · Custom Steps →

Die zwei Befehle, die jede Pipeline braucht

Jeder Befehl auf dieser Seite läuft aus pm/ heraus (siehe Quickstart — Schritt 5):

cd pm
npm ci
npx playwright test

npm ci (statt npm install) ist die übliche CI-Wahl — es installiert exakt das, was pm/package-lock.json festlegt, und schlägt fehl, statt eine Abhängigkeit still zu aktualisieren. npx playwright test löst cc-testframework aus pm/node_modules auf, genau wie auf deiner eigenen Maschine — nichts CI-Spezifisches ist nötig, damit die CLI funktioniert. Jeder npx cc-testframework <subcommand>-Aufruf (set-run-mode, set-ai-key, self-healing status, …) löst genauso auf.

Die Installation authentifizieren

npm ci/npm install liest pm/.npmrc, das deinen License Key referenziert, statt ihn einzubetten:

@meintest:registry=https://itsbusiness.vercel.app/api/tmgmt/npm/
//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=${CC_LICENSE_KEY}

Setze CC_LICENSE_KEY als Secret bei deinem CI-Provider — nie als reine Workflow-Datei-Variable —, und der Install-Schritt authentifiziert genauso wie lokal. Siehe Quickstart — Schritt 3, woher der Key kommt, und FAQ — Installation bricht mit 401 Unauthorized ab, falls der Install-Schritt ihn ablehnt.

Umgebungs-Variablen, die du setzen kannst

Alle werden in dem Moment gelesen, in dem die jeweilige Datei lädt (playwright.config.ts für die ersten beiden, pm/.npmrc für die dritte) — setze sie als CI-Secrets/-Variablen, nicht als Kommandozeilen-Argumente, damit sie nie in einer Log-Zeile oder einem Prozess-Listing auftauchen.

Variable Steuert Default, falls nicht gesetzt
CC_LICENSE_KEY Install-Authentifizierung gegen die Proxy-Registry (siehe oben) (erforderlich — Install schlägt ohne fehl)
CC_RUN_MODE failfast (bricht beim ersten fehlgeschlagenen Step ab) oder failsafe (läuft über eine fehlgeschlagene Assertion hinweg weiter) — siehe Ausführen und Debuggen failfast
AI_API_KEY (oder der veraltete ANTHROPIC_API_KEY) Der BYOK-Key, den Self-Healing Vision zur Reparatur eines kaputten Locators nutzt — siehe Self-Healing — Kosten und BYOK (nicht gesetzt — der Vision-Fallback wird übersprungen, das übrige Self-Healing-Verhalten bleibt unberührt)
SELF_HEALING_WRITEBACK Ob eine erfolgreiche Heilung in deine Control-Quelldatei zurückgeschrieben wird (Apply-Modus) — siehe Self-Healing — Setup false — nur Discovery, nichts wird geschrieben
CC_PASSWORD_MANAGER_SECRET Entschlüsselt PasswordManager.json auf einem Runner ohne OS-Keychain — siehe Credential Management — CI einrichten (nicht gesetzt — das Auslesen einer gespeicherten Zugangsdaten schlägt fehl)
CC_AI_PRICE_JSON Überschreibt die eingebaute USD/Token-Rate pro Modell in der Heal-Kosten-Schätzung — siehe Self-Healing — Was ein Heal wirklich kostet Eingebaute Beispiel-Rate für das Standard-Vision-Modell

💡 Lass SELF_HEALING_WRITEBACK in einem normalen Testlauf-Job ungesetzt (oder false). Das Apply-Modus-Opt-in existiert, damit ein CI-Lauf dein Repository nie unerwartet mutiert — aktiviere es nur für einen dedizierten Job, dessen einziger Zweck es ist, Locator-Fixes zur Review vorzuschlagen (ein Diff, ein Pull Request), nicht für den Job, der deinen Merge gated. Siehe Self-Healing — Wie weit der Apply-Modus geht für die zusätzliche SELF_HEALING_WRITEBACK_MODE-Staffelung (working-tree / commit / commit-push), sobald du es aktivierst.

Präzedenz: Umgebungs-Variable, immer

Jede dieser Einstellungen löst über dieselbe Priority-Chain auf: eine Umgebungs-Variable gewinnt, wenn gesetzt, immer über eine persistierte .cc-testframework.local.json-Datei, die wiederum über den eingebauten Default gewinnt (siehe Self-Healing — Setup dauerhaft speichern, wo das vollständig dokumentiert ist). Für CI bevorzugst du die Umgebungs-Variable gegenüber den npx cc-testframework set-run-mode <mode>-/set-ai-key <key>-Settern, die in diese Datei schreiben:

  • Die Datei ist als gitignorete, per-Maschine, lokale Entwickler-Einstellung gedacht — sie reist nicht mit einem Checkout mit, ein einmaliges Setzen würde einen frischen Runner also ohnehin nicht überleben.
  • Eine über den Secrets-Store deines CI-Providers gesetzte Umgebungs-Variable bleibt komplett außerhalb des ausgecheckten Quellcodes — nichts, was versehentlich committet werden könnte.
  • Ein einmaliger Override für einen einzelnen Job (z.B. CC_RUN_MODE=failsafe nur für den nächtlichen Lauf) braucht keinen separaten Schritt, um eine Einstellung zu persistieren und später wieder zurückzunehmen.

Die set-run-mode-/set-ai-key-/config self-healing <action>-CLI-Befehle bleiben das richtige Werkzeug für die eigene Maschine eines Entwicklers — ein einmaliges Setup pro Maschine, das nicht in jeder neuen Shell wiederholt werden soll. Nutze Umgebungs-Variablen für CI, die Setter für lokale Entwicklung; beide speisen exakt dieselbe Auflösungs-Kette, es verhält sich also zwischen den beiden nichts unterschiedlich.

CI-sichere Defaults, bereits eingebaut in baseConfig

Spreadest du in deiner playwright.config.ts das baseConfig des Frameworks (siehe API-Referenz — baseConfig), reagieren drei Einstellungen bereits auf das Standard-process.env.CI-Flag, das jeder größere CI-Provider setzt (GitHub Actions, GitLab CI, CircleCI, …) — keine framework-spezifische Variable nötig:

Einstellung Außerhalb von CI Innerhalb von CI (process.env.CI truthy)
forbidOnly false true — ein versehentlich committetes test.only(...) lässt den Lauf fehlschlagen, statt den Rest der Suite still zu überspringen
retries 0 2 — ein flakiger Step bekommt zwei weitere Versuche, bevor der Test als fehlgeschlagen gemeldet wird
workers Playwrights eigener Default (parallel, an verfügbare CPUs angepasst) 1 — Tests laufen seriell, das vermeidet Ressourcen-Konkurrenz auf einem typischen CI-Runner (überschreibe mit --workers=N, falls dein Runner mehr Spielraum hat)

Diese drei sind die einzigen CI-bedingten Einstellungen in baseConfig — alles andere (das ['list','html']-Reporter-Paar, screenshot: 'on', video: 'on', trace: 'on-first-retry') verhält sich in und außerhalb von CI identisch.

Headless per Default — keine virtuelle Anzeige nötig

Ein aus dem mitgelieferten Template gescaffoldetes Projekt setzt headless überhaupt nicht, ein Web-AUT-Lauf über npx playwright test nutzt also Playwrights eigenen Default (headless) — außer du hast bewusst eine playwright.config.ts oder einen GlobalConfig.apps-Eintrag auf headless: false umgestellt, um einen Test lokal zu beobachten. Ein Default-Scaffold läuft daher unverändert auf einem Standard-Linux-CI-Runner — kein Xvfb, kein virtuelles-Display-Setup. Hast du für lokales Debugging auf headless: false umgestellt, entweder vor dem Merge zurücksetzen oder umgebungs-abhängig machen — siehe FAQ — headless: false zeigt keinen Browser auf meinem Linux-Server für das Muster.

💡 Desktop-TestCases (Appium/WinAppDriver) sind eine andere Geschichte. Sie brauchen einen erreichbaren Appium-Server mit der Zielanwendung auf genau diesem Host installiert — typischerweise ein Windows-Runner, kein Standard-Linux/macOS-CI-Image. Siehe FAQ — Wie findet das Framework den Appium-Server bei Desktop-Tests? für die URL-Auflösungs-Kette; das Einrichten dieses Windows-Hosts selbst liegt außerhalb des Umfangs dieser Seite.

Maschinenlesbare Ausgabe für deine Pipeline

Zwei Ausgaben sind dafür gebaut, von einem Skript oder Dashboard gelesen zu werden, nicht nur von einem Menschen im Terminal:

  • Die Inline-Zeilen des list-Reporters — baseConfigs Reporter-Array enthält immer ['list'] neben ['html'] (siehe API-Referenz — baseConfig), jeder Lauf gibt also pro Step eine [PASS]/[FAIL] TS_x: ...-Zeile auf stdout aus, während sie passiert — dieselben Zeilen, die du lokal siehst, nützlich für einen CI-Log-Viewer oder jedes Tool, das die Prozess-Ausgabe tailt, ohne den HTML-Report öffnen zu müssen.
  • .self-healing-report.json — geschrieben innerhalb von pm/ durch SelfHealingWritebackReporter, sobald registriert (siehe Self-Healing — Setup), egal ob tatsächlich eine Heilung stattfand. Enthält pro Heal den Token-Verbrauch und eine Kosten-Schätzung, sofern Self-Healing Vision lief — siehe Self-Healing — Die Report-Datei für das vollständige Schema. Ein CI-Job mit aktiviertem Self-Healing kann diese Datei lesen, um einen Zusammenfassungs-Kommentar zu posten oder einen Review-Schritt zu gaten.

Ein vollständiges GitHub-Actions-Beispiel 

name: e2e

on: [push, pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependencies
        working-directory: pm
        env:
          CC_LICENSE_KEY: $
        run: npm ci
      - name: Run tests
        working-directory: pm
        env:
          CC_RUN_MODE: failfast
          AI_API_KEY: $
          CC_PASSWORD_MANAGER_SECRET: $
        run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: pm/playwright-report/
          retention-days: 14

AI_API_KEY und CC_PASSWORD_MANAGER_SECRET sind nur nötig, wenn der Job tatsächlich Self-Healing Vision oder eine gespeicherte Test-Account-Zugangsdaten nutzt — lass jeweils weg, was deine Suite nicht braucht. Der upload-artifact-Schritt ist optional, aber empfohlen: baseConfig schreibt den HTML-Report immer nach pm/playwright-report/ (siehe Ausführen und Debuggen — Lies den HTML-Report), und das lokale Dateisystem eines CI-Runners verschwindet mit dem Job.

Jeder andere CI-Provider

Nichts oben ist GitHub-Actions-spezifisch. Die zwei Befehle und die Umgebungs-Variablen-Tabelle sind der gesamte Vertrag — ein GitLab-CI-.gitlab-ci.yml-Job, eine Jenkins-Pipeline-Stage oder eine CircleCI-Config reduzieren sich alle auf dieselbe Form:

export CC_LICENSE_KEY=<aus dem Secrets-Store deines Providers>
export CC_RUN_MODE=failfast
export AI_API_KEY=<aus dem Secrets-Store deines Providers>   # nur falls Self-Healing Vision läuft
cd pm
npm ci
npx playwright test

Wo es weitergeht

  • Ausführen und Debuggen — CC_RUN_MODE, der HTML-Report und das Debuggen eines lokalen Fehlschlags
  • Self-Healing Locators — Apply-Modus, writebackMode und das vollständige Schema der Report-Datei
  • Credential Management — die vollständige CC_PASSWORD_MANAGER_SECRET-/OS-Keychain-Priority-Chain
  • FAQ — Troubleshooting für Install-, Headless- und Appium-Server-Auflösungs-Probleme

📧 Fragen? Kontakt: jens.szelag@itsbusiness.ch

itsbusiness AG · Bern · Schweiz