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,
, 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--evalet--reportsé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
- 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. - Capturez l'état à vérifier, en l'atteignant avec
--click/--eval/--scroll-bottomsi nécessaire :Balayez plusieurs largeurs, ou supprimeznode "$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--mobileet utilisez par exemple--width 1280 --height 800pour le desktop, selon les besoins. - 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.
- 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
- Confirmez la portée et la ou les zones d'affichage.
mkdir -p visual-checks. Choisissez le préfixe partagé<changement>. - Capturez APRÈS — l'arbre de travail contient déjà le changement :
Pour le desktop, supprimeznode "$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--mobile, utilisez par exemple--width 1280 --height 800, et le suffixe-desktop-after.png. - 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>(ougit checkout <parent> -- <fichier>) → capture →git checkout -- <fichier>Attendez que le serveur de développement recharge à chaud entre le basculement et la capture (--wait).
- Changement non commité :
- 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" - Lisez le composite, confirmez qu'il montre ce que vous prétendez, puis montrez-le dans votre réponse.
- Restaurez le basculement AVANT. Ne commitez ni ne déployez jamais avec le changement AVANT temporaire encore appliqué — revérifiez
git status/git diffavant de terminer.
Tests tactiles mobiles (
…
[tronqué pour la traduction]
