document-feature

name	document-feature
description	Create E2E tests with screenshots and build step-by-step documentation for the public website
argument-hint	<feature-name>

Feature dokumentieren mit E2E Tests und Screenshots

Erstelle E2E-Tests, Screenshots und eine Schritt-für-Schritt-Anleitung für ein Feature auf der PublicWeb-Website.

Feature: $ARGUMENTS

---

Übersicht

Dieser Skill automatisiert den gesamten Dokumentations-Workflow für ein Feature:

1. E2E-Tests erstellen die Screenshots für jeden Schritt erzeugen
2. Tests im Docker-Container ausführen
3. Schritt-für-Schritt-Anleitung (DE + EN) auf der PublicWeb-Website erstellen/aktualisieren
4. Optional: Feature als Highlight auf der Landing Page aufnehmen

---

Schritt 1: Feature identifizieren

1. Falls $ARGUMENTS leer ist, frage den User welches Feature dokumentiert werden soll.
2. Identifiziere die relevanten UI-Seiten und Workflows des Features:
   • Lies den bestehenden Code unter src/ReadyStackGo.WebUi/src/pages/ und src/ReadyStackGo.WebUi/src/components/
   • Verstehe den User-Flow: Welche Schritte durchläuft ein User?
   • Identifiziere die relevanten Routes/URLs
3. Prüfe ob bereits Dokumentation existiert:
   • PublicWeb: src/ReadyStackGo.PublicWeb/src/content/docs/de/docs/ und en/docs/
   • Interne Docs: docs/
4. Prüfe ob bereits E2E-Tests existieren: src/ReadyStackGo.WebUi/e2e/

Schritt 2: Highlight-Feature abfragen

Frage den User mit AskUserQuestion:

Soll dieses Feature als Highlight auf der Landing Page aufgenommen werden?
Highlight-Features erscheinen prominent in der Feature-Übersicht auf der Startseite.

Optionen:
1. Nein, nur Dokumentation erstellen (Recommended)
2. Ja, als Highlight-Feature auf der Landing Page aufnehmen

Falls Highlight: Frage nach Titel (kurz, DE + EN), Beschreibung (1 Satz, DE + EN) und ob ein Badge (z.B. "NEW") angezeigt werden soll.

Schritt 3: E2E-Tests erstellen

Erstelle eine neue Test-Datei unter src/ReadyStackGo.WebUi/e2e/<feature-name>.spec.ts.

Muster folgen (Referenz: e2e/cicd-settings.spec.ts):

import { test, expect } from '@playwright/test';
import * as path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const SCREENSHOT_DIR = path.join(__dirname, '..', '..', 'ReadyStackGo.PublicWeb', 'public', 'images', 'docs');

test.describe('<Feature Name>', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
    await page.fill('input[type="text"]', 'admin');
    await page.fill('input[type="password"]', 'Admin1234');
    await page.click('button[type="submit"]');
    await page.waitForURL(/\/(dashboard)?$/, { timeout: 10000 });
  });

  test('should <step description>', async ({ page }) => {
    // Navigation + Assertions
    await page.goto('/target-page');
    await page.waitForLoadState('networkidle');

    // Screenshot an jedem wichtigen Schritt
    await page.screenshot({
      path: path.join(SCREENSHOT_DIR, '<feature>-01-<beschreibung>.png'),
      fullPage: false
    });
  });
});

Screenshot-Konventionen:

• Pfad: src/ReadyStackGo.PublicWeb/public/images/docs/
• Namensformat: <feature>-<##>-<beschreibung>.png (z.B. cicd-01-settings-nav.png)
• Fortlaufende Nummerierung für die Schritt-Reihenfolge
• fullPage: false verwenden (nur Viewport)
• Screenshots in den Tests machen, die den Happy-Path / Hauptworkflow abbilden

Test-Anforderungen:

• Nicht nur Happy-Path! Teste auch:
  • Leere Zustände (keine Daten vorhanden)
  • Validierung (Pflichtfelder, ungültige Eingaben)
  • Cancel/Abbrechen-Flows
  • Fehlerfälle
• Nutze getByRole() und getByText({ exact: true }) statt getByText() um Strict-Mode-Fehler zu vermeiden
• Bei Texten die als Substring in anderen Elementen vorkommen: { exact: true } verwenden
• Bei Buttons in Tabellenzeilen: row.getByRole('button', { name: '...' }) statt row.getByText('...')

Schritt 4: E2E-Tests ausführen

Container starten (falls nicht laufend):

docker compose up -d --build

Wizard durchlaufen (bei frischem Container):

curl -sf -X POST http://localhost:8080/api/wizard/admin \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin1234"}'

curl -sf -X POST http://localhost:8080/api/wizard/organization \
  -H "Content-Type: application/json" \
  -d '{"id":"e2e-test-org","name":"E2E Test Organization"}'

curl -sf -X POST http://localhost:8080/api/wizard/environment \
  -H "Content-Type: application/json" \
  -d '{"name":"default","socketPath":"/var/run/docker.sock"}'

curl -sf -X POST http://localhost:8080/api/wizard/install \
  -H "Content-Type: application/json" -d '{}'

Tests ausführen:

Erstelle eine temporäre Playwright-Config die auf den Container zeigt:

// playwright.temp.config.ts (nach Tests löschen!)
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
  testDir: './e2e',
  fullyParallel: false,
  workers: 1,
  reporter: 'list',
  timeout: 60 * 1000,
  expect: { timeout: 10 * 1000 },
  use: {
    baseURL: 'http://localhost:8080',
    actionTimeout: 15 * 1000,
    navigationTimeout: 30 * 1000,
  },
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
});

cd src/ReadyStackGo.WebUi
npx playwright test <feature-name> --config=playwright.temp.config.ts --reporter=list

Bei Fehlern:

• Locator-Fehler (strict mode) → Spezifischere Selektoren verwenden
• Timing-Fehler → waitForLoadState('networkidle') oder waitForTimeout() einfügen
• Container mit frischen Volumes neu starten wenn Test-Daten kollidieren:

  docker compose down -v && docker compose up -d
  

  Dann Wizard erneut durchlaufen.

Nach erfolgreichen Tests:

• Prüfe dass alle Screenshots in src/ReadyStackGo.PublicWeb/public/images/docs/ erzeugt wurden
• Lösche die temporäre Config playwright.temp.config.ts

Schritt 5: Dokumentation auf PublicWeb erstellen

Datei anlegen oder aktualisieren:

• Deutsch: src/ReadyStackGo.PublicWeb/src/content/docs/de/docs/<feature-name>.md
• Englisch: src/ReadyStackGo.PublicWeb/src/content/docs/en/docs/<feature-name>.md

Dokumentations-Struktur (Referenz: ci-cd-integration.md):

---
title: <Feature-Titel>
description: <Kurzbeschreibung>
---

<Einleitungsparagraph: Was macht das Feature, wann braucht man es?>

## Übersicht / Overview

<Tabelle oder kurze Auflistung der Use Cases>

---

## Schritt für Schritt: <Hauptworkflow> / Step by Step: <Main Workflow>

### Schritt 1: <Aktion>

<Kurze Anleitung was zu tun ist>

![<Alt-Text>](/images/docs/<feature>-01-<beschreibung>.png)

---

### Schritt 2: <Aktion>

<Anleitung mit Details>

![<Alt-Text>](/images/docs/<feature>-02-<beschreibung>.png)

:::tip[<Tipp-Titel>]
<Hilfreicher Hinweis>
:::

---

(... weitere Schritte ...)

## <Zusätzliche Sektionen je nach Feature>

<z.B. API-Parameter, Konfiguration, Sicherheitshinweise>

---

## Fehlerbehandlung / Error Handling

<HTTP-Status-Tabelle oder häufige Fehler und deren Lösung>

Regeln:

• Deutsch: Volle Dokumentation in Deutsch mit englischen Fachbegriffen
• Englisch: Vollständige Übersetzung, gleiche Struktur
• Screenshots: Gleiche Bilder für beide Sprachen, unterschiedliche Alt-Texte
• Starlight-Features nutzen: :::tip, :::note, :::caution Callouts
• Parameter-Tabellen für API-Endpunkte: Feld, Typ, Pflicht/Required, Beschreibung

Docs-Index aktualisieren:

Falls die Datei neu ist, prüfe ob sie in die Sidebar-Navigation aufgenommen werden muss:

• src/ReadyStackGo.PublicWeb/src/content/docs/de/docs/index.md
• src/ReadyStackGo.PublicWeb/src/content/docs/en/docs/index.md

Schritt 6: Landing Page erweitern (nur bei Highlight-Feature)

Nur wenn in Schritt 2 als Highlight bestätigt wurde!

6a: Translations erweitern

Datei: src/ReadyStackGo.PublicWeb/src/i18n/translations.ts

Füge neue Translation Keys hinzu (in beide Sprachen):

// DE
'features.<feature>.title': '<Titel auf Deutsch>',
'features.<feature>.desc': '<Beschreibung auf Deutsch (1 Satz)>',

// EN
'features.<feature>.title': '<Title in English>',
'features.<feature>.desc': '<Description in English (1 sentence)>',

6b: Feature-Kachel in Features.astro hinzufügen

Datei: src/ReadyStackGo.PublicWeb/src/components/Features.astro

Füge das Feature zum highlightedFeatures Array hinzu:

{
    icon: `<SVG path data>`,
    titleKey: 'features.<feature>.title' as const,
    descKey: 'features.<feature>.desc' as const,
    badge: 'NEW',  // Optional
    link: `/${lang}/docs/<feature-name>`,
},

SVG Icons: Verwende Heroicons (https://heroicons.com/) – nur den <path> Tag kopieren. Stil: outline, 24x24.

6c: TypeScript-Typen prüfen

Die Translation Keys müssen im Translations Type in translations.ts vorhanden sein, sonst compiliert die Website nicht. Prüfe mit:

cd src/ReadyStackGo.PublicWeb && npm run build

Schritt 7: Commit und Push

git add <alle neuen/geänderten Dateien>
git commit -m "<Aussagekräftige Commit-Message>"
git push

Commit-Regeln (siehe CLAUDE.md):

• Englische Commit-Messages
• Kein Footer (kein Co-Authored-By, kein Generated with Claude Code)

Checkliste

Vor dem Abschluss prüfen:

• E2E-Tests laufen alle grün (gegen Container auf Port 8080)
• Screenshots wurden erzeugt in public/images/docs/<feature>-*.png
• Deutsche Dokumentation erstellt/aktualisiert
• Englische Dokumentation erstellt/aktualisiert (gleiche Struktur)
• Screenshots in beiden Sprach-Versionen referenziert
• Docs-Index-Seiten aktualisiert (falls neue Datei)
• (Falls Highlight) Translation Keys in DE + EN hinzugefügt
• (Falls Highlight) Feature-Kachel in Features.astro hinzugefügt
• Temporäre Playwright-Config gelöscht
• Committed und gepusht