FAQ & Troubleshooting

Häufige Fragen und die Probleme, die in der ersten Woche am wahrscheinlichsten auftauchen.

← Zurück zur Übersicht · 🇬🇧 English · ← Credential Management · Deinen ersten TestCase schreiben →

Installation

Installation bricht mit 401 Unauthorized ab

Ursache: npm hat keinen gültigen License Key zum Authentifizieren gegen die Proxy-Registry.

Diagnose:

echo $CC_LICENSE_KEY

Wenn die Ausgabe leer ist, ist die Env-Var nicht gesetzt. Wiederhole den export aus Quickstart Schritt 4 (oder Schritt 3, falls du noch im selben Terminal wie beim Bootstrap-Befehl bist).

Wenn die Var gesetzt ist und Install trotzdem fehlschlägt, prüfe:

  1. Die .npmrc referenziert sie korrekt (${CC_LICENSE_KEY}, nicht $CC_LICENSE_KEY)
  2. Der Key ist exakt wie in der Welcome-E-Mail kopiert, ohne zusätzliche Leerzeichen
  3. Der Trial oder das Abo hinter dem Key ist nicht abgelaufen — siehe Lizenz-Troubleshooting

Installation bricht mit 404 Not Found ab

Ursache: der Paketname ist falsch geschrieben, oder die Proxy-Registry erkennt deine Lizenz noch nicht.

Checkliste:

  1. Ist der Paketname exakt @meintest/cc-testframework (Kleinbuchstaben meintest)?
  2. Ist die Aktivierung des License Keys aus der Welcome-E-Mail schon durch? Neue Keys können eine Minute brauchen, bis sie zur Proxy-Registry propagiert sind.

Wenn der Name korrekt ist und du trotzdem 404 bekommst, wende dich mit der zu deinem License Key gehörenden E-Mail-Adresse an support@itsbusiness.ch.

Installation bricht mit 404 oder DEPLOYMENT_NOT_FOUND ab, obwohl es vorher funktionierte

Ursache: die pm/.npmrc deines Projekts zeigt noch auf den stillgelegten Proxy-Host cc-testframework-landing.vercel.app — er wurde durch itsbusiness.vercel.app ersetzt und löst nicht mehr auf. Das betrifft nur ein Projekt, das vor dieser Umstellung gescaffoldet wurde; ein frischer Scaffold nutzt bereits den aktuellen Host.

Fix: öffne pm/.npmrc und aktualisiere beide Zeilen auf den aktuellen Host:

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

Führe danach npm install innerhalb von pm/ erneut aus.

Installation hängt ewig

Wenn npm install (innerhalb von pm/) nach “Downloading X% complete” hängt, ist das meist ein Netzwerk-Issue mit dem Windows-WSL/Devcontainer-Filesystem (langsames Small-File-I/O). Workaround, aus pm/ heraus:

# Abbrechen (Ctrl+C), aufräumen, mit Verbose-Logging nochmal
rm -rf node_modules package-lock.json
npm install --verbose

Wenn’s immer noch hängt: versuche zuerst außerhalb von WSL/Docker zu installieren, um Netzwerk/Auth zu verifizieren, dann zurück in die Container-Umgebung.

Wie verwalte oder kündige ich mein Abo?

Führe aus:

npx cc-testframework billing

Der Befehl liest deinen CC_LICENSE_KEY, fordert einen kurzlebigen, persönlichen Link zum Self-Service-Billing-Portal an, gibt ihn aus und öffnet ihn (in einem interaktiven Terminal) im Browser. Dort kannst du Zahlungsmethode ändern, Rechnungen herunterladen oder das Abo kündigen.

  • Mit --no-open wird nur die URL ausgegeben (z. B. auf einem Headless-Server), mit --json maschinenlesbar.
  • Bei einem Trial oder einem Key ohne aktives Abo meldet der Befehl, dass es nichts zu verwalten gibt — für ein Abo wende dich an sales@itsbusiness.ch.
  • Der Portal-Link ist an dein Abo gebunden und läuft schnell ab; Zahlungsdaten laufen nie durch das Framework.

Wie upgrade ich meine Trial-Version auf ein Paid-Abo?

Führe aus:

npx cc-testframework upgrade

Der Befehl liest deinen CC_LICENSE_KEY, prüft, ob die Lizenz eine upgradebare Trial ist, und gibt dann die Pricing-Seite aus (im interaktiven Terminal öffnet er sie). Den Kauf schließt du dort ab; anschließend bekommst du einen neuen Paid-Lizenzschlüssel per E-Mail — setze ihn als CC_LICENSE_KEY.

  • Mit --no-open wird nur die URL ausgegeben, mit --json maschinenlesbar.
  • Ist der Key bereits auf einem Paid-Abo, verweist der Befehl stattdessen auf npx cc-testframework billing. Perpetual- oder manuell ausgestellte Keys haben kein Self-Service-Upgrade — wende dich an sales@itsbusiness.ch.

Setup und Konfiguration

Brauche ich wirklich die drei Schichten (Controls / TestSteps / Cases)?

Für >10 TestCases mit ähnlichen UI-Patterns: ja, die Schichten zahlen sich in Wartbarkeit aus.

Für 1-3 schnelle Smoke-Tests: nein, du kannst eine einzige TC_Smoke.spec.ts schreiben und Cores Action / Check direkt aufrufen. Das Framework erzwingt die Schichten nicht, es stellt sie als produktiven Default zur Verfügung.

Kann ich page.locator() direkt im TestCase nutzen?

Technisch ja, aber das unterläuft die Architektur. Direkte page.locator()-Calls im TestCase:

  • Verstecken UI-Implementations-Details in Test-Szenarien
  • Machen UI-Refactors schmerzhaft (jeder TestCase, der das geänderte Element berührt, muss angepasst werden)
  • Unterlaufen die Lesbarkeit (“diesen CSS-Selector finden” vs “den Submit-Button im Login-Dialog klicken”)

Wenn du dich dabei häufig ertappst, ist das ein Signal, dass ein Control oder TestStep fehlt.

Mein tsconfig.json zeigt rote Errors nach dem Kopieren des Templates

Der @Apps/*-Path-Alias des Templates zeigt auf pm/2_Apps/* — du (oder ein Scaffolding-Werkzeug) ergänzt bei App-Erstellung einen Alias-Satz pro App (@App1 → pm/2_Apps/<erste-app>/References.ts, @App1Controls/* → .../1_Controls/* usw.). Du musst:

  1. Diese App-Aliase in tsconfig.json ergänzen bzw. an deinen tatsächlichen App-Ordner-Namen anpassen
  2. Sicherstellen, dass dein pm/2_Apps/<DeineApp>/-Ordner tatsächlich mit der erwarteten Unter-Struktur existiert
  3. Den TypeScript-Language-Server in der IDE neu starten nach dem Editieren von tsconfig

Gibt es einen schnelleren Weg, eine neue Web-App anzulegen, als _Skeleton von Hand umzubenennen?

Ja — npx cc-testframework create-web-app --name <DeineApp> --url <deine-app-url> kopiert _Skeleton in einen nummerierten 2_Apps/<N>_<DeineApp>/-Ordner, ersetzt den App-Namen-Platzhalter, fügt den passenden Eintrag zum apps-Objekt in GlobalConfig.ts hinzu und verdrahtet die globale References.ts-Barrel-Datei mit der Re-Export-Zeile der App — alles in einem Schritt, Project.<DeineApp>.* ist sofort importierbar. Die eine Ausnahme: Ist deine Barrel-Datei noch die nicht aktivierte References.ts.example, wird dieser letzte Schritt sanft übersprungen und stattdessen der nächste manuelle Schritt ausgegeben. Siehe Neue App hinzufügen — Scaffolde eine Web-App automatisch per CLI für die vollständige Flag-Liste und einen Beispiel-Lauf. Registrierst du stattdessen eine Windows-Desktop-App? create-desktop-app --name <DeineApp> --executable <pfad> macht dasselbe für eine Appium-Windows-AUT — siehe Scaffolde eine Desktop-App automatisch per CLI.

Wie migriere ich vom alten Git-Submodule-Setup?

Drei Schritte:

  1. .gitmodules aus dem Repo-Root entfernen.
  2. Lokales tests/1_Core/-Verzeichnis löschen — der Core kommt jetzt aus pm/node_modules via npm-Paket.
  3. Submodule-Pfad-Imports durch Package-Imports ersetzen: 
    // vorher
import { Action } from '../1_Core/Internal/Action';
// nachher
import { Action } from '@meintest/cc-testframework';

    Per grep -r "1_Core/" tests/ alle solchen Imports finden, dann via Find-Replace umstellen.

Woher weiß ich, ob eine neuere Framework-Version noch zu meiner Umgebung passt?

Jedes Release von @meintest/cc-testframework-templates veröffentlicht einen maschinenlesbaren supportMatrix in seinem manifest.json — die Playwright-, Node-, Appium- und Browser-Versionsbereiche (plus jede von einer mitgelieferten App abhängige Komponente, z. B. Outlook/Microsoft 365), gegen die dieses Release getestet und unterstützt ist. Siehe Neue App scaffolden — Kompatibilität vor dem Update prüfen für das Schema und wie du es vor der Installation liest.

Verwendung

Mein Test schlägt fehl mit “browser executable not found”

Playwright braucht die Browser-Binary lokal. Führe aus:

npx playwright install --with-deps chromium

Das --with-deps-Flag installiert OS-Level-Dependencies, die unter Linux nötig sind (macht auf macOS/Windows nichts, ist aber harmlos).

headless: false zeigt keinen Browser auf meinem Linux-Server

Auf einem headless Server (kein Display) braucht headless: false einen virtuellen Display (Xvfb) oder Remote-Display. Entweder:

  • headless: true in CI/Server-Kontexten verwenden
  • Oder DISPLAY=:99 setzen und vor Tests einen Xvfb :99-Prozess starten

Ein gängiges Pattern ist umgebungs-bedingte Headedness:

headless: process.env.HEADLESS === 'true' || !!process.env.CI,

Tests scheitern zufällig mit “element not found”

Meist eins von:

  • Die Seite ist nicht vollständig geladen → AppReady.waitForPageLoad() oder waitForNetworkIdle() nutzen
  • Ein Modal/Loading-Spinner überdeckt das Element → erst warten bis er verschwindet
  • Der Selector matched mehrere Elemente → Locator mit View-Präfix einengen ('Login', 'dialog')
  • Test war schneller als UI-Rendering → von page.locator(...).click() auf das Framework-Action.click() wechseln, das eingebaute Retry-Logik hat

Wie führe ich nur einen TestCase aus?

Aus pm/ heraus:

npx playwright test 3_Cases/TC_UserCreation.spec.ts

Oder mit --grep-Flag für Teil-Match:

npx playwright test --grep "UserCreation"

Kann ich den Browser nach einem Testlauf offen lassen, statt dass er automatisch schließt?

Ja — setze CC_DEBUG_SESSION=true (oder debugSession: true in .cc-testframework.local.json). Der erste Lauf startet die AUT dann als eigenständigen, losgelösten Prozess und beendet sich normal; jeder folgende Lauf verbindet sich mit genau dieser Instanz, statt sie neu zu starten, und macht dort weiter, wo der vorherige Lauf aufgehört hat. Siehe Persistente Debug-Session fürs Setup, die CLI (npx cc-testframework session status/close) und die Electron-Besonderheit. Aktiviere das nicht in CI — der persistente Prozess ist eine lokale Debugging-Hilfe, keine CI-Einstellung.

Wie findet das Framework den Appium-Server bei Desktop-Tests?

Für eine Desktop-AUT (Windows, via Appium) löst das Framework die Appium-Server-URL in drei Schritten auf, höchste Priorität zuerst: ein explizites appiumUrl im Eintrag dieser AUT in GlobalConfig.apps, dann die Umgebungs-Variable APPIUM_URL, dann ein plattform-basierter Default — http://localhost:4723, wenn der Test-Prozess selbst nativ auf Windows läuft, sonst http://host.docker.internal:4723 (Linux, macOS, oder ein Container, der einen separaten Windows-Host mit laufendem Appium erreicht). appiumUrl oder APPIUM_URL musst du nur setzen, wenn dein Appium-Server woanders läuft, als der Default annimmt — z.B. auf einer entfernten Maschine oder einer Device-Farm. Ist der Server nicht erreichbar, sagt dir die Fehlermeldung, welches der beiden Setups sie erkannt hat und was zuerst zu prüfen ist. Siehe API-Referenz — Sektion 14.

Mein Windows-Rechner hat einen Corporate-HTTP-Proxy — muss ich für Appium etwas konfigurieren?

Kein manueller Schritt nötig. Bevor eine Appium-/WinAppDriver-Session eröffnet wird, ergänzt das Framework den aufgelösten Appium-Hostnamen in NO_PROXY für den aktuellen Prozess, falls er dort noch nicht abgedeckt ist — Appium-/WinAppDriver-Traffic ist immer lokal (Loopback, oder die Host-Loopback-Adresse eines Containers) und sollte nie über einen Proxy laufen, der für den Rest deines Netzwerk-Traffics gedacht ist. Das rührt ausschließlich NO_PROXY an; dein bestehendes HTTP_PROXY/HTTPS_PROXY-Setup funktioniert für alles andere, was deine Tests tun, unverändert weiter.

Self-Healing

Bei einem gescheiterten Locator passiert nichts — ist Self-Healing kaputt?

Self-Healing aktiviert sich nur für einen Aufruf, bei dem über Core.Inspector.bindReference(refId) mit nicht-leerem refId ein Referenz-Screenshot gebunden ist, und unter pm/7_Assets/<uid>/<refId>.png ein passendes PNG existiert (die <uid>, die du über Core.setTestCaseId('tc_<slug>') registriert hast). Fehlt eins von beidem, läuft das Framework im normalen Locator-only-Modus, und ein gescheiterter Locator lässt den Test genau wie immer fehlschlagen. Prüfe die Konsole auf eine [SelfHealing]-Log-Zeile — sie meldet entweder einen Versuch oder den konkreten Grund, warum er übersprungen wurde (fehlendes Referenz-PNG, Budget erschöpft, keine Vision-Suggestion, etc.). Siehe Self-Healing Locators für das vollständige Setup.

Muss ich alle meine bestehenden Locators auf Core.xpath umstellen?

Nein. Core.xpath ist rein additiv — rohe Template-Literal-Strings funktionieren exakt wie vorher weiter, sie sind nur nicht für automatisches Writeback geeignet. Discovery-Modus-Heilung (einen Ersatz-Locator zur Laufzeit finden) funktioniert unabhängig davon, ob der ursprüngliche Locator getaggt war; nur der Writeback-Schritt braucht den Tag, um zu wissen, wo er den geheilten Locator in deiner Quelldatei einfügen soll.

Die Konsole loggt “Vision returned no suggestion” — was jetzt?

Das Vision-Modell hat keinen konfidenten Match zwischen Referenz-Screenshot und aktueller UI gefunden. Der ursprüngliche Locator-Fehler wird unverändert erneut geworfen, dein Test schlägt also mit seiner gewohnten Diagnose fehl — Self-Healing degradiert graceful und verdeckt einen echten Fehlschlag nie mit einem verwirrenden Sekundär-Fehler.

Woher bekomme ich einen KI-API-Key für Self-Healing / den Authoring-Agenten?

Erstelle einen in deinem eigenen Anthropic-Console-Account (BYOK — Bring Your Own Key). Das Framework proxied oder speichert diesen Key nie außerhalb deiner Maschine. Für Self-Healing Vision wird er aus der provider-agnostischen Umgebungs-Variable AI_API_KEY, einem mit npx cc-testframework set-ai-key persistierten Key, der veralteten Umgebungs-Variable ANTHROPIC_API_KEY, oder dem OS-Credential-Store gelesen, in dieser Reihenfolge geprüft — siehe Self-Healing Locators — Kosten und BYOK für die vollständige Priorität und das Kostenmodell. Der Custom-Step-Authoring-Agent (npx cc-testframework author) liest aktuell spezifisch ANTHROPIC_API_KEY, entweder als Umgebungs-Variable, per interaktivem Prompt, oder über Credential Management.

Was passiert, wenn ich dieselbe Control-Datei in meiner IDE bearbeite, während der Agent Writeback ausführt?

Hält ein Kollege (oder ein anderer Agent-Lauf) über dasselbe Koordinations-Protokoll aktiv einen Lock auf diese Datei, überspringt dieser Lauf sie vollständig — nichts wird geschrieben, nichts committet — und .self-healing-report.json hält fest, wer den Lock hält (lockedByHumans). Eine reine, unkoordinierte lokale Bearbeitung, die kein Tool gelockt hat, ist für diesen Schutz jedoch unsichtbar: committe oder stashe deine eigenen Änderungen, bevor du einen Lauf mit SELF_HEALING_WRITEBACK=true startest, und beachte die Dirty-Working-Tree-Warnung des Reporters, falls du eine siehst. Siehe Self-Healing Locators — Multi-User-Koordination für den vollständigen Lock-Lifecycle und die Env-Var SELF_HEALING_AGENT_IDENTITY.

Mein Testlauf meldet eine Heilung, aber in meiner Control-Datei hat sich nichts geändert — warum?

Writeback braucht neben einer erfolgreichen Heilung noch eine Sache: SelfHealingWritebackReporter muss für den Lauf tatsächlich registriert sein — entweder über baseConfig-Auto-Wiring (SELF_HEALING_WRITEBACK=true gesetzt, und deine Config spreadet baseConfig) oder manuell. Führe npx cc-testframework self-healing status aus — es prüft genau das, plus deinen Anthropic-API-Key, die Erreichbarkeit deines Git-Origins und aktive Koordinations-Locks, in einem Durchgang. Siehe Self-Healing Locators — Pipeline-Probleme diagnostizieren.

Wie prüfe ich, ob die Self-Healing-Pipeline korrekt eingerichtet ist?

npx cc-testframework self-healing status führt sechs Gesundheits-Prüfungen aus (Writeback-Modus, Anthropic-API-Key, Agent-Identität, Reporter-Registrierung, Git-Origin, Ref-Lock-Status) und gibt HEALTHY oder MISCONFIGURED mit dem konkreten Grund jeder gescheiterten Prüfung aus. Übergib --format json für dasselbe Ergebnis als ein einzelnes parsebares Objekt, z.B. für ein Skript, das ein Deployment von der Pipeline-Gesundheit abhängig macht. Siehe Self-Healing Locators — Pipeline-Probleme diagnostizieren.

Wie leere ich eingereihte Heilungen, die nie angewendet wurden?

npx cc-testframework self-healing clear löscht .self-healing-pending.jsonl, nach einer interaktiven Bestätigung. Übergib --force in einem nicht-interaktiven Kontext (CI, ein Skript) — ohne das endet ein nicht-interaktiver Aufruf mit Exit-Code 2, statt irgendetwas zu löschen, sodass eine unbeaufsichtigte Pipeline nie still ausstehende Heilungen verwirft. Siehe Self-Healing Locators — Die Pending-Heals-Queue leeren.

Kann ich SelfHealingWritebackReporter zusammen mit meinen eigenen Custom-Reportern nutzen?

Ja — füge ihn deinem eigenen reporter[]-Array hinzu, entweder über den benannten Import (import { SelfHealingWritebackReporter } from '@meintest/cc-testframework') oder den dedizierten Sub-Pfad-Export (@meintest/cc-testframework/Reporter/SelfHealingWritebackReporter), falls dein Setup nicht das komplette Paket-Barrel importiert. Siehe Self-Healing Locators — Den Reporter manuell registrieren.

Muss ich SELF_HEALING_WRITEBACK in jeder Session neu setzen?

Nein — npx cc-testframework config self-healing enable (plus discovery / set-identity <string> / disable / show) persistiert dieselben Einstellungen in einer projekt-lokalen .cc-testframework.local.json-Datei, sodass ein neues Terminal oder ein Shell-Wechsel dein Setup nicht verliert. Eine gesetzte Umgebungs-Variable gewinnt immer gegen die Datei, ein bestehendes export SELF_HEALING_WRITEBACK=...-Setup funktioniert also unverändert weiter. Eine Einschränkung: Verlässt sich deine playwright.config.ts auf baseConfigs automatische Reporter-Registrierung (statt den Reporter manuell zu registrieren), prüft genau diese Entscheidung weiterhin nur die Umgebungs-Variable, nicht die Config-Datei — siehe Self-Healing Locators — Setup dauerhaft speichern für die vollständige Erklärung und die zwei Wege, diese Lücke zu schließen.

Custom Steps

Wie verfolge ich Custom Steps, die noch nicht automatisiert sind?

Führe discoverCustomSteps(rootDir) aus und prüfe das Feld isNotImplemented jeder zurückgegebenen CustomStepDiscovery — true bedeutet, der Body des Steps enthält noch den “not yet automated”-Platzhalter. Kombiniere das mit validateCustomStep(discovery), um dabei gleich auch Authoring-Fehler zu erkennen (fehlende stepId, ungültiger intent usw.). Siehe Custom Steps — Custom Steps entdecken und validieren für ein direkt lauffähiges Skript — gut geeignet für einen CI-Job, der meldet, wie viele Custom Steps noch offen sind.

Mein Test-Management-Tool hat keine “Custom”-Step-Option — kann ich trotzdem einen schreiben?

Ja. Die @custom-JSDoc-Konvention setzt kein bestimmtes Authoring-Tool voraus — kopiere das TS_Custom.ts-Template in den 2_Steps-Ordner deiner App und fülle die Tags von Hand aus. Siehe Custom Steps — Einen Custom Step per Hand schreiben.

Kann das Framework meine Custom Steps automatisch implementieren, statt sie von Hand zu schreiben?

Ja — entweder rufst du runAuthoringAgent(options) direkt auf (übergib deinen eigenen Test-Root plus ein Digest des aktuellen UI-Baums deiner Anwendung), oder du führst npx cc-testframework author in einem Terminal aus, was dieses UI-Baum-Digest komplett für dich erfasst. Beide brauchen ANTHROPIC_API_KEY (BYOK, derselbe Key wie bei Self-Healing). Siehe Custom Steps — Automatisierte Implementierung und Custom Steps — Der Agent als Kommandozeilen-Befehl für das vollständige Setup und ein lauffähiges Beispiel.

Soll ich die CLI mit --test <path> oder --batch-mode --app <name> aufrufen?

Nutze standardmäßig --test <path> (Runtime-Modus) — zeig damit auf einen Test-Case, und die CLI führt ihn komplett end-to-end aus und repariert unterwegs, was bricht, Custom Steps genauso wie bereits implementierte Steps, über so viele Apps hinweg, wie der Test-Case selbst berührt. Greif zu --batch-mode --app <name>, wenn du gezielt jeden @custom-markierten Step im 2_Steps-Ordner einer App in einem einzigen Durchlauf implementieren willst, ohne überhaupt einen Test-Case auszuführen — z.B. direkt nach einer Bulk-Authoring-Session in deinem Test-Management-Tool, bevor ein Test-Case, der diese Steps referenziert, überhaupt existiert. Siehe Custom Steps — Der Agent als Kommandozeilen-Befehl für beide Modi im Vergleich.

Was passiert, wenn ein bisher funktionierender Step nach einer App-Änderung anfängt zu scheitern?

Hat dieser Step ein gebundenes Self-Healing-Referenzbild, versucht Self-Healing zuerst, den Locator zu reparieren — siehe die Self-Healing-FAQ-Einträge oben. Ist das nicht der Fall und läufst du im Runtime-Modus (--test <path>), erkennt und diagnostiziert die Schleife den Fehler trotzdem und identifiziert das voraussichtlich richtige Element — nur schreibt sie den Code des Steps noch nicht automatisch um, wie sie es bei einem noch nicht implementierten Custom Step tut. Führe denselben Test-Case mit --dry-run aus, um zu sehen, welches Element der Agent im Report identifiziert hat, und übernimm die Änderung von Hand. Siehe die Erklärungs-Box in Custom Steps — Runtime-Modus für die vollständige Erklärung.

Warum hat der Authoring-Agent einen meiner Custom Steps übersprungen?

Prüfe das Feld reason am passenden Eintrag in AuthoringResult.skipped[] — es ist immer einer von acht festen Werten (validation-failed, duplicate-step-id, already-implemented, element-not-found, agent-uncertain, agent-uncertain-underspecified, max-steps-reached, file-locked-by-human), jeweils gepaart mit einem lesbaren reasonDetail. Siehe Custom Steps (Abschnitt “Warum ein Step übersprungen wird”) für die Bedeutung jedes einzelnen und wie du ihn behebst.

Der Authoring-Agent hat einen Color-Check-Step generiert, der nicht kompiliert — was tue ich?

Das ist eine bekannte Lücke: @property color / @operator equals-Checks rufen eine Check-Methode auf, die das Framework noch nicht mitliefert. Prüfe die generierte Assertion und passe sie vorerst von Hand an — siehe die Erklärungs-Box in Custom Steps — Was generiert wird für Details. Jede andere unterstützte @property/@operator-Kombination generiert Code, der so wie er ist läuft.

Wie binde ich den Authoring-Agenten in meine CI-Pipeline ein?

Nutze die Exit-Codes der CLI: behandle 0 als Erfolg, 1 als echten Fehler, der den Build scheitern lassen sollte, und (nur Batch-Modus) 3 als Lock-Patt, das eher einen Retry verdient als einen Alarm (ein Kollege oder ein anderer CI-Job hält gerade den Schreib-Lock für jede betroffene Datei — siehe Self-Healing Locators — Multi-User-Koordination). Zeig mit --report-path auf einen Ort, den deine Pipeline danach ausliest, z.B. um die applied/skipped/error-Zahlen (Batch-Modus) oder die finalStatus/fixes[]-Aufschlüsselung (Runtime-Modus) als PR-Kommentar zu posten.

Was passiert, wenn mein --test-Pfad null Test-Dateien trifft?

Der Runtime-Modus behandelt das nicht still als Erfolg. Bestätigt Playwrights eigener JSON-Report, dass null Test-Dateien getroffen wurden — meist ein Tippfehler im Pfad —, druckt der Lauf eine Warnung, fügt dem credentialIssues-Array des Reports einen Eintrag kind: 'playwright-0-tests' hinzu (mit dem betroffenen pattern) und sendet ein playwright-0-tests-Progress-Event. finalStatus und der Exit-Code ändern sich dadurch allein nicht, weil Playwright selbst bei “0 Tests getroffen” mit Code 0 beendet — prüfe credentialIssues auch nach einem scheinbar sauberen finalStatus: 'passed'. Siehe die Erklärungs-Box in Custom Steps — Runtime-Modus.

Wie zeige ich Step-Beschreibungen in der Sprache eines Testers an?

Füg eine gleichnamige Katalog-Datei neben der Step-Datei hinzu, z.B. TS_Main.i18n.json neben TS_Main.ts, mit einem Eintrag pro Locale, geschlüsselt nach dem exportierten Namen der Step-Funktion. Das reicht für sich allein schon für jedes externe Tooling, das den Katalog statisch parst — keine Framework-Konfiguration oder Runtime-Änderung für diesen Pfad nötig; ein fehlender Katalog, oder eine fehlende Locale darin, fällt einfach auf den englischen Text zurück, der schon in deiner .ts-Datei steht. Soll auch der eigene Testlauf des Frameworks denselben Katalog rendern? Siehe die nächste Frage. Vollständige Konvention und ein lauffähiges Beispiel: Step-Description Localization.

Kann ich Step-Beschreibungen auf Deutsch (oder in einer anderen Sprache) sehen, wenn ich die Tests selbst ausführe?

Ja — setze language = 'de' in der pm/2_Apps/1_Global/GlobalConfig.ts deines Projekts, oder exportiere die Umgebungsvariable CC_TESTFRAMEWORK_LOCALE=de vor dem Lauf, und die Ausführung des Frameworks selbst — Playwrights HTML-/JSON-Reports, die Konsolen-Ausgabe und der Self-Healing-Writeback-Report — rendert dieselben .i18n.json-Kataloge live, im Moment, in dem jeder Step läuft. Steps, die weiterhin das ältere description:/logTitle:-Feld nutzen, rendern trotzdem weiterhin auf Englisch. Siehe Laufzeit-Lokalisierung für die vollständige Prioritätskette und was in jedem Fall auf Englisch bleibt.

Der Validator meldet einen Platzhalter-Mismatch in meinem Katalog — was bedeutet das?

Jeder Locale-Eintrag für einen bestimmten Step-Schlüssel muss exakt dieselben ${paramName}-Platzhalter enthalten wie das englische Quell-Template — gleiche Namen, gleiche Anzahl, nur die Formulierung und Reihenfolge darum herum darf sich unterscheiden. Ein fehlender oder zusätzlicher Platzhalter zerbricht die Ersetzung, die passiert, wenn der Text einem Tester tatsächlich angezeigt wird — deshalb behandelt der Validator das als Fehler, nicht als Warnung. Siehe Step-Description Localization — Der Platzhalter-Vertrag für ein Beispiel korrekt vs. falsch nebeneinander.

Zugangsdaten

Wo werden meine Zugangsdaten gespeichert?

Im nativen Credential-Store deines Betriebssystems — Windows Credential Manager, macOS Keychain, oder (unter Linux) der Secret Service deines Desktop-Session-Keyring-Daemons — unter dem Service-Namen cc-testframework. Nichts landet in einer .env-Datei oder deiner Shell-History, außer du setzt selbst eine Umgebungs-Variable. Siehe Credential Management für den vollständigen Mechanismus.

Wie rotiere ich einen Key oder Token?

Führe npx cc-testframework config set <name> erneut aus — das überschreibt, was zuvor gespeichert war. Es gibt keine separate “Rotieren”-Aktion.

Kann ich pro Projekt einen anderen GitHub-Token nutzen?

Ja — github-token ist standardmäßig projekt-gescoped, automatisch erkannt aus dem Git-Remote deines aktuellen Repositorys. Übergib stattdessen --global an config set, wenn du lieber einen Token für jedes Projekt nutzen willst (eine gängige Wahl für einen Solo-Entwickler). Siehe Credential Management — Projekt-Scoping.

Werden OAuth-Device-Flow-Tokens unterstützt?

Ja — die Prefixe gho_ und ghu_ werden beide für github-token akzeptiert, neben klassischen und fein-granularen Personal Access Tokens. Das Framework speichert und liest den Token nur — ihn über einen OAuth-Flow zu beziehen und zu erneuern, ist Aufgabe des Tools, das dich ursprünglich durch diesen Flow geführt hat. Läuft ein Token ab, besorg dir einen frischen und setze ihn erneut mit config set ... --stdin. Siehe Credential Management — Akzeptierte GitHub-Token-Formate.

Was passiert, wenn mein Token abläuft?

Das Framework behandelt eine abgelaufene Zugangsdaten als unbrauchbar und schlägt schnell mit einem Credential-bezogenen Fehler fehl (Exit-Code 4 bei der Authoring-Agent-CLI), statt eine zum Scheitern verurteilte Anfrage an den entfernten Dienst zu schicken — siehe Credential Management — Ablauf und Gnadenfrist. Besorg dir einen frischen Token oder Key und setze ihn erneut; das Framework selbst erneuert nie etwas in deinem Auftrag.

Was ist der Unterschied zwischen den GitHub-Token-Prefixen?

Prefix Token-Art Akzeptiert für github-token?
ghp_ Personal Access Token (classic) Ja
github_pat_ Fein-granularer Personal Access Token Ja
ghs_ GitHub-App Server-to-Server-Token Ja
gho_ OAuth-App / OAuth-Device-Flow-Access-Token Ja
ghu_ GitHub-App User-to-Server-Token Ja
ghr_ Refresh-Token Nein — nie selbst für einen API-Call oder Push nutzbar, nur um ihn gegen einen neuen Access-Token einzutauschen

Siehe Credential Management — Akzeptierte GitHub-Token-Formate für die Begründung.

Wie teile ich das Passwort-Manager-Secret mit einem neuen Team-Mitglied?

Teile es out-of-band — ein 1Password-Eintrag, eine Slack-DM, oder dein eigener Secrets-Manager, nie ein Git-Commit oder eine reine E-Mail. Dein Kollege führt dann npx cc-testframework password init --stdin aus und fügt es ein; ab diesem Zeitpunkt kann seine Maschine Einträge in PasswordManager.json entschlüsseln und hinzufügen wie jeder andere im Team. Siehe Credential Management — Weitere Team-Mitglieder onboarden.

Wie richte ich Test-Zugangsdaten in CI ein?

Setze die Umgebungs-Variable CC_PASSWORD_MANAGER_SECRET aus dem eigenen Secrets-Store deines CI-Providers (GitHub-Actions-Secrets, Vault, Azure Key Vault, …) — sie hat Vorrang vor dem Keychain, es ist also kein password init-Schritt auf dem Runner nötig. PasswordManager.json selbst ist bereits ins Repo eingecheckt und entschlüsselt, sobald die Umgebungs-Variable gesetzt ist. Siehe Credential Management — CI einrichten.

Ich bekomme eine passwordSecretKey-Deprecation-Warnung — was soll ich tun?

Verschiebe den Key aus GlobalConfig.ts in den Keychain: führe npx cc-testframework password init --secret <der-bestehende-key> aus, lösche dann die Zeile Core.Constant.passwordSecretKey = ... und committe. Bestehende PasswordManager.json-Dateien entschlüsseln weiterhin exakt wie vorher — nur woher der Key kommt, ändert sich. Siehe Credential Management — Vom veralteten passwordSecretKey migrieren.

Lizenz & Support

Wie starte ich einen Trial?

Geh auf cc-testframework.itsbusiness.ch und klick Request a Demo. Fülle das Demo-Anfrageformular aus (Name, Work-E-Mail, Firma, Use Case) und sende es ab. Du erhältst eine Bestätigung auf dem Bildschirm. Sobald deine Anfrage geprüft wurde — innerhalb eines Werktages — erhältst du per E-Mail einen personalisierten Sign-up-Link. Öffne diesen Link, fülle das Anmeldeformular aus, und innerhalb weniger Minuten kommt eine Welcome-E-Mail mit deinem 14-Tage-Trial-License-Key. Ein GitHub-Account ist zu keinem Zeitpunkt nötig. Den vollständigen Ablauf findest du in Quickstart Schritt 1.

Im Onboarding-Ablauf gibt es zwei separate E-Mails:

  1. Den personalisierten Sign-up-Link — wird nach Prüfung deiner Demo-Anfrage versendet (innerhalb eines Werktages). Falls er nach einem Werktag nicht angekommen ist, prüfe den Spam-Ordner und schreib dann an sales@itsbusiness.ch mit der E-Mail-Adresse, die du in der Demo-Anfrage angegeben hast.
  2. Die Welcome-E-Mail (mit deinem License Key) — wird innerhalb weniger Minuten nach dem Absenden des Anmeldeformulars versendet. Wenn sie nach 10 Minuten nicht angekommen ist, prüfe den Spam-Ordner und schreib dann an support@itsbusiness.ch mit der E-Mail-Adresse, die du im Anmeldeformular angegeben hast.

Das Framework gibt “License key not recognized” aus

Der CC_LICENSE_KEY-Wert entspricht keiner bekannten Lizenz. Häufige Ursachen:

  • Der Key wurde mit einem führenden oder nachgestellten Leerzeichen eingefügt — erneut sorgfältig kopieren
  • Der falsche Wert ist in der Env-Var gesetzt (prüfen mit echo $CC_LICENSE_KEY)

Wenn der Key exakt aus der Welcome-E-Mail kopiert ist und die Warnung bestehen bleibt, wende dich an support@itsbusiness.ch.

Mein Trial ist abgelaufen — was passiert mit meinen Tests?

Tests laufen weiter. Das Framework blockiert die Ausführung nach Trial-Ablauf nicht. Im Log erscheint eine Warnung: [cc-testframework license] License expired. Contact sales@itsbusiness.ch for renewal.

Wende dich an sales@itsbusiness.ch, um auf eine kostenpflichtige Lizenz umzustellen. Dein CC_LICENSE_KEY bleibt gleich — keine Projekt-Änderungen nötig.

Was bedeutet “Open Code License” genau?

Nach Lizenz-Erwerb darfst du (der Lizenznehmer):

  • Die Software in deiner eigenen Umgebung installieren, nutzen, ausführen
  • Den Source-Code für interne Nutzung und innerhalb deiner eigenen Produkte modifizieren
  • Sie in Produktiv-Umgebungen integrieren, die von oder für deine Firma betrieben werden

Du darfst nicht:

  • Die Software weitervertreiben, sublizenzieren, verkaufen, vermieten oder mit Dritten teilen
  • Sie verwenden, um ein konkurrierendes Produkt zu entwickeln
  • Copyright-Hinweise entfernen

Vollständige Bedingungen in der LICENSE-Datei, die mit jedem Release ausgeliefert wird. Für kommerzielle Lizenz-Anfragen: sales@itsbusiness.ch.

Wie bekomme ich Support?

Für technische Probleme (Installation, Test-Fehler, Konfiguration):

  1. Diese Dokumentation zuerst prüfen — die meisten Issues stehen hier
  2. Email an support@itsbusiness.ch mit:
    • Deinem Firmennamen
    • Framework-Version (pm/node_modules/@meintest/cc-testframework/package.json → version-Feld)
    • Minimaler Reproduktion (Test-Code, Log-Output)
    • Was du schon probiert hast

Für Lizenz und Abrechnung (Trial-zu-Paid-Umstellung, Verlängerungen, Rechnungen): sales@itsbusiness.ch

Für Vor-Kauf-Fragen, ob das Framework zu eurem Bedarf passt: sales@itsbusiness.ch — ihr müsst noch kein Kunde sein.

Gibt’s eine öffentliche Roadmap?

Roadmap-Details werden unter NDA während des Sales-Prozesses besprochen. Public Docs zeigen nur aktuelle Funktionen.

Unterstützt das Framework Mobile-Testing?

Aktuell zielt das Framework auf Web (Playwright-basiert) und Windows-Desktop-Testing (via Appium). Mobile (iOS/Android) ist auf der Roadmap, aber noch nicht ausgeliefert — frag deinen Sales-Kontakt nach Timing, wenn’s für euer Projekt kritisch ist.

📧 Technische Probleme: support@itsbusiness.ch · Lizenz & Abrechnung: sales@itsbusiness.ch

itsbusiness AG · Bern · Schweiz