CommunityCodierung & Entwicklunggithub.com

visual-verify

Führt einen echten, kopflosen Browser (Playwright: Chromium oder WebKit für iPhone; läuft im Playwright-Docker-Image, wenn Docker installiert ist) aus, um eine laufende Web-App bei einem gewählten Geräte-Viewport zu screenshotten, das Ergebnis zu betrachten und zu bestätigen, ob etwas tatsächlich gerendert wird/funktioniert – oder erstellt eine beschriftete VORHER/NACHHER-Gegenüberstellung für eine visuelle Änderung. Verwende dies immer, wenn der Benutzer bittet, etwas visuell zu überprüfen, zu sehen, wie eine Seite/eine Komponente aussieht, die UI bei einer Telefon-/Tabletbreite zu prüfen, die App zu screenshotten, ein Vorher-Nachher einer Stiländerung zu erhalten oder mobile Touch-Interaktionen auf iOS/Android zu testen (Touch-Zielgrößen, Tippen, Ziehen/Größenänderung mit dem Finger). Funktioniert in jedem Projekt. Verwendet die Playwright-Bibliothek über Node-Skripte in scripts/ – es gibt hier KEIN Playwright MCP.

Was ist visual-verify?

Visual-Verify ist eine Skill für KI-Agenten (wie Claude Code, Cursor, Codex), die einen echten, kopflosen Browser (Playwright: Chromium oder WebKit für iPhone) nutzt, um eine laufende Web-App bei einem spezifischen Geräte-Viewport zu screenshotten und das visuelle Ergebnis zu überprüfen. Der Skill bietet drei Modi: Überprüfung (ein oder mehrere Screenshots des aktuellen Zustands), Vorher/Nachher (Wechsel zwischen zwei Zuständen für eine visuelle Gegenüberstellung) und Touch-Tests (Emulation von iPhone/Android, Tippen, Ziehen und Prüfung von Touch-Zielgrößen). Die Ausführung erfolgt über lokale Node-Skripte (scripts/screenshot.mjs, scripts/composite.mjs, scripts/touch.mjs), die mit Playwright arbeiten; der Agent kann Docker für isolierte Browser-Container oder lokale Browser-Binärdateien nutzen. Der Skill erfordert eine einmalige Installation pro Maschine (bash scripts/install.sh), erzeugt Ausgaben im gitignorierten Ordner visual-checks/ und verlangt, dass der Agent jeden Screenshot liest und ein fundiertes Urteil abgibt, bevor er dem Benutzer berichtet.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

Beschriftung

Dokumentation

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, ![Beschriftung](/abs/pfad/zu/bild.png), 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 --eval und --report separat.
  • --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

  1. 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.
  2. Erfasse den zu überprüfenden Zustand und erreiche ihn bei Bedarf mit --click / --eval / --scroll-bottom:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<laufende app url>" --out visual-checks/<änderung>-mobile.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Probiere ein paar Breiten durch oder verwende für Desktop --mobile weglassen und z. B. --width 1280 --height 800, je nach Bedarf.
  3. 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.
  4. Zeige die relevanten Aufnahmen in deiner Antwort – eine pro Funktion (siehe Zeige, was du überprüft hast).

Arbeitsablauf – Vorher/Nachher-Modus

  1. Bestätige den Umfang und die Viewport(s). mkdir -p visual-checks. Wähle das gemeinsame <änderung>-Präfix.
  2. Erfasse NACHHER – der Arbeitsbaum enthält bereits die Änderung:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<laufende app url>" --out visual-checks/<änderung>-mobile-after.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Für Desktop lasse --mobile weg, verwende z. B. --width 1280 --height 800 und das Suffix -desktop-after.png.
  3. 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> (oder git checkout <parent> -- <datei>) → Screenshot → git checkout -- <datei> Warte zwischen dem Umschalten und der Aufnahme auf das Hot-Reload des Dev-Servers (--wait).
  4. 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"
    
  5. Lies die Gegenüberstellung, bestätige, dass sie zeigt, was du behauptest, und zeige sie dann in deiner Antwort.
  6. 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]

Verwandte Skills