Visual Verify
Version: 1.1.0. Versionen vor 1.0.0 werden nicht in diesem Repository verfolgt.
Betrachte die echte laufende App in einem kopflosen Browser und berichte ehrlich, was du siehst. Zwei Modi:
- Überprüfen (Standard) – erstelle einen (oder wenige) Screenshots des aktuellen Zustands und lies sie selbst, um zu bestätigen, dass eine Funktion rendert, eine Fehlerbehebung funktioniert hat oder ein Layout bei einer bestimmten Breite korrekt ist.
- Vorher/Nachher – für eine visuelle Änderung schalte die Änderung aus und ein und erstelle eine einzelne beschriftete VORHER/NACHHER-Gegenüberstellung.
- Touch (iOS / Android) – emuliere ein Telefon, tippe und ziehe mit einem Finger und überprüfe Touch-Zielgrößen. Siehe Mobile Touch-Checks unten.
Wähle den Modus basierend auf der Anfrage des Benutzers. „Sieht das richtig aus / funktioniert es / zeig es mir in Telefonbreite“ → Überprüfen. „Vorher und Nachher / hat das das Problem visuell behoben“ → Vorher/Nachher.
Wenn der Benutzer danach fragt, mach es
Wenn der Benutzer dich bittet, etwas visuell zu überprüfen (oder zu screenshotten / nachzusehen, wie es aussieht), ist diese Anfrage dein Startzeichen – führe die vollständige Prüfung selbst durch: erfassen, das/die Bild(er) lesen und klar sagen, ob es richtig ist. Biete es nicht nur an und höre auf.
Führe dies nicht unaufgefordert aus eigener Initiative nach jeder Änderung aus – es startet einen Browser und liest Bilder, was Tokens kostet. Nach einer unaufgeforderten visuellen Änderung darfst du es anbieten („Möchtest du eine Vorher/Nachher-Gegenüberstellung – mobil, Desktop oder beides?“) und den Benutzer entscheiden lassen.
Zeige, was du überprüft hast – jedes Mal
Der Benutzer muss das Ergebnis sehen können, ohne Dateien öffnen zu müssen. Zeige in der Antwort, die die Arbeit meldet, das Nachher-Bild für jede Funktion, die du überprüft hast – ein Bild pro Funktion, also bei drei überprüften Dingen mindestens drei Bilder. Platziere jedes Bild neben einer einzeiligen Beschriftung, die sagt, was es zeigt und ob es korrekt ist (z. B. „Löschbestätigung, Telefonbreite – Fokus auf Abbrechen“).
- Zeige Bilder inline mit Markdown und einem absoluten Pfad,
, wo der Client sie rendert. Andernfalls hänge sie an (z. B. SendUserFile). Gib immer auch den Pfad an. - Wähle die klarste Aufnahme: beschneide oder schneide auf die Funktion, wo die vollständige Seite sie verstecken würde.
- Für ein Vorher/Nachher zeige die Gegenüberstellung.
- Wenn etwas nicht ehrlich gezeigt werden konnte (System-UI, Safe-Area), sage dies, anstatt ein irreführendes Bild zu zeigen.
Sieh dir immer an, was du erfasst hast
Der Screenshot ist nicht das Ergebnis – dein überprüftes Urteil ist es. Lies jedes Bild, das du erfasst hast, bevor du berichtest, und bevor du eine Gegenüberstellung sendest, damit du bestätigen kannst, dass es tatsächlich zeigt, was du behauptest. Wenn es nicht das zeigt, was du erwartet hast, recherchiere; melde keinen Erfolg auf der Grundlage eines ungelesenen Screenshots.
Wähle den richtigen Viewport – das ist wichtig
Ein responsiver Fehler tritt oft nur bei einer bestimmten Breite auf. Passe das Gerät des Benutzers an. Wenn er einen Screenshot geschickt hat, leite die CSS-Breite ab:
css_breite = screenshot_pixel_breite / devicePixelRatio
Moderne iPhones haben DPR 3 (z. B. ein 1320px breiter Screenshot ⇒ 440 CSS-Px; Pro-Max-Klasse).
Übliche Android-Geräte haben DPR ~2.6–3. Wenn du dir unsicher bist, probiere ein paar Breiten durch (z. B. 320, 360, 390, 440) – das Screenshot-Skript macht dies günstig. Verwende --mobile für Touch/Mobil-Emulation. Für eine allgemeine Designänderung, die bei allen Breiten gilt, überprüfe sowohl Desktop als auch Mobil.
Die Skripte (mit Bash ausführen; es gibt kein MCP)
Suche nicht nach einem browser_* / Playwright-MCP-Tool – es ist nicht installiert. Alles läuft über einfache Node-Skripte. Ermittele das absolute Verzeichnis, das diese installierte SKILL.md enthält, und setze dann VISUAL_VERIFY_DIR in deiner Shell auf dieses Verzeichnis. Dies kann eine Projektinstallation oder eine globale Installation sein; verwende die Kopie, deren Anweisungen du gerade liest, keinen fest codierten globalen Pfad. Behalte das Arbeitsverzeichnis im App-Projektstamm. Verwende diese Variable in jedem Shell-Befehl erneut (oder setze sie erneut, wenn der Shell-Zustand nicht erhalten bleibt):
VISUAL_VERIFY_DIR="/absoluter/pfad/zum/installierten/visual-verify"
Die gebündelten Skripte sind:
"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" # erfasse eine URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs" # zwei pngs → beschriftet vorher/nachher
"$VISUAL_VERIFY_DIR/scripts/touch.mjs" # Telefon-Touch: tippen, ziehen, Ziel-Prüfung
Laufzeit und Browser-Setup. Dieser Skill besitzt eine genaue Playwright-Abhängigkeit und Sperrdatei. Er löst niemals ein globales oder Projekt-Playwright-Paket auf. Führe das Installationsprogramm explizit nach der Installation oder Aktualisierung des Skills aus; normale Prüfungen laden niemals Pakete, Images oder Browser herunter. Verwende Node.js 20+, npm und Bash. Installiere keine Host-Systempakete für diesen Skill.
Wo der Browser läuft. Wenn Docker verfügbar ist, startet jeder Launch seinen eigenen Container aus dem exakt passenden, bereits installierten Playwright-Image. Docker weist einen eindeutigen Loopback-Port zu; der Helfer überprüft seine Container-Identität und verbindet sich mit diesem Endpunkt. Die installierten Node-Abhängigkeiten des Skills sind schreibgeschützt eingebunden, sodass der Server keine Pakete herunterladen muss. Playwright leitet Loopback-Anfragen an den Client weiter, sodass lokale App-URLs ohne Host-Netzwerk möglich sind. Normales Schließen, Startfehler und behandeltes Beenden bereinigen nur den Container dieses Laufs. Ein harter Kill oder Host-Absturz kann einen markierten Container hinterlassen; überprüfe den Besitz vor der expliziten Bereinigung. Keine bereits vorhandenen Container werden ersetzt oder gestoppt. Docker Desktop/macOS-Netzwerk erfordert dennoch eine separate Validierung; behaupte dies nicht von einem Linux-Check aus.
Ohne Docker verwendet der Helfer installierte lokale Browser-Binärdateien. Setze VISUAL_VERIFY_DOCKER=0, um den lokalen Modus zu erzwingen; die Start-API akzeptiert auch ein explizites Backend. Die JSON-Ausgabe nennt das tatsächliche Backend und die Version.
Unterstützter Launcher für Projektskripte
// Löse diesen Import relativ zum installierten Skill-Verzeichnis auf.
const { launchBrowser } = await import("<installiertes-skill>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
backend: "auto", // auto, docker, local
timeout: 30000,
launchOptions: { headless: true },
});
try {
// Verwende browser.newContext(), etc. Melde `where` mit den Beweisen.
} finally {
await browser.close();
}
launchOptions gehen an den lokalen launch oder die angeforderte Browser-Start-Anfrage des festgelegten Docker-Servers. Der vollständige Playwright-Server ermöglicht die angeforderte Client-Loopback-Weiterleitung; Docker besitzt den Server-Host und -Port; host-spezifische ausführbare Pfade und andere maschinenspezifische Optionen liegen in der Verantwortung des Aufrufers. Bestehende loadChromium()- und loadBrowser(name)-Exporte bleiben nur lokale Kompatibilitäts-APIs: sie starten weder Docker noch reparieren sie fehlende Browser. Migriere Aufrufer bewusst, anstatt anzunehmen, dass das Setup ihr Verhalten ändert.
Docker-Starts verwenden für jeden Aufruf einen neuen, eindeutig benannten Server-Container. Docker weist atomar einen Loopback-Port zu; der Client validiert Container-Metadaten und verbindet sich mit seinem gemeldeten WebSocket-Pfad. Playwright leitet Client-Loopback-Datenverkehr weiter und bewahrt so den Zugriff auf lokale Dev-Apps ohne Host-Netzwerk. Container werden beim Schließen, Startfehler und behandeltem Beenden entfernt. Dies tauscht Warm-Server-Wiederverwendung gegen Endpunkt-Isolation; ältere Shared-Port-Container werden in Ruhe gelassen. Ein erzwungener Kill oder Docker-Fehler kann einen verwaisten Container hinterlassen. Überprüfe die Doctor-Ausgabe und verifiziere den genauen Container-Besitz, bevor du ihn explizit entfernst; stoppe niemals alle passenden Prozesse/Container. Plattformübergreifendes Docker-Verhalten erfordert dennoch eine unabhängige Validierung.
screenshot.mjs-Flags: --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Text oder Selektor"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]. --click ist wiederholbar und matcht zuerst den barrierefreien Namen einer Schaltfläche, dann einen CSS-Selektor – verwende es, um einen Zustand hinter einem Tab/Menü/Dialog zu erreichen.
Einmalige Installation (pro Maschine)
bash "$VISUAL_VERIFY_DIR/scripts/install.sh"
Installiert die gesperrte Abhängigkeit in das eigene node_modules dieses Skills. Das standardmäßige auto-Setup zieht das passende Docker-Image, wenn Docker verfügbar ist; andernfalls installiert es lokales Chromium. Übergib docker oder local an das Installationsprogramm, um explizit auszuwählen. Lokales WebKit wird von diesem Befehl nicht installiert. Es werden keine globalen npm-Pakete oder Systempakete geändert.
Überprüfe Voraussetzungen, ohne Browser zu starten, Images zu ziehen oder Container zu ändern:
node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"
Doctor meldet die Skill-/Laufzeitversion, den Laufzeitpfad, das Vorhandensein lokaler ausführbarer Dateien, die Docker-Image-Verfügbarkeit und aktive Visual-Verify-Container/Endpunkte (einschließlich Legacy-Namen). Der Exit-Status prüft Chromium-Voraussetzungen für das ausgewählte Standard-Backend; er beweist weder den Browser-Start noch die WebKit-Verfügbarkeit. Das Installieren von Dateien und das erfolgreiche Starten eines Browsers sind getrennte Beweise.
Überprüfe mit:
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url https://example.com --out /tmp/_vv_check.png --width 390 --height 844
Überprüfe das Bild und das Backend-JSON, um zu bestätigen, dass dieser Smoke-Test funktioniert hat.
Warte auf den zu überprüfenden Zustand
Screenshot- und Touch-Befehle unterstützen diese Post-Action-Optionen:
--ready-selector "<selektor>": warte, bis das erste passende Element sichtbar ist.--ready-js "<ausdruck>": pollt, bis ein Seitenausdruck (einschließlich eines Promises) truthy ist.--ready-timeout 10000: positive Bereitschafts-Timeout in Millisekunden; wird vom Selektor und Prädikat-Wait gemeinsam genutzt. Begrenzt auch die Auswertung von--evalund--reportseparat.--settle 0: optionales, nicht-negatives Verzögerung nach Bereitschaft für Animationen.
Diese Bedingungen laufen nach allen Klicks/Taps, Scrollen, Auswertung und Ziehen, vor Prüfung und Erfassung. Beide Bedingungen, wenn angegeben, müssen bestehen. Ein Fehler beendet sich mit einem Exit-Code ungleich Null und schreibt keinen neuen Erfolgs-Screenshot (eine vorhandene Ausgabedatei wird nicht entfernt). Wähle eindeutige Ausgabepfade. --wait behält seine legacy Pre-Action-Verzögerung; feste Klick-/Zieh-Verzögerungen bleiben Kompatibilitäts-Settles, keine Beweise für Bereitschaft. Gib an, was die gewählte Bedingung beweist.
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url "<lokale-app-url>" --out visual-checks/suche-desktop.png \
--click "Suche" --ready-selector "[data-suchergebnisse]" \
--ready-js "document.querySelectorAll('[data-ergebnis]').length > 0"
Verwende eine Bedingung, die für den erwarteten neuen Zustand spezifisch ist, nicht ein altes Element, das bereits auf der Seite vorhanden ist. Für Zwischenschritte, die asynchrone Ergebnisse erfordern, verwende die Start-API und Playwright-Locators mit Assertions zwischen Aktionen. Wenn du auf eine Antwort wartest, registriere den Wait, bevor du seine Anfrage auslöst, und bestätige dann den gerenderten Zustand; eine Antwort allein beweist kein Rendern. Behandle keine willkürlichen Verzögerungen oder Netzwerk-Idle als Fertigstellungsgarantien für entprellte Apps.
Ausgabeort
Schreibe generierte Bilder in ein git-ignoriertes visual-checks/ im Repository-Stamm (mkdir -p visual-checks). Wenn du dich nicht in einem Repository befindest oder keine Dateien darin hinzufügen möchtest, verwende stattdessen ein temporäres Verzeichnis. Referenziere die stabilen Pfade, wenn du Dateien an den Benutzer sendest.
Gib jedem Bild aus einem Lauf ein gemeinsames <änderung>-Präfix, das beschreibt, was gezeigt wird (z. B. import-export-tab, header-nav) – nicht generische before.png/after.png – damit ein Blick auf das Verzeichnis sagt, zu welchem Lauf eine Datei gehört:
visual-checks/<änderung>-<viewport>.png # Überprüfungsmodus: ein einzelner Schuss
visual-checks/<änderung>-<viewport>-before.png # Vorher/Nachher-Modus
visual-checks/<änderung>-<viewport>-after.png
visual-checks/<änderung>-<viewport>-before-after.png # die Gegenüberstellung
wobei <viewport> entweder mobile oder desktop ist.
Arbeitsablauf – Überprüfungsmodus
- Stelle sicher, dass die App läuft und du ihre URL hast (starte sie so, wie dieses Projekt läuft – siehe App ausführen unten).
mkdir -p visual-checks. - Erfasse den zu überprüfenden Zustand und erreiche ihn bei Bedarf mit
--click/--eval/--scroll-bottom:Probiere ein paar Breiten durch oder verwende für Desktopnode "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<laufende app url>" --out visual-checks/<änderung>-mobile.png \ --width 440 --height 800 --mobile --wait 2000--mobileweglassen und z. B.--width 1280 --height 800, je nach Bedarf. - Lies jedes Bild und berichte klar, ob es richtig ist. Wenn du eine Fehlerbehebung überprüfst, bestätige, dass das kaputte Ding tatsächlich weg ist; wenn eine Funktion, bestätige, dass sie tatsächlich rendert.
- Zeige die relevanten Aufnahmen in deiner Antwort – eine pro Funktion (siehe Zeige, was du überprüft hast).
Arbeitsablauf – Vorher/Nachher-Modus
- Bestätige den Umfang und die Viewport(s).
mkdir -p visual-checks. Wähle das gemeinsame<änderung>-Präfix. - Erfasse NACHHER – der Arbeitsbaum enthält bereits die Änderung:
Für Desktop lassenode "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<laufende app url>" --out visual-checks/<änderung>-mobile-after.png \ --width 440 --height 800 --mobile --wait 2000--mobileweg, verwende z. B.--width 1280 --height 800und das Suffix-desktop-after.png. - Erfasse VORHER – mache nur die visuelle Änderung vorübergehend rückgängig, screenshot nach
<änderung>-<viewport>-before.png, dann stelle wieder her. Bevorzuge Git, damit du nicht vergessen kannst, wiederherzustellen:- Nicht committete Änderung:
git stash push -- <datei>→ Screenshot →git stash pop - Committete Änderung:
git show HEAD~1:<pfad> > <pfad>(odergit checkout <parent> -- <datei>) → Screenshot →git checkout -- <datei>Warte zwischen dem Umschalten und der Aufnahme auf das Hot-Reload des Dev-Servers (--wait).
- Nicht committete Änderung:
- Gegenüberstellung – gleiches Präfix, Suffix
-before-after.png:node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \ --before visual-checks/<änderung>-mobile-before.png --after visual-checks/<änderung>-mobile-after.png \ --out visual-checks/<änderung>-mobile-before-after.png \ --title "Header bei 440px (iPhone-Breite)" \ --before-label "VORHER — Titel gestaucht" \ --after-label "NACHHER — Titel volle Breite" - Lies die Gegenüberstellung, bestätige, dass sie zeigt, was du behauptest, und zeige sie dann in deiner Antwort.
- Stelle den VORHER-Umschalter wieder her. Committe oder deploye niemals mit der temporären VORHER-Änderung, die noch angewendet ist – überprüfe vor dem Abschluss erneut
git status/git diff.
Mobile Touch-Checks (
…
[abgeschnitten für die Übersetzung]
