Skeleton-Konventionen

Die Naming-, Signatur- und XPath-Style-Regeln, die das Framework auf jeder gescaffoldeten App durchsetzt — damit ein Custom Step, ein Self-Healing-Writeback oder eine Handbearbeitung alle byte-konsistenten Code erzeugen.

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

Was diese Konventionen abdecken

Struktur — Naming, Funktionssignatur, Import-Reihenfolge, i18n-Wrapping — folgt 6 fixen Regeln, automatisch geprüft bei jeder neuen Datei. Semantik — welche Control, welches Label, welches XPath-Fragment — bleibt deine Entscheidung; die Regeln unten schränken nur die Form des Codes ein, nie was er tut.

Die 6 Regeln

Regel Art Was geprüft wird Schweregrad
R1 — i18n i18n Jedes Core.i18n.t('KEY', ...) und jedes descriptionI18n.key: 'KEY' hat einen en-Eintrag im Sibling-.i18n.json-Katalog; jede Locale-Variante hat identische Platzhalter Fatal
R2 — Naming Steps Jeder exportierte TS_* in einer Step-Datei matcht TS_<Type>_<Element>_<Action> (z.B. TS_Main_Button_Click) Fatal
R3 — Signatur Steps Jeder run-Callback von Core.defineTestStep hat pageLogName: string, _?sectionName: string als seine ersten zwei Parameter (nur TS_Main/TS_Dialog/TS_Message) Fatal
R4 — XPath-Style Controls Skeleton-Controls verbieten @id, [@data-testid], [@data-cy] — der Framework-Style ist strukturell (Text/Rolle/Label) Fatal
R5 — Sibling-Katalog i18n Jede TS_*.ts mit mindestens einem defineTestStep hat eine Sibling-TS_*.i18n.json Fatal
R6 — Import-Reihenfolge Steps Imports erscheinen in kanonischer Reihenfolge: Core → Controls* (alphabetisch) → sonstige Warning

Deine Dateien automatisch prüfen lassen

  • Pre-Commit-Hook. Nach npm install innerhalb von pm/ installiert simple-git-hooks einen .git/hooks/pre-commit-Hook, der die vom aktuellen Commit betroffenen Skeleton-Dateien validiert.
  • CI. Ein Validate Skeleton Conventions-Step läuft bei jedem Pull Request und Push.
  • CLI, bei Bedarf. Aus pm/ heraus: node node_modules/@meintest/cc-testframework-templates/bin/validate-conventions.js <root> läuft mit dem vollständigen Regelsatz gegen einen Verzeichnisbaum — manuell, oder in deine eigene CI eingebunden. Exit-Codes: 0 alles sauber, 1 mindestens eine fatale Verletzung, 2 nur Warnungen.
  • Maschinenlesbare Ausgabe. Das Flag --json liefert strukturierte Befunde für ein Test-Management-Tool oder einen anderen externen Consumer statt des menschenlesbaren Text-Reports.

Generierter Code — ein Self-Healing-Writeback, oder ein Step, den der Custom-Steps-Authoring-Agent erzeugt — wird gegen dieselben Regeln geprüft, bevor er überhaupt in deine Source-Datei geschrieben wird, sodass er ab dem Moment seiner Landung konform ist. Siehe Self-Healing Locators und Custom Steps dafür, was jeder dieser Schreibpfade tut.

Was tun bei einer Verletzung

R1 — i18n 

// Falsch — Schlüssel 'TS_Main_Login_Click' hat keinen en-Eintrag im Sibling-Katalog
Core.i18n.t('TS_Main_Login_Click', { user: 'alice' });

Fix: den Eintrag zum Sibling-.i18n.json-Katalog hinzufügen:

{
  "TS_Main_Login_Click": { "en": "click Login for ${user}", "de": "..." }
}

R2 — Naming 

// Falsch
export const clickLoginButton = ...

// Korrekt
export const TS_Main_Button_Click = Core.defineTestStep('MyApp', { ... });

R3 — Signatur 

// Falsch — run-Callback ohne pageLogName
Core.defineTestStep('MyApp', {
    descriptionI18n: { ... },
    run: (label: string) => Controls.click(label),
});

// Korrekt
Core.defineTestStep('MyApp', {
    descriptionI18n: { ... },
    run: (_pageLogName: string, _sectionName: string, label: string) => Controls.click(label),
});

R4 — XPath-Style 

// Falsch — Skeleton-Style ist strukturell, nicht id-basiert
Core.xpath`.//*[@id='login-btn']`

// Korrekt
Core.xpath`.//button[.='${label}']`

R5 — Sibling-Katalog

TS_Main.ts mit mindestens einem defineTestStep, aber ohne daneben liegende TS_Main.i18n.json, schlägt als Fatal fehl. Erstelle die Sibling-Katalog-Datei, auch wenn sie anfangs leer ist ({}).

R6 — Import-Reihenfolge 

// Falsch — Controls-Import steht vor Core
import * as ControlsButton from '../1_Controls/Button';
import * as Core from '@Core';

// Korrekt
import * as Core from '@Core';
import * as ControlsButton from '../1_Controls/Button';

Wissen, welche deiner Dateien geprüft werden

R2, R3 und R4 gelten nur, wenn der Root des Validators auf das Skeleton selbst zeigt (packages/templates/templates). Für deine eigenen Apps unter pm/2_Apps/ sind nur R1 und R5 aktiv — R2, R3 und R4 werden mit einer Info-Log-Zeile übersprungen, weil diese Apps gewachsen sind, bevor diese Konventionen existierten. Aktiviere die volle Durchsetzung für deine eigenen Apps mit strictConventions — siehe den nächsten Abschnitt.

Alle 6 Regeln auf deinen eigenen Apps durchsetzen (strictConventions)

Standardmäßig gelten R2 (Naming), R3 (Signatur) und R4 (XPath-Style) nur für das Skeleton selbst, sodass Apps, die gewachsen sind, bevor diese Konventionen existierten, oder die bereits ihren eigenen Naming- oder XPath-Style etabliert haben, unverändert weiter funktionieren.

Aktiviere dieselben Garantien für deine eigenen Apps unter 2_Apps/, wenn du willst, dass ein Self-Healing-Writeback, eine Handbearbeitung oder ein externes Tool nicht mehr über die Zeit von deinem Naming-, Signatur- und XPath-Style abdriften. Drei Wege, es zu aktivieren, geprüft in dieser Reihenfolge — der erste Treffer gewinnt:

  1. CLI-Flag. Übergib --strict beim direkten Aufruf von validate-conventions.js, z.B. aus deiner eigenen Pre-Commit-Konfiguration.
  2. Umgebungs-Variable. Setze STRICT_CONVENTIONS=true — typischerweise in deiner CI-Konfiguration, sodass jeder Pipeline-Lauf es durchsetzt, ohne eine Projekt-Datei anzufassen.
  3. GlobalConfig.ts. Füge in 2_Apps/1_Global/GlobalConfig.ts hinzu:
// In 2_Apps/1_Global/GlobalConfig.ts
export const strictConventions = true;

Das ist die persistente, im Repo committete Option — einmal gesetzt, setzt jeder Commit und jeder CI-Lauf sie durch, ohne dass anderswo ein Flag oder eine Env-Var nötig ist. Eine neu gescaffoldete App liefert diese Zeile auskommentiert in ihrer GlobalConfig.ts mit; kommentiere sie ein, wenn du bereit bist.

Ist keiner der drei Wege gesetzt, fällt das Framework auf den oben beschriebenen Standard zurück — R2, R3 und R4 bleiben Skeleton-only; R1 und R5 bleiben unabhängig davon überall aktiv.

Was sich ändert, wenn es aktiv ist

R2, R3 und R4 laufen jetzt gegen jede Datei unter 2_Apps/**, nicht nur gegen das Skeleton. In der Praxis fängt das:

  • Self-Healing-Writeback-Drift. Ein geheilter Locator kommt aus einem Vision-Aufruf und kann gelegentlich einen @id- oder [data-testid]-Style-XPath vorschlagen, obwohl der Rest deiner Control dem strukturellen Style folgt. Siehe Self-Healing Locators dafür, wie das mit strictConventions zusammenspielt.
  • Handbearbeitungs-Drift. Ein Teammitglied, das einen Step umbenennt oder eine Signatur von Hand anpasst, wird genauso geprüft, wie es eine Skeleton-Datei bereits wird.

Was das nicht fängt

strictConventions läuft zum Commit-Zeitpunkt und in der CI — es validiert Dateien, die bereits auf der Platte existieren. Es fängt keinen vom Authoring-Agent generierten Custom-Step-Code, bevor dieser Code überhaupt in deine Source-Datei geschrieben wird; das ist ein separater, früherer Checkpoint, beschrieben in Wie generierter Code verifiziert wird.

Wohin als Nächstes

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

itsbusiness AG · Bern · Schweiz