Neue App scaffolden

Der schnellste Weg, eine neue zu testende Anwendung hinzuzufügen: ein CLI-Befehl, fertig.

← Zurück zur Übersicht · 🇬🇧 English · ← Konzepte · Neue App hinzufügen (vollständiger Guide) →

Web-App

npx cc-testframework create-web-app --name MyApp --url https://myapp.example

Scaffoldet die App unter 2_Apps/ und registriert sie — fertig, Project.MyApp.* ist sofort in einem TestCase nutzbar. Füge --dry-run hinzu, um vorab zu sehen, was erstellt würde, ohne etwas zu schreiben.

Desktop-App (Appium-Windows)

npx cc-testframework create-desktop-app --name MyApp --executable "C:\apps\MyApp.exe"

Electron-App

npx cc-testframework create-electron-app --name MyApp --executable-path "/opt/MyApp/MyApp"

Scaffoldet die App (Web-Controls + Electron-Start) und registriert sie — fertig. Es ist ein Playwright-/Web-Familien-Start (ein Electron-Renderer ist ein Chromium-DOM), sie nutzt also dieselben Web-Controls — der einzige Unterschied zu einer Web-App ist, dass sie ein Executable statt einer URL startet (type: 'Web', tool: 'Playwright', executablePath). Füge --dry-run hinzu, um vorab zu sehen, was erstellt würde, ohne etwas zu schreiben.

Dann einen Test schreiben

npx cc-testframework create-testcase --name MeinTest --app MyApp

Scaffoldet 3_Cases/TC_MeinTest.spec.ts mit einem Setup-Block, der MyApp startet — führe ihn mit npx playwright test 3_Cases/TC_MeinTest.spec.ts aus. Lässt du --name weg, wirst du interaktiv danach gefragt; lässt du --app weg, entsteht ein leeres TODO-Skeleton statt des Setup-Blocks.

Du schreibst Locators dabei nicht von Hand. Ist Self-Healing aktiviert (SELF_HEALING_WRITEBACK=true + ein KI-API-Key — AI_API_KEY, npx cc-testframework set-ai-key, oder der veraltete ANTHROPIC_API_KEY, siehe Self-Healing Locators — Kosten und BYOK), entdeckt das Framework die echten Locators deiner App automatisch, sobald die gescaffoldeten, generischen Controls beim ersten Lauf fehlschlagen — kein Handbearbeiten von Controls/Steps vor dem ersten Lauf nötig. Ohne aktiviertes Self-Healing heilt nichts — siehe Self-Healing Locators, um es einzuschalten.

Eine mitgelieferte Standard-App einbinden

npx cc-testframework add-app ftp-client     # die FtpClient-App einbinden
npx cc-testframework add-app --list         # den Katalog anzeigen

Statt eine leere App zu scaffolden, holt add-app eine vollständige, sofort nutzbare App, die das Framework mitliefert — email, ftp-client, os-common, os-windows, utilities — kein Naming, keine Locators zu schreiben. Jede braucht ihr eigenes Setup, bevor sie funktioniert (Zugangsdaten, OAuth, ein Appium-Windows-Host, …); der Befehl sagt dir genau, was nötig ist, und --list zeigt Beschreibung und Setup-Hinweis für jede App im Voraus. Das sind kontextfreie Tool-Apps — verdrahtet in References.ts als Project.FtpClient.* etc., kein GlobalConfig.apps-Eintrag nötig.

Eine App mit den Templates synchron halten

Wenn sich die mitgelieferten _Skeleton*-Templates verbessern, übernehmen bereits gescaffoldete Apps das nicht automatisch. Halte eine App mit folgendem Befehl auf dem aktuellen Stand:

npx cc-testframework-update-app --app MyApp

Standardmäßig läuft das als Dry-Run — es wird nichts geschrieben. Der Befehl zeigt eine Statustabelle für jede Datei unter 1_Controls//2_Steps/ der App: up-to-date, update (Template hat sich geändert, du nicht — sicher), skip (du hast bearbeitet, Template unverändert), conflict (beide geändert — braucht eine Entscheidung), new (Template hat eine Datei ergänzt, die du noch nicht hast) oder template-removed. Mit --json gibt es zusätzlich einen maschinenlesbaren Report.

npx cc-testframework-update-app --app MyApp --apply    # schreibt nur die sicheren update-/new-Dateien
npx cc-testframework-update-app --app MyApp --force    # löst zusätzlich Konflikte: sichert deine Datei als <file>.bak, schreibt dann die Template-Version

Eine Control oder ein Step, den du von Hand bearbeitet hast — oder den bereits ein Self-Healing-Writeback gepatcht hat — wird nie stillschweigend überschrieben; ein conflict braucht --force, bevor sich etwas ändert, und selbst dann bleibt dein bisheriger Inhalt als <file>.bak direkt daneben erhalten.

💡 .cc-scaffold.json. init und add-app schreiben diesen Baseline-Marker am pm/-Root — den ursprünglichen Hash jeder von ihnen gescaffoldeten Datei. Er ermöglicht es update-app, “das Template hat das geändert” von “du hast das geändert” zu unterscheiden. Committe sie in die Versionskontrolle. Apps, die vor diesem Marker gescaffoldet wurden, funktionieren weiterhin — update-app fällt für sie auf einen vorsichtigeren Vergleich zurück (jede Abweichung vom aktuellen Template zählt als conflict, wird also nie erraten).

Kompatibilität vor dem Update prüfen

Jede veröffentlichte Version von @meintest/cc-testframework-templates liefert ein manifest.json — dieselbe Datei, die init/create-*/update-app bereits einlesen, um deine Apps zu scaffolden und zu synchronisieren. Neben dem bestehenden compatibility-Pin (der passenden @meintest/cc-testframework-Versionsspanne) trägt dieses Manifest einen maschinenlesbaren supportMatrix-Block: die externen Komponenten-Versionen, gegen die diese Framework-Version getestet und unterstützt ist.

"supportMatrix": {
  "schemaVersion": 1,
  "playwright": ">=1.49.0 <2.0.0",
  "node": ">=20",
  "appium": ">=2.0.0",
  "browser": { "chromium": ">=131.0.0" },
  "outlook": "Microsoft 365 (Graph API)"
}

💡 Die Bereiche oben sind ein Beispiel aus einer veröffentlichten Version. Sie verschieben sich von Release zu Release, wenn sich die eigene Playwright-/Node-Untergrenze des Frameworks bewegt oder die Appium-/Browser-Unterstützung neu verifiziert wird — behandle nie eine Kopie aus dieser Doku als aktuell. Lies immer den supportMatrix der konkreten Version, die du installieren willst.

Feld	Bedeutung
`schemaVersion`	Der stabile Vertrag für alles, was diesen Block parst. Wird nur erhöht, wenn sich die Form des Blocks selbst ändert — Tooling kann sich sicher darauf statt auf die Framework-Version stützen.
`playwright`	Die `@playwright/test`-Versionsspanne, gegen die diese Framework-Version gebaut und getestet ist.
`node`	Die minimal benötigte Node.js-Version dieser Framework-Version.
`appium`	Die minimale Appium-Server-Hauptversion für Desktop-/Mobile-Tests. Der Appium-Server selbst läuft außerhalb dieses npm-Pakets (siehe Neue App hinzufügen für das Appium-Setup) — das ist eine Support-Aussage, keine Abhängigkeit, die dein Paketmanager installiert.
`browser.chromium`	Die Chromium-Hauptversion, die die unterstützte Playwright-Untergrenze mitbringt — relevant, wenn deine Umgebung einen bestimmten Browser-Build fest vorschreibt.
Jede weitere Komponente (z. B. `outlook`)	Erscheint nur, wenn eine mitgelieferte App sie tatsächlich unterstützt — siehe Eine mitgelieferte Standard-App einbinden oben. Fehlt eine Komponente, deckt sie aktuell keine mitgelieferte App ab — nicht, dass sie dauerhaft unsupported wäre.

Vergleiche supportMatrix mit deiner eigenen Umgebung — Node-Version, die in pm/package.json gepinnte Playwright-Version, deine Appium-Server-Version, dein Browser-Build — bevor du eine neuere Framework-Version installierst, um zu sehen, ob sie passt, ohne sie vorher zu installieren. Denselben Block kann jedes externe Tooling, das dieses Paket konsumiert (ein CI-Check, ein internes Kompatibilitäts-Skript, ein Test-Management-Tool), maschinell auswerten, statt Release-Notes zu parsen.

Um ihn zu prüfen, ohne etwas in dein Projekt zu installieren, lade nur das Paket-Tarball mit derselben Registry-Authentifizierung wie in Quickstart — Schritt 3 herunter und lies die Datei direkt daraus:

npm pack @meintest/cc-testframework-templates@<zielversion> \
    --registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ \
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$CC_LICENSE_KEY

tar -xzf meintest-cc-testframework-templates-<zielversion>.tgz package/manifest.json -O

Ersetze <zielversion> durch die Version, die du prüfen willst, oder lasse @<zielversion> für die neueste weg.

Alle Details

Manuelle GlobalConfig-Registrierung, mehr zu Electron (Lifecycle-Steps, Voraussetzungen), Mobile-Apps, oder eine App verkabeln, deren Controls du bereits von Hand geschrieben hast — alles im vollständigen Guide.

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

itsbusiness AG · Bern · Schweiz