2026 OpenClaw front-end en pratique :
Régression visuelle sur Mac distant — diff JSON, synthèse PR et webhook

Que la capture parte d’une Storybook build, d’une suite Playwright ou d’un script CLI dédié, la CI doit produire deux choses : un code de sortie explicite lorsque des snapshots diffèrent, et un identifiant de build retourné par l’outil ou son API — pas seulement une page web. Stockez cet identifiant dans une variable du type VISUAL_BUILD_ID et archivez-le à côté du SHA Git sous .openclaw/reports/${GIT_SHA}/ pour que le même chemin serve sur le runner Linux et sur le Mac loué où OpenClaw peut tourner plus longtemps.

Ne gravez pas dans le dépôt d’URL de type « build/12345 » pointant vers un domaine SaaS : elles changent, exigent une session, et rendent les commentaires PR inutilisables pour les automates et les contributeurs sans compte. Limitez-vous à l’ID, au nom du workflow et, si besoin, à la documentation officielle de l’API (chemin relatif dans votre wiki interne, pas un lien profond vers un tableau nécessitant le SSO).

Percy et Chromatic exposent des points d’accès HTTP authentifiés : listez les builds, puis les snapshots en échec, via des appels scriptables (curl ou client généré). Centralisez la base d’API et le préfixe de version dans des variables d’environnement (PERCY_API_BASE, CHROMATIC_PROJECT_TOKEN en lecture seule si le fournisseur le permet) afin de pouvoir basculer entre régions ou self-host sans modifier le script.

Pour un pipeline maison (pixelmatch, reg-cli, diff PNG sortant d’Odiff), faites écrire à votre wrapper un fichier unique visual_diff_report.json validé par jq empty en CI. L’important est que Percy, Chromatic et le comparateur interne convergent vers le même schéma cible via une fine couche d’adaptation (petit script Node ou jq) : une seule entrée pour OpenClaw.

Versionnez un schéma léger dans le dépôt, par exemple schemaVersion: 1, gitSha, provider (percy | chromatic | custom), puis un tableau failures[] avec : nom du snapshot ou de la story, viewport, pourcentage ou nombre de pixels divergents, sévérité normalisée, et chemin de composant ou label stable — jamais de chemin absolu du Mac. Les captures binaires restent dans les artefacts CI ; le JSON ne contient que des références (nom de fichier ou clé S3 interne) si vous devez les mentionner.

Deux canaux complémentaires : un commentaire Markdown sur la PR (GitHub, GitLab, Gitea — même principe d’API) pour les humains, et optionnellement un POST webhook vers votre passerelle (Slack signé, bus d’événements, OpenClaw orchestrateur) pour déclencher d’autres automatisations. Le webhook doit utiliser un secret partagé (signature HMAC du corps) et accepter un en-tête d’idempotence dérivé du SHA et du type de rapport pour survivre aux retries.

Le commentaire public doit rester court : statut global, trois à cinq puces sur les pires régressions, lien vers le run CI (URL de la plateforme Git, qui ne impose pas de compte SaaS visuel) plutôt que vers Percy ou Chromatic. Les captures sensibles restent dans les artefacts à accès restreint.

Pour la plateforme Git, appliquez le même principe de moindre privilège que pour un bot de résumé PR (un dépôt, écriture limitée aux pull requests, ou GITHUB_TOKEN du workflow avec permissions YAML explicites). Pour Percy ou Chromatic, créez un token de lecture dédié au CI, roté avec le même rythme que les autres secrets, sans droits d’administration de compte.

Encapsulez les appels réseau dans une fonction retry : au moins trois tentatives pour les erreurs 5xx et timeouts, délai initial de une seconde, facteur deux, plafond (par exemple trente secondes cumulées) et jitter pour éviter les rafales. Après échec définitif, faites échouer le job avec un message clair plutôt que de poster un commentaire vide ou tronqué.

Peut-on mélanger Percy sur une branche et diff maison sur une autre ? Oui, tant que l’adaptateur normalise vers le même schéma ; documentez le routage par variable VISUAL_PROVIDER.

Le Mac distant doit-il être la source de vérité ? Il excelle pour WebKit et charges longues ; la décision de merge peut rester sur un runner Linux si le JSON est identique — alignez versions Node et polices.

Comment éviter les fuites dans les logs CI ? Masquez les en-têtes d’autorisation, tronquez les corps de réponse dans les journaux, et validez en revue que le commentaire PR ne contient ni secret ni URL pré-signée.