Quickstart

Von der Anmeldung bis zu einem verifizierten, funktionierenden Setup in ~15 Minuten.

← Zurück zur Übersicht · 🇬🇧 English · Konzepte →

Voraussetzungen

Du brauchst:

Node.js ≥ 20 (Download)
Ein Terminal (bash, zsh, PowerShell — alle funktionieren)

💡 Wie funktioniert die Authentifizierung? Das Framework wird über eine license-brokered npm-Proxy-Registry verteilt. Statt eines npm-Logins oder eines von GitHub ausgestellten Tokens authentifizierst du dich mit dem License Key aus deiner Welcome-E-Mail — für nichts in diesem Quickstart ist ein GitHub-Account nötig.

Schritt 1 — Zugang beantragen

Der Zugang zu cc-testframework wird nach einem kurzen Prüfschritt gewährt. So stellen wir sicher, dass das Framework zum Team passt, bevor wir Repository-Zugriff und License Key übergeben.

1a — Demo-Anfrage einreichen

Geh auf cc-testframework.itsbusiness.ch und klick Request a Demo.
Fülle das Demo-Anfrageformular aus:
- Vollständiger Name
- Work-E-Mail
- Firmenname
- Use Case (kurze Beschreibung, was du testen möchtest)
Formular absenden.

Du siehst eine Bestätigung: “We will get back to you within one business day.”

1b — Persönlichen Onboarding-Link erhalten

Sobald deine Anfrage geprüft wurde, erhältst du eine E-Mail von noreply@itsbusiness.ch mit einem personalisierten Sign-up-Link (/signup?token=...). Dieser Link ist einmalig und an deine Anfrage gebunden.

1c — Anmeldeformular ausfüllen

Öffne den Link aus der E-Mail.
Fülle das Anmeldeformular aus:
- Vollständiger Name
- Work-E-Mail
- Firmenname
Formular absenden.

Innerhalb weniger Minuten erhältst du eine Welcome-E-Mail von noreply@itsbusiness.ch mit:

Einem 14-Tage-Trial-License-Key (Format: CC_LICENSE_KEY=<dein-key>)
Einem Link zurück zu diesem Quickstart

Wenn die Welcome-E-Mail nach dem Ausfüllen des Anmeldeformulars nicht innerhalb von 10 Minuten ankommt, prüfe den Spam-Ordner. Falls sie auch dort nicht ist, schreib an support@itsbusiness.ch.

Schritt 2 — Deinen License Key finden

Das einzige Credential, das du für Installation und jeden Test-Run brauchst, ist der License Key aus deiner Welcome-E-Mail (Schritt 1) — derselbe CC_LICENSE_KEY=<dein-key>-Wert, der deinen Trial aktiviert.

Öffne die Welcome-E-Mail von noreply@itsbusiness.ch.
Kopiere den Wert nach CC_LICENSE_KEY=.
Halte ihn bereit — du exportierst ihn in Schritt 3 als Umgebungs-Variable, und noch einmal, um ihn in Schritt 4 dauerhaft zu setzen.

⚠ Key-Hygiene Key niemals in Source Code commiten, niemals in Chat-Tools oder Screenshots posten, niemals per Mail teilen. Bei Verdacht auf Leak wende dich an support@itsbusiness.ch, um ihn rotieren zu lassen.

Schritt 3 — Authentifizierung bootstrappen und Projekt scaffolden

Der Scaffolder des Frameworks — @meintest/cc-testframework-templates — wird selbst über dieselbe license-brokered Proxy-Registry verteilt, das Abrufen braucht also dieselbe CC_LICENSE_KEY-Authentifizierung wie jedes andere @meintest/...-Paket. Das ist aber ein einmaliger, punktueller Bootstrap: er legt bewusst keine persistente .npmrc im äußeren Repo-Root an. Die einzige persistente .npmrc, die dieser Workflow je anlegt, liegt innerhalb von pm/ — gescaffoldet einen Moment später vom selben Befehl. Übergib Registry und Key stattdessen als Einmal-Flags an npx, statt eine Datei zu schreiben:

Linux / macOS (bash/zsh):

export CC_LICENSE_KEY=dein-key-aus-welcome-mail

npx --@meintest:registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ \
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$CC_LICENSE_KEY \
    @meintest/cc-testframework-templates init

Windows (PowerShell):

$env:CC_LICENSE_KEY="dein-key-aus-welcome-mail"

npx --@meintest:registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ `
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$env:CC_LICENSE_KEY `
    @meintest/cc-testframework-templates init

💡 Warum nicht zuerst npm install --save-dev? Den Scaffolder als Projekt-Dependency zu installieren würde eine package.json im äußeren Repo-Root hinzufügen — oder anlegen —, genau das, was dieser Workflow vermeidet. npx holt und führt ihn aus, ohne irgendetwas Persistentes außerhalb von pm/ zu installieren.

Das scaffoldet ein eigenständiges pm/-Projekt in deinem aktuellen Verzeichnis. Dein äußerer Repo-Root bekommt nichts:

pm/
├── package.json              ← @meintest/cc-testframework, @playwright/test, App-Abhängigkeiten
├── tsconfig.json
├── playwright.config.ts
├── .npmrc                    ← gescaffoldet aus .npmrc.example, dieselben zwei Registry-Zeilen wie oben
├── 2_Apps/_Skeleton/          ← Starter-Controls + TestSteps
├── 3_Cases/TC_Example.spec.ts
└── … die restlichen 9 nummerierten Ordner (von der ersten Sekunde an `.gitkeep`-versehen)

Siehe Konzepte — Die komplette Ordnerstruktur dafür, wofür jeder der 11 nummerierten Ordner — und die daneben aufgeführten Config-Dateien — gedacht ist.

Nach dem Scaffolden:

pm/2_Apps/_Skeleton/ → pm/2_Apps/<DeineApp>/ umbenennen (z.B. pm/2_Apps/MyApp/).
Path-Aliases in pm/tsconfig.json anpassen an deinen App-Ordner-Namen (<AppName>-Platzhalter ersetzen).
baseURL in pm/playwright.config.ts setzen auf deine Anwendungs-URL.

💡 Ein schnellerer Weg für Schritt 1. npx cc-testframework create-web-app --name <DeineApp> --url <deine-app-url> (ausgeführt innerhalb von pm/) kopiert _Skeleton in einen nummerierten 2_Apps/<N>_<DeineApp>/-Ordner, ersetzt den App-Namen-Platzhalter, registriert den Eintrag in GlobalConfig.ts und verdrahtet die globale References.ts-Barrel-Datei für dich — ein Befehl statt manuellem Umbenennen und Editieren. Siehe Neue App hinzufügen — Scaffolde eine Web-App automatisch per CLI für Flags und die entstehende Ordnerstruktur. Schritt 2 und 3 oben bleiben davon unberührt.

💡 Bestehendes Projekt aktualisieren? v0.25.0 verschob package.json, tsconfig.json, playwright.config.ts und .npmrc aus dem äußeren Repo-Root in pm/ selbst — siehe Konzepte — Migration auf v0.25.0 für die Vorher/Nachher-Tabelle.

Schritt 4 — License Key setzen

Der License Key aus der Welcome-E-Mail muss als Umgebungs-Variable verfügbar sein — derselbe CC_LICENSE_KEY, den du für den Einmal-Bootstrap in Schritt 3 exportiert hast, authentifiziert auch npm install (Schritt 5) und jeden Test-Run.

💡 Kein .env-File. Das Framework lädt niemals automatisch eine .env-Datei — CC_LICENSE_KEY muss eine echte Umgebungs-Variable in deinem Terminal/Betriebssystem sein (genau wie bei den Zugangsdaten aus Credential Management landet auch der License Key nie in einer Datei im Projekt).

Für die aktuelle Session

Das ist derselbe Befehl wie in Schritt 3 — warst du seither ununterbrochen im gleichen Terminal, hast du das bereits erledigt und kannst direkt zu Schritt 5 weiter.

Linux / macOS (bash/zsh):

export CC_LICENSE_KEY=dein-key-aus-welcome-mail

Windows (PowerShell):

$env:CC_LICENSE_KEY="dein-key-aus-welcome-mail"

⚠ Gilt nur im aktuellen Terminal. Diese Zuweisung lebt ausschließlich in der offenen Terminal-Sitzung — ein neues Terminal-Fenster, ein Neustart oder eine neue SSH-Sitzung kennen den Wert nicht mehr. Für alles, was über die aktuelle Sitzung hinausgeht, siehe unten.

Dauerhaft setzen

Damit CC_LICENSE_KEY auch in künftigen, neu geöffneten Terminals verfügbar ist, trägst du ihn einmalig in die persistente Umgebungs-Konfiguration deines Betriebssystems bzw. deiner Shell ein.

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("CC_LICENSE_KEY", "dein-key-aus-welcome-mail", "User")

Äquivalent als Einzeiler: setx CC_LICENSE_KEY "dein-key-aus-welcome-mail". Beide schreiben in die persistenten User-Umgebungsvariablen — das aktuell offene Terminal liest die Änderung nicht automatisch nach, dafür brauchst du ein neues Terminal-Fenster.

macOS (zsh — Standard-Shell seit macOS Catalina):

echo 'export CC_LICENSE_KEY=dein-key-aus-welcome-mail' >> ~/.zshrc
source ~/.zshrc

source ~/.zshrc lädt das Profil im aktuellen Terminal sofort neu; alternativ genügt auch ein neu geöffnetes Terminal-Fenster.

Linux (bash):

echo 'export CC_LICENSE_KEY=dein-key-aus-welcome-mail' >> ~/.bashrc
source ~/.bashrc

💡 Welche Datei ist bei mir die richtige? Anders als unter Windows gibt es unter Linux/macOS keinen einzelnen Befehl, der auf jedem System funktioniert — welche Datei deine Shell beim Start liest, hängt von Distribution, Login-Shell und individueller Konfiguration ab (~/.bashrc, ~/.bash_profile, ~/.profile, ~/.zshrc, …). Prüfe mit echo $SHELL, welche Shell aktiv ist, und trage die Zeile in die zugehörige Profildatei ein. Läuft dein Terminal nicht als Login-Shell, kann statt ~/.bashrc auch ~/.profile nötig sein.

Ersetze dein-key-aus-welcome-mail in jedem Befehl durch den tatsächlichen Key aus der Welcome-E-Mail. Der Key ist case-sensitive.

💡 Was passiert, wenn ich das überspringen? Wenn CC_LICENSE_KEY nicht gesetzt ist, schlägt npm install in Schritt 5 mit 401 Unauthorized fehl (pm/.npmrc kann den Token nicht auflösen), und — einmal installiert — laufen Tests trotzdem, geben aber eine Warnung aus: [cc-testframework license] No license key set. Provide CC_LICENSE_KEY=<your-key> in your environment. Für Schritt 5 reicht die Session-Variante oben; für jeden künftigen Test-Run in einem neuen Terminal brauchst du die dauerhafte Variante.

Schritt 5 — Pakete in `pm/` installieren

cd pm
npm install

pm/.npmrc (in Schritt 3 gescaffoldet) referenziert dieselbe CC_LICENSE_KEY-Umgebungs-Variable, die du in Schritt 4 gesetzt hast (oder für den Einmal-Bootstrap in Schritt 3 exportiert hast, falls du noch im selben Terminal bist) — das funktioniert einfach so. In einem neuen Terminal exportiere sie zuerst erneut (derselbe Wert wie in Schritt 4).

Du solltest sehen:

added 96 packages, and audited 97 packages in 5s
found 0 vulnerabilities

Das installiert @meintest/cc-testframework, @playwright/test und die Laufzeit-Abhängigkeiten der mitgelieferten Apps in pm/node_modules/.

Wenn 401 Unauthorized kommt: dein CC_LICENSE_KEY fehlt, ist ungültig, oder die Env-Var wird nicht aufgegriffen — siehe FAQ: 401 Unauthorized.

Wenn 404 Not Found kommt: die Proxy-Registry hat den Paketnamen nicht erkannt, oder deine Lizenz ist noch nicht aktiv. Prüfe, ob der Paketname exakt @meintest/cc-testframework lautet; wenn ja und es kommt trotzdem 404, schreib an support@itsbusiness.ch.

Schritt 6 — Installation verifizieren

Führe den Starter-Test aus, der mit dem Scaffold aus Schritt 3 mitkam — noch kein eigener Test-Code nötig. Aus pm/ heraus (oder erst cd pm, falls neues Terminal):

npx playwright test 3_Cases/TC_Example.spec.ts

Wenn alles richtig verkabelt ist, startet Playwright den Browser (oder läuft headless, je nach playwright.config.ts), führt die Steps aus und meldet pass/fail.

Achte zu Beginn des Test-Runs auf eine Log-Zeile, die bestätigt, dass deine Lizenz aktiv ist:

[cc-testframework license] License valid until JJJJ-MM-TT

Das bestätigt, dass das Framework deinen CC_LICENSE_KEY gelesen und verifiziert hat. Wenn stattdessen eine Warnung erscheint, siehe Lizenz-Troubleshooting weiter unten.

💡 Was steckt in TC_Example.spec.ts? Ein kurzer Ablauf, komponiert mit Project.Core.test(...) und Project.Core.Step.numberedStepBlock(...), der TestSteps aus der gescaffoldeten _Skeleton-App über das @GlobalRef-Barrel aufruft. Genau dieses Muster schreibst du gleich gegen deine eigene Anwendung — angefangen bei Neue App hinzufügen.

Ein erfolgreicher Lauf bestätigt, dass dein Setup Ende-zu-Ende verkabelt ist — License Key, Templates und Playwright selbst. Controls, TestSteps und TestCases gegen deine eigene Anwendung zu bauen, beginnt bei Neue App hinzufügen.

Nach 14 Tagen — was passiert?

Ungefähr 2 Tage vor Ablauf deines Trials erhältst du eine Erinnerungs-E-Mail von noreply@itsbusiness.ch.

Wenn die Trial-Periode endet:

Tests laufen weiter — das Framework blockiert die Ausführung nicht.
Die Lizenz-Log-Zeile wechselt zu einer Warnung: [cc-testframework license] License expired. Contact sales@itsbusiness.ch for renewal.

Für die Umstellung auf eine kostenpflichtige Lizenz wende dich an sales@itsbusiness.ch. Dein License Key bleibt gleich — keine Änderungen am Projekt-Setup nötig. Der nächste Test-Run nach der Verlängerung erkennt die neue Laufzeit automatisch.

Lizenz-Troubleshooting

Log-Ausgabe	Ursache	Lösung
`License valid until JJJJ-MM-TT`	Lizenz aktiv	—
`No license key set. Provide CC_LICENSE_KEY=<your-key> in your environment.`	`CC_LICENSE_KEY`-Env-Var nicht gesetzt oder nicht aufgegriffen	`export` aus Schritt 4 wiederholen, mit `echo $CC_LICENSE_KEY` prüfen
`License key not recognized.`	Key ungültig oder falsch eingegeben	Key aus Welcome-E-Mail erneut exakt kopieren; bei anhaltendem Problem: support@itsbusiness.ch
`License expired. Contact sales@itsbusiness.ch for renewal.`	Trial abgelaufen	sales@itsbusiness.ch kontaktieren

💡 Netzwerk-Issues Das Framework cached die Lizenz-Prüfung für 7 Tage. Wenn dein Netzwerk ausgehende Verbindungen zum Lizenz-Server blockiert, wird das letzte gecachte Ergebnis verwendet. Tests schlagen wegen vorübergehender Netzwerk-Probleme nicht fehl.

Was als Nächstes?

Konzepte — die dreischichtige Architektur verstehen, bevor du die App-Schicht ausbaust
Neue App hinzufügen — deine zu testende Anwendung registrieren und das passende Plattform-Tool wählen
API-Referenz — die kuratierten Framework-Primitives (Action, Check, Step, baseConfig, …)
FAQ — Troubleshooting für die häufigsten Setup-Stolperer

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

itsbusiness AG · Bern · Schweiz

Quickstart

Voraussetzungen

Schritt 1 — Zugang beantragen

Schritt 2 — Deinen License Key finden

Schritt 3 — Authentifizierung bootstrappen und Projekt scaffolden

Schritt 4 — License Key setzen

Für die aktuelle Session

Dauerhaft setzen

Schritt 5 — Pakete in pm/ installieren

Schritt 6 — Installation verifizieren

Nach 14 Tagen — was passiert?

Lizenz-Troubleshooting

Was als Nächstes?

Schritt 5 — Pakete in `pm/` installieren