Manual-Screenshot-System

Automatisierte mobile Handbuch-Screenshots¶

Das Endnutzer-Handbuch enthält reproduzierbare Screenshots der gebauten Steady-Oberfläche. Ein eigener Playwright-Runner startet die Browserfassung in einer festen mobilen Darstellung, durchläuft ausgewählte Ansichten auf Deutsch und Englisch und schreibt die erzeugten PNG-Dateien direkt in die veröffentlichten Handbuch-Verzeichnisse.

Ziel und Aussagekraft¶

Der Lauf prüft und dokumentiert gemeinsam:

ob der spezielle Vite-Handbuch-Build startet,
ob die zentralen Ansichten und Konfigurationsdialoge in Chromium erreichbar sind,
ob deutsche und englische Screenshots mit identischen Dateinamen entstehen,
ob die lokalisierten Dokumentationsmarkierungen erzeugt werden,
ob die Bildpfade im Endnutzer-Handbuch vorhanden bleiben,
und ob die Dokumentationsprüfungen nach der Erzeugung weiterhin bestehen.

Browsernachweis, kein Android-Nachweis

Der Lauf zeigt die React-Oberfläche in einem mobilen Chromium-Viewport. Er beweist weder einen erfolgreichen nativen Android-Build noch korrektes Verhalten von SQLite, Android Keystore, Gerätesperre, Benachrichtigungen oder nativen Systemdialogen.

Aufbau¶

flowchart LR
  A[Manueller Start oder Request-Zähler] --> B[GitHub Actions]
  B --> C[npm ci]
  C --> D[isoliertes Playwright-Paket und Chromium]
  D --> E[Vite-Build im Modus manual]
  E --> F[synthetische IndexedDB-Daten]
  F --> G[mobile Durchläufe DE und EN]
  G --> H[temporäre Callout-Ebene]
  H --> I[28 PNG-Dateien]
  I --> J[docs:check]
  J --> K[nur Screenshot-Verzeichnisse stagen]
  K --> L[Bot-Commit bei Änderungen]

Baustein	Aufgabe
`npm run build:manual`	baut Vite im Modus `manual`
`playwright.manual.config.js`	definiert Browser, Viewport, Zeitlimits und lokalen Preview-Server
`src/main.jsx`	lädt die Capture-Vorbereitung nur bei aktivem Build-Schalter
`src/manual-capture.js`	erzeugt den isolierten synthetischen App-Zustand
`tests/manual/manual-walkthroughs.spec.js`	navigiert durch App und Dialoge, setzt Callouts und schreibt die Handbuch-PNG-Dateien
`.github/workflows/manual-screenshots.yml`	führt den Ablauf kontrolliert in GitHub Actions aus
`docs/manual-screenshots.request`	löst durch eine Inhaltsänderung einen neuen CI-Lauf aus

Doppelte Aktivierungssperre¶

Der Capture-Zustand wird nur aktiviert, wenn beide Bedingungen erfüllt sind:

Vite wurde im Modus manual gebaut und setzt dadurch VITE_MANUAL_CAPTURE=1.
Die aufgerufene URL enthält zusätzlich manualCapture=1.

Ein normaler Aufruf von npm run build, npm run android:sync oder der Release-Pipeline setzt den Build-Schalter auf 0. Ein URL-Parameter allein kann den Capture-Zustand deshalb nicht aktivieren. Umgekehrt erzeugt auch ein Handbuch-Build ohne den expliziten URL-Parameter keine Demo-Sitzung.

src/main.jsx lädt src/manual-capture.js nur bei aktivem Build-Schalter dynamisch. Im Capture-Modus wird außerdem kein Service Worker registriert, damit kein alter Cache den dokumentierten Zustand verfälscht.

Synthetische Daten und Datenschutz¶

Jeder Playwright-Test beginnt in einem frischen Browserkontext mit einer eigenen Browserdatenbank. Die Capture-Vorbereitung:

verwendet ausschließlich synthetische Recovery-Datensätze aus src/data/recovery-demo-data.js,
lokalisiert freie Beispieltexte separat für Deutsch und Englisch,
setzt den neutralen Beispielnamen Alex,
markiert Datenschutz-Hinweis, Profil und Produkttour als abgeschlossen,
leert Companion-Erinnerungen und wichtige Notizreferenzen,
verwendet keine Provider-Tokens, Backups oder importierten Nutzerdaten,
und normalisiert Recovery-Beispiele auf den allgemeinen Bereich Social Media beziehungsweise zielloses Scrollen.

Gerätesperre und Screenshot-Schutz sind nur innerhalb dieser künstlichen Browser-Sitzung deaktiviert. Die produktiven Standardwerte und die native Android-Sicherheit werden dadurch nicht geändert.

Dokumentationsmarkierungen¶

Vor jedem Bild erzeugt der Test eine temporäre, fest positionierte Overlay-Ebene. Sie zeichnet gelbe Rahmen um relevante Bedienelemente und ergänzt nummerierte Hinweise in der jeweiligen Dokumentsprache.

Die Callout-Ebene:

verändert keinen React-Zustand und keine IndexedDB-Daten,
besitzt pointer-events: none,
wird erst unmittelbar vor dem Screenshot eingefügt,
wird direkt nach dem Schreiben der PNG-Datei entfernt,
und ist in normalen Builds sowie in der App niemals sichtbar.

Die Markierungen sind Orientierungshilfen und keine pixelgenaue visuelle Regression.

Browseremulation und dokumentierter Rundgang¶

Einstellung	Wert
Viewport	`412 × 915` CSS-Pixel
Geräteskalierung	`1`
Eingabe	mobile Darstellung mit Touch
Farbschema	Dark Mode
Bewegung	reduzierte Animationen
Zeitzone	`Europe/Berlin`
feste Uhrzeit	15. Juli 2026, 19:30 Uhr
Parallelität	ein Worker, Sprachläufe nacheinander

Für jede Sprache werden vierzehn Ansichten erzeugt:

Heute / täglicher Check-in,
Journal,
Recovery,
Muster und Lebensrad,
Explorer,
Toolbox,
Bearbeitungsmodus,
Bereichsverwaltung,
Bereich-zu-Lebensrad-Zuordnung,
Feld-Grundkonfiguration,
Feld-Analytics und Radar-Rolle,
Lebensrad-Achsenverwaltung,
Recovery-Veränderungsbereiche,
Counter- und Rückfallkonfiguration.

Die Tests verwenden nach Möglichkeit zugängliche Rollen und sichtbare Bezeichnungen für die Navigation. Toasts, Caret und Scrollbalken werden für eine ruhigere Dokumentationsdarstellung ausgeblendet. Die Bilder zeigen den aktuellen Viewport und keine künstlich zusammengesetzte Ganzseitenaufnahme.

Grenzen¶

Nicht geprüft oder nicht originalgetreu dargestellt werden insbesondere:

native Android-Status- und Navigationsleisten,
SQLite- und Keystore-Verhalten,
biometrische oder systembasierte Gerätesperren,
Benachrichtigungsberechtigungen,
Dateiauswahl, Teilen-Dialoge und andere Android-Systemoberflächen,
herstellerspezifische Schrift-, Skalierungs- oder WebView-Unterschiede,
Dialoge, Einstellungen und Randfälle außerhalb des definierten Rundgangs,
sowie pixelgenaue Regressionen gegen ein freigegebenes Referenzbild.

Ein erfolgreicher Lauf bedeutet: Die ausgewählten Browseransichten konnten unter den festgelegten Bedingungen gebaut, geöffnet, markiert und fotografiert werden. Er ersetzt keine Android-Instrumentierung, keinen vollständigen Funktionstest und keine manuelle visuelle Abnahme.

Lokale Ausführung¶

npm ci
npm install --no-save --package-lock=false @playwright/test@1.55.0
npx playwright install chromium
npm run docs:screenshots
npm run docs:check

Playwright bleibt eine isolierte Dokumentationsabhängigkeit und wird nicht dauerhaft in package.json oder package-lock.json aufgenommen. npm run docs:screenshots baut die App im Modus manual, startet vite preview lokal auf Port 4173 und führt beide Sprachläufe aus.

CI-Aktualisierung¶

Der Workflow startet nur über workflow_dispatch oder bei einer Änderung an docs/manual-screenshots.request auf main. Normale UI-Commits erzeugen deshalb nicht automatisch neue Binärdateien.

Der Workflow verwendet Node.js 24, installiert Playwright ohne Lockfile-Änderung, installiert Chromium, erzeugt beide Bildsätze und führt anschließend npm run docs:check aus. Erst danach wird ein Commit vorbereitet.

git add docs-site/en/assets/manual docs-site/de/assets/manual

Andere Arbeitsbaumänderungen werden nicht in den Screenshot-Commit aufgenommen. Wenn Build, Navigation, Callout-Erzeugung, Screenshot-Erzeugung oder Dokumentationsprüfung scheitern, erfolgt kein Commit; die zuletzt funktionierenden Bilder bleiben erhalten. Parallele Läufe teilen sich eine Concurrency-Gruppe, wobei ein neuer Lauf einen älteren noch laufenden Durchlauf ersetzt.

Wartungsregeln¶

Nach einer sichtbaren Änderung an einer dokumentierten Ansicht:

Runner, Selektoren und Callout-Ziele an die neue UI anpassen.
Beide Sprachläufe lokal prüfen oder den Request-Zähler erhöhen.
Alle 28 erzeugten Bilder visuell kontrollieren.
Sicherstellen, dass deutsche und englische Ordner dieselben vierzehn Dateinamen enthalten.
Screenshots niemals von Hand retuschieren oder mit realen Daten ersetzen.

Eine umbenannte Navigation oder ein verschwundenes Ziel darf den Lauf sichtbar fehlschlagen lassen. Ein veralteter Rundgang soll nicht stillschweigend scheinbar aktuelle Screenshots erzeugen.

Quellen und Ausgabepfade¶

Zweck	Pfad
Capture-Konfiguration	`playwright.manual.config.js`
Benutzerablauf und Callouts	`tests/manual/manual-walkthroughs.spec.js`
isolierter App-Zustand	`src/manual-capture.js`
Build-Abgrenzung	`vite.config.js`, `src/main.jsx`
CI-Ablauf	`.github/workflows/manual-screenshots.yml`
interne Kurzanleitung	`docs/MANUAL-SCREENSHOTS.md`
englische Bilder	`docs-site/en/assets/manual/`
deutsche Bilder	`docs-site/de/assets/manual/`