slimabbadi/ui-diff

Que fait ui-diff ?

Capturez une page avant de la modifier, capturez-la à nouveau après, et lisez ce qui a changé. La comparaison s'exécute localement : les pixels sont alignés comme un diff textuel, et chaque région modifiée est associée au changement DOM qui l'a provoquée. Le modèle ne paie une image que lorsque quelque chose de visible a changé. Même dans ce cas, l'image ne contient que les éléments modifiés, recadrés, dans une limite de tokens (400 par défaut ; deux captures pleine page coûtent généralement 2 000 à 5 000 tokens).

scripts/ se trouve à côté de ce fichier. Ci-dessous, $UI_DIFF représente node <chemin du répertoire de cette compétence>/scripts/ui-diff.mjs.

Configuration (une fois par machine)

1. Ajoutez agent-browser au PATH (npm i -g agent-browser, puis agent-browser install pour Chromium ; sur Linux agent-browser install --with-deps).
2. Installez la bibliothèque d'images : exécutez npm install dans <chemin du répertoire de cette compétence>/scripts.
3. Preuve facultative que la machine est prête : node <chemin du répertoire de cette compétence>/scripts/selftest/selftest.mjs. Elle se termine avec le code 0 lorsque tous les scénarios réussissent.

Étapes

1. Référence avant la première modification : $UI_DIFF baseline <url> --name <slug>. Utilisez un slug par page ou état, par exemple home ou checkout-mobile. Une référence charge la page deux fois pour apprendre quelles parties scintillent d'elles-mêmes.
2. Effectuez la modification.
3. Vérifiez : $UI_DIFF check <url> --name <slug>. Le code de sortie 0 signifie aucun changement visuel, 1 signifie qu'un changement a été trouvé, et 2 signifie une erreur.
4. Lisez d'abord le rapport textuel, puis décidez de l'image :
   • Chaque changement DOM listé est un changement intentionnel et le rapport affiche 0 inexpliqué : le texte est la preuve, ne l'ouvrez donc pas.
   • Le rapport liste les régions inexpliquées (U1.…), ou vous devez juger de l'apparence de quelque chose : ouvrez le chemin de l'image de révision que le rapport imprime. Ouvrez-la une fois, à la fin du travail, car une lecture d'image en cours de tâche est refacturée à chaque tour ultérieur.
5. Itérez en réexécutant check sur la même référence. Prenez une nouvelle référence uniquement lorsque vous acceptez l'état actuel comme nouvelle base.

L'étape est terminée lorsque le rapport liste exactement les modifications que vous avez intentionnelles, et que chaque région inexpliquée est soit comprise, soit corrigée.

Lecture du rapport

• Changements DOM sont les causes : étiquette d'élément, puis propriété avant -> après (couleurs en hexadécimal) ou texte "ancien" -> "nouveau". Les changements identiques sont regroupés (x3). Les changements qui ne touchent aucun pixel modifié sont simplement comptés.
• layout liste les conséquences : éléments déplacés de (dx,dy), éléments redimensionnés, et lignes de pixels qui ont glissé avec un contenu identique. Ce sont des effets attendus d'un changement de taille ou d'espacement, donc ils ne reçoivent pas d'image.
• régions de pixels place chaque zone modifiée dans l'une des quatre classes :
  • par changements DOM et par layout uniquement sont expliqués.
  • volatile signifie que la page a également changé là entre deux captures identiques.
  • inexpliqué signifie que des pixels ont changé et que rien dans le DOM n'en rend compte, par exemple canvas, images, ou pseudo-éléments. Les régions inexpliquées sont toujours dans l'image : ce sont là où les régressions se cachent.
• SUBTLE marque un changement trop faible pour être vu, comme un ajustement de token de design. Fiez-vous aux valeurs hexadécimales dans le texte plutôt qu'à l'image.
• Changements d'espacement (margin, padding, gap) apparaissent dans un recadrage seulement par rapport aux voisins. Le texte donne les valeurs exactes.

Bruit et options

• ⚠ la page a continué de changer entre les captures signifie du contenu en direct (animations, carrousels, minuteurs). Masquez-le avec --hide "<sélecteurs css>", ou limitez la vérification avec --selector <css> à l'élément que vous avez modifié.
• Les bannières de consentement et les widgets de chat doivent être dans --hide. Les éléments masqués sont toujours listés dans le rapport.
• Les valeurs par défaut du projet vont dans .ui-diff.json dans le répertoire de travail, par exemple { "hide": "#cookie-banner", "width": 1440 }. Les flags remplacent ces valeurs.
• Les éléments position:fixed sont épinglés où ils se trouvent sur la page, donc ils restent dans la comparaison.
• Les captures vont dans .ui-diff/ dans le répertoire de travail. Ce dossier s'ignore lui-même dans git.
• Exécutez $UI_DIFF sans arguments pour imprimer tous les flags.