visual-verify

Pilote un vrai navigateur headless (Playwright : Chromium, ou WebKit pour iPhone ; exécuté dans l'image Docker Playwright si Docker est installé) pour capturer une application web en cours d'exécution à une taille d'écran choisie, examiner le résultat et confirmer que quelque chose s'affiche/fonctionne correctement — ou générer un composite side-by-side AVANT/APRÈS pour un changement visuel.

Qu'est-ce que visual-verify ?

Cette compétence « visual-verify » permet à un agent IA de piloter un véritable navigateur headless (via Playwright) afin de capturer des captures d'écran d'une application web en cours d'exécution et de les analyser visuellement. Elle offre deux modes principaux : la vérification simple (capture et examen d'une ou plusieurs vues pour confirmer le rendu ou le fonctionnement d'une fonctionnalité) et le mode « avant/après » qui produit un composite côte à côte pour comparer un changement visuel. Elle supporte également les tests tactiles mobiles (iOS/Android) avec évaluation de la taille des cibles. La compétence s'exécute via des scripts Node.js, avec un support optionnel de Docker pour isoler le navigateur. L'agent doit toujours lire les images capturées avant de rapporter un résultat, et inclure les captures dans sa réponse. L'installation est requise une fois par machine, et les dépendances Playwright sont gérées localement.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

légende

Documentation

Que fait visual-verify ?

Version : 1.1.0. Les versions antérieures à 1.0.0 ne sont pas suivies dans ce dépôt.

Examinez la vraie application en cours d'exécution dans un navigateur headless et rapportez honnêtement ce que vous voyez. Deux modes :

  • Vérification (par défaut) — capturez une (ou quelques) captures d'écran de l'état actuel et lisez-les vous-même pour confirmer qu'une fonctionnalité s'affiche, qu'un correctif a fonctionné ou qu'une mise en page est correcte à une largeur donnée.
  • Avant/Après — pour un changement visuel, basculez le changement entre désactivé et activé et produisez un composite côte à côte AVANT/APRÈS avec des libellés.
  • Tactile (iOS / Android) — émulez un téléphone, tapez et faites glisser avec un doigt, et auditez la taille des cibles tactiles. Voir Tests tactiles mobiles ci-dessous.

Choisissez le mode en fonction de la demande de l'utilisateur. « Est-ce que ça a l'air correct / est-ce que ça fonctionne / montre-moi en largeur téléphone » → vérification. « Avant et après / est-ce que ça a corrigé visuellement » → avant/après.

Quand l'utilisateur le demande, faites-le

Lorsque l'utilisateur vous demande de vérifier visuellement quelque chose (ou de faire une capture d'écran / de vérifier l'apparence), cette demande est votre feu vert — exécutez la vérification complète vous-même : capturez, lisez la ou les images, et indiquez clairement si c'est correct. Ne vous contentez pas de proposer et de vous arrêter.

Ne pas exécuter cela de votre propre initiative après chaque changement — cela pilote un navigateur et lit des images, ce qui coûte des tokens. Après un changement visuel non demandé, vous pouvez le proposer (« voulez-vous un composite avant/après — mobile, desktop, ou les deux ? ») et laisser l'utilisateur décider.

Montrez ce que vous avez vérifié — à chaque fois

L'utilisateur doit pouvoir voir le résultat sans ouvrir de fichiers. Dans la réponse qui rend compte du travail, montrez l'image après pour chaque fonctionnalité que vous avez vérifiée — une image par fonctionnalité, donc trois éléments vérifiés signifient au moins trois images. Placez chaque image à côté d'une légende d'une ligne indiquant ce qu'elle montre et si elle est correcte (par exemple « Confirmation de suppression, largeur téléphone — focus sur Annuler »).

  • Affichez les images en ligne avec Markdown et un chemin absolu, ![légende](/chemin/absolu/vers/image.png), afin que le client les rende. Sinon, attachez-les (par exemple SendUserFile). Donnez toujours le chemin.
  • Choisissez la capture la plus claire : recadrez ou coupez sur la fonctionnalité là où la page entière l'enterrerait.
  • Pour un avant/après, montrez le composite.
  • Si quelque chose ne peut pas être montré honnêtement (interface système, zone de sécurité), dites-le plutôt que d'afficher une image trompeuse.

Regardez toujours ce que vous avez capturé

La capture d'écran n'est pas le livrable — votre jugement vérifié l'est. Lisez chaque image que vous capturez avant de faire votre rapport, et avant d'envoyer un composite, afin de pouvoir confirmer qu'elle montre effectivement ce que vous prétendez. Si elle ne montre pas ce que vous attendiez, enquêtez ; ne rapportez pas un succès sur la base d'une capture non lue.

Choisissez la bonne zone d'affichage — c'est important

Un bogue d'adaptation ne se reproduit souvent qu'à une largeur spécifique. Faites correspondre l'appareil de l'utilisateur. S'il a envoyé une capture d'écran, déduisez la largeur CSS :

css_width = largeur_pixels_capture / devicePixelRatio

Les iPhones modernes sont DPR 3 (par exemple une capture de 1320 px de large ⇒ 440 px CSS ; classe Pro Max). Les Android courants sont DPR ~2,6–3. En cas de doute, balayez plusieurs largeurs (par exemple 320, 360, 390, 440) — le script de capture rend cela peu coûteux. Passez --mobile pour l'émulation tactile/mobile. Pour un changement de design général qui s'applique à toutes les largeurs, vérifiez à la fois desktop et mobile.

Les scripts (à exécuter avec Bash ; il n'y a pas de MCP)

Ne cherchez pas d'outil browser_* / Playwright MCP — il n'est pas installé. Tout passe par des scripts Node simples. Résolvez le répertoire absolu contenant ce SKILL.md installé, puis définissez VISUAL_VERIFY_DIR sur ce répertoire dans votre shell. Il peut s'agir d'une installation dans un projet ou d'une installation globale ; utilisez la copie dont vous lisez les instructions, pas un chemin global codé en dur. Conservez le répertoire de travail à la racine du projet d'application. Réutilisez cette variable dans chaque commande shell (ou redéfinissez-la si l'état du shell n'est pas conservé) :

VISUAL_VERIFY_DIR="/chemin/absolu/vers/visual-verify-installé"

Les scripts fournis sont :

"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs"   # capture une URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs"     # deux png → avant/après avec libellés
"$VISUAL_VERIFY_DIR/scripts/touch.mjs"         # tactile téléphone : taper, glisser, audit cible

Environnement d'exécution et configuration du navigateur. Cette compétence possède sa propre dépendance Playwright et son fichier de verrouillage. Elle ne résout jamais un package Playwright global ou de projet. Exécutez l'installateur explicitement après avoir installé ou mis à jour la compétence ; les vérifications normales ne téléchargent jamais de packages, d'images ou de navigateurs. Utilisez Node.js 20+, npm et Bash. N'installez pas de packages système hôte pour cette compétence.

Où le navigateur s'exécute. Avec Docker disponible, chaque lancement démarre son propre conteneur à partir de l'image Playwright exacte correspondante, déjà installée. Docker alloue un port de bouclage unique ; l'assistant vérifie l'identité de son conteneur et se connecte à ce point de terminaison. Les dépendances Node installées de la compétence sont montées en lecture seule, de sorte que le serveur n'a pas besoin de téléchargements de packages. Playwright transmet les requêtes de bouclage au client, permettant d'utiliser des URL d'applications locales sans réseau hôte. La fermeture normale, l'échec de démarrage et l'arrêt géré nettoient uniquement le conteneur de cette exécution. Un kill dur ou un crash de l'hôte peut laisser un conteneur étiqueté ; inspectez la propriété avant un nettoyage explicite. Aucun conteneur préexistant n'est remplacé ou arrêté. La mise en réseau Docker Desktop/macOS nécessite toujours une validation séparée ; ne l'affirmez pas à partir d'une vérification Linux.

Sans Docker, l'assistant utilise les binaires de navigateur locaux installés. Définissez VISUAL_VERIFY_DOCKER=0 pour forcer le mode local ; l'API de lancement accepte également un backend explicite. La sortie JSON nomme le backend réel et sa version.

Lanceur pris en charge pour les scripts de projet

// Résolvez cette importation par rapport au répertoire de compétence installé.
const { launchBrowser } = await import("<compétence-installée>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
  backend: "auto", // auto, docker, local
  timeout: 30000,
  launchOptions: { headless: true },
});
try {
  // Utilisez browser.newContext(), etc. Rapportez `where` avec la preuve.
} finally {
  await browser.close();
}

launchOptions vont à launch local ou à la demande de lancement du navigateur du serveur Docker épinglé. Le serveur Playwright complet active le transfert de bouclage du client demandé ; Docker possède l'hôte et le port du serveur ; les chemins d'exécutables spécifiques à l'hôte et les autres options spécifiques à la machine sont de la responsabilité de l'appelant. Les exports existants loadChromium() et loadBrowser(name) restent des API de compatibilité locales uniquement : ils ne lancent pas Docker et ne réparent pas les navigateurs manquants. Migrez les appelants délibérément plutôt que de supposer que la configuration modifie leur comportement.

Les lancements Docker utilisent un conteneur serveur frais et nommé de manière unique pour chaque appel. Docker alloue atomiquement un port de bouclage ; le client valide les métadonnées du conteneur et se connecte à son chemin WebSocket rapporté. Playwright transfère le trafic de bouclage du client, préservant l'accès aux applications de développement locales sans réseau hôte. Les conteneurs sont supprimés lors de la fermeture, de l'échec de démarrage et de l'arrêt géré. Cela échange la réutilisation du serveur chaud contre l'isolation des points de terminaison ; les anciens conteneurs à port partagé sont laissés tranquilles. Un kill forcé ou un échec Docker peut laisser un orphelin. Inspectez la sortie doctor et vérifiez la propriété du conteneur exact avant de le supprimer explicitement ; n'arrêtez jamais tous les processus/conteneurs correspondants. Le comportement Docker multiplateforme nécessite toujours une validation indépendante.

Indicateurs screenshot.mjs : --url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Texte ou sélecteur"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]. --click est répétable et correspond d'abord au nom accessible d'un bouton, puis à un sélecteur CSS — utilisez-le pour atteindre un état derrière un onglet/menu/dialogue.

Installation unique (par machine)

bash "$VISUAL_VERIFY_DIR/scripts/install.sh"

Installe la dépendance verrouillée dans son propre node_modules de la compétence. La configuration par défaut auto tire l'image Docker correspondante si Docker est disponible ; sinon, elle installe Chromium local. Passez docker ou local à l'installateur pour sélectionner explicitement. WebKit local n'est pas installé par cette commande. Aucun package npm global ou package système n'est modifié.

Inspectez les prérequis sans démarrer de navigateurs, tirer des images ou modifier des conteneurs :

node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"

Doctor rapporte la version de la compétence/de l'environnement d'exécution, le chemin d'exécution, la présence d'exécutables locaux, la disponibilité des images Docker et les conteneurs/points de terminaison Visual Verify actifs (y compris les noms hérités). Son code de sortie vérifie les prérequis Chromium pour le backend par défaut sélectionné ; il ne prouve pas le lancement du navigateur ou la disponibilité de WebKit. L'installation des fichiers et le lancement réussi d'un navigateur sont des preuves séparées.

Vérifiez avec :

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url https://example.com --out /tmp/_vv_check.png --width 390 --height 844

Inspectez l'image et le JSON du backend pour confirmer que cette vérification de fumée a fonctionné.

Attendez l'état vérifié

Les commandes de capture d'écran et tactiles prennent en charge ces options post-action :

  • --ready-selector "<sélecteur>" : attend que le premier élément correspondant soit visible.
  • --ready-js "<expression>" : interroge jusqu'à ce qu'une expression de page (y compris une promesse) soit vraie.
  • --ready-timeout 10000 : délai d'attente positif en millisecondes ; partagé par les attentes de sélecteur et de prédicat. Borne également l'évaluation de --eval et --report séparément.
  • --settle 0 : délai non négatif facultatif après la disponibilité pour l'animation.

Ces conditions s'exécutent après tous les clics, tapotements, défilements, évaluations et glissements, avant l'audit et la capture. Les deux conditions, lorsqu'elles sont fournies, doivent réussir. Un échec se termine avec un code non nul et n'écrit pas une nouvelle capture d'écran de succès (un fichier de sortie existant n'est pas supprimé). Choisissez des chemins de sortie uniques. --wait conserve son délai pré-action hérité ; les délais de clic/glissement fixes restent des stabilisations de compatibilité, pas une preuve de disponibilité. Indiquez ce que la condition sélectionnée prouve.

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url "<url-app-locale>" --out visual-checks/search-desktop.png \
  --click "Rechercher" --ready-selector "[data-search-results]" \
  --ready-js "document.querySelectorAll('[data-result]').length > 0"

Utilisez une condition spécifique au nouvel état attendu, pas un élément obsolète déjà sur la page. Pour les étapes intermédiaires nécessitant des résultats asynchrones, utilisez l'API de lancement et les localisateurs Playwright avec des assertions entre les actions. Si vous attendez une réponse, enregistrez l'attente avant de déclencher sa demande, puis affirmez l'état rendu ; une réponse seule ne prouve pas le rendu. Ne traitez pas les délais arbitraires ou l'inactivité du réseau comme des garanties d'achèvement pour les applications anti-rebond.

Emplacement de sortie

Écrivez les images générées dans un répertoire visual-checks/ ignoré par git à la racine du dépôt (mkdir -p visual-checks). Si vous n'êtes pas dans un dépôt, ou si vous ne voulez pas y ajouter de fichiers, utilisez un répertoire temporaire à la place. Référencez les chemins stables lors de l'envoi de fichiers à l'utilisateur.

Donnez à chaque image d'une même exécution un préfixe partagé <changement> décrivant ce qui est montré (par exemple import-export-tab, header-nav) — pas générique before.png/after.png — afin qu'un coup d'œil au répertoire indique à quelle exécution appartient un fichier :

visual-checks/<changement>-<viewport>.png                 # mode vérification : une seule capture
visual-checks/<changement>-<viewport>-before.png          # mode avant/après
visual-checks/<changement>-<viewport>-after.png
visual-checks/<changement>-<viewport>-before-after.png    # le composite

où <viewport> est mobile ou desktop.

Flux de travail — mode vérification

  1. Assurez-vous que l'application est en cours d'exécution et que vous avez son URL (démarrez-la comme ce projet s'exécute — voir Exécution de l'application ci-dessous). mkdir -p visual-checks.
  2. Capturez l'état à vérifier, en l'atteignant avec --click / --eval / --scroll-bottom si nécessaire :
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<url de l'application en cours>" --out visual-checks/<changement>-mobile.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Balayez plusieurs largeurs, ou supprimez --mobile et utilisez par exemple --width 1280 --height 800 pour le desktop, selon les besoins.
  3. Lisez chaque image et rapportez clairement si elle est correcte. Si vous vérifiez un correctif, confirmez que l'élément cassé a effectivement disparu ; si une fonctionnalité, confirmez qu'elle s'affiche réellement.
  4. Montrez la ou les captures pertinentes dans votre réponse — une par fonctionnalité (voir Montrez ce que vous avez vérifié).

Flux de travail — mode avant/après

  1. Confirmez la portée et la ou les zones d'affichage. mkdir -p visual-checks. Choisissez le préfixe partagé <changement>.
  2. Capturez APRÈS — l'arbre de travail contient déjà le changement :
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<url de l'application en cours>" --out visual-checks/<changement>-mobile-after.png \
      --width 440 --height 800 --mobile --wait 2000
    
    Pour le desktop, supprimez --mobile, utilisez par exemple --width 1280 --height 800, et le suffixe -desktop-after.png.
  3. Capturez AVANT — annulez temporairement uniquement le changement visuel, capturez dans <changement>-<viewport>-before.png, puis restaurez. Préférez git pour ne pas oublier de restaurer :
    • Changement non commité : git stash push -- <fichier> → capture → git stash pop
    • Changement committé : git show HEAD~1:<chemin> > <chemin> (ou git checkout <parent> -- <fichier>) → capture → git checkout -- <fichier> Attendez que le serveur de développement recharge à chaud entre le basculement et la capture (--wait).
  4. Compositez — même préfixe, suffixe -before-after.png :
    node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \
      --before visual-checks/<changement>-mobile-before.png --after visual-checks/<changement>-mobile-after.png \
      --out visual-checks/<changement>-mobile-before-after.png \
      --title "En-tête à 440 px (largeur iPhone)" \
      --before-label "AVANT — titre écrasé" \
      --after-label  "APRÈS — titre pleine largeur"
    
  5. Lisez le composite, confirmez qu'il montre ce que vous prétendez, puis montrez-le dans votre réponse.
  6. Restaurez le basculement AVANT. Ne commitez ni ne déployez jamais avec le changement AVANT temporaire encore appliqué — revérifiez git status / git diff avant de terminer.

Tests tactiles mobiles (

…

[tronqué pour la traduction]

Skills associés