Captures d'écran dans une PR

Les captures d'écran dans une PR constituent une preuve de QA. Chacune montre ce que le produit réel affiche à un endroit donné, cadrée de sorte qu'un relecteur qui n'a jamais ouvert la page puisse voir ce qui a changé.

Étape 1 : Lister les emplacements

Énumère tous les endroits du produit que le diff affecte : chaque page, tiroir, modal ou widget qui affiche un composant modifié, identifiés en traçant ses appelants et consommateurs. Ajoute ensuite les états que le changement affecte à chacun d'eux, tels que chargement, erreur, vide, survol, sélectionné, menu ouvert, développé, défilé, viewport étroit et thème clair ou sombre.

Ne groupe jamais les surfaces en une seule ligne : par exemple, « GridEditable, comme dans Discover, dashboards et insights » représente trois lignes.

Étape 2 : Capturer depuis le produit réel

Règle	Détail
Build réel uniquement	Capture d'écran de l'app en exécution sur la branche PR pour « après » et sur la branche de base pour « avant ». Ne capture jamais une story, une page fictive ou un harness construit pour la PR, sauf si le changement porte sur cette story.
Aucun changement injecté	N'injecte jamais de CSS ou de modification du DOM pour imiter le changement. Le stubbing des réponses API est acceptable ; le code frontend doit être le code réel.
Remplir les données manquantes	Si un état nécessite des données qu'aucun compte ne possède, crée-les dans un environnement local. Ne signale pas un emplacement comme impossible à capturer jusqu'à ce que le remplissage ait été tenté, puis indique exactement ce qui a échoué.
Cadrage identique	Capture la même région aux mêmes dimensions pour les deux images d'une paire, même si un état est plus grand. Émule un viewport fixe au lieu de redimensionner la fenêtre du navigateur.
Contexte	Conserve le titre ou le libellé qui nomme l'élément, les lignes ou contrôles à proximité, et un peu de padding de chaque côté. Pour un état de survol, focus ou menu ouvert, garde le déclencheur et l'overlay dans un seul cadre. Quand le bug n'a sens que dans sa page, affiche plus de la page.
Pas de bandes vides	Recadre le chrome du navigateur, la navigation de l'app et les régions que le changement n'affecte pas. Pour les mises en page pleine largeur, réduis le viewport au lieu de laisser un espace blanc important à côté du contenu court.

Étape 3 : Redacter et auditer

Flou uniquement les valeurs privées : emails, noms d'utilisateur, noms et slugs de clients ou d'organisations, ID et noms d'hôtes internes. Garde lisibles les clés, libellés et valeurs non sensibles, comme browser.name → chrome.
Peins chaque région avant de la flouter pour que le flou ne puisse pas être inversé. N'utilise jamais de boîtes noires ou sombres solides, et ne flou jamais de tables ou lignes entières.
Lis chaque image avant de la télécharger et vérifie les credentials : tokens, en-têtes d'authentification, cookies, URLs signées, clés secrètes et endpoints webhook. Supprime les fuites réelles. Ne traite pas un DSN public client comme une fuite.

Étape 4 : Choisir la forme du tableau

Changement	Forme
Changement visuel de l'UI existante	Tableau Changed, plus un tableau Unchanged pour les emplacements que le diff affecte et qui affichent la même chose.
Nouvelle page ou fonctionnalité	Pas d'avant/après. Quelques captures d'écran « après », chacune introduite par une brève phrase. Quand la nouvelle UI apparaît à plusieurs emplacements, utilise un tableau `Location \\| Screenshot` à la place.
Alternatives sans « avant », comme les traitements prototype ou options de conception	Tableau `Treatment \\| Screenshot`, une ligne par alternative.
Un changement qui diffère selon le thème	Ajoute une ligne clair et une ligne sombre pour chaque emplacement, comme `Explore › Logs, dark`. Pour la nouvelle UI, utilise des colonnes `Light \\| Dark` à la place.

Diff pixel chaque paire avant/après. Déplace une paire sans différence visible, y compris le bruit d'anti-crénelage, vers Unchanged avec une seule image. Laisse de côté un tableau qui serait vide.

**Changed**

| Location | Before | After |
| --- | --- | --- |
| Explore › Logs | ![Explore › Logs before](./shots/logs-before.png) | ![Explore › Logs after](./shots/logs-after.png) |
| Explore › Logs, loading | ![Explore › Logs, loading before](./shots/logs-loading-before.png) | ![Explore › Logs, loading after](./shots/logs-loading-after.png) |

**Unchanged**

| Location | Before & After |
| --- | --- |
| Trace view › Logs | ![Trace view › Logs](./shots/trace-logs.png) |

Règles de formatage :

Nomme la première colonne Location, ou Treatment pour les alternatives. Ne laisse jamais son en-tête vide.
Écris chaque emplacement comme un breadcrumb › de ce que le lecteur clique, puis une virgule et l'état : Monitors › cron monitor details › Check-Ins, loading.
Utilise uniquement les colonnes montrées ci-dessus. N'ajoute jamais de colonne « What changed » ou notes ; les captures d'écran montrent le changement.
Donne à chaque image un alt text nommant sa ligne et son côté, comme Explore › Logs before.
Étiquette les tableaux avec des lignes en gras **Changed** et **Unchanged**. N'ajoute pas une phrase d'introduction décrivant où ou comment les captures d'écran ont été prises.
Utilise les tableaux Markdown par défaut, car gh --attach réécrit uniquement les références d'images Markdown. Bascule vers un tableau HTML uniquement quand les cellules doivent s'étendre sur plusieurs lignes, comme une ligne clair et une ligne sombre sous un emplacement (Location | Theme | Before | After avec rowspan="2" sur la cellule d'emplacement). N'ajoute pas d'attributs align.

Étape 5 : Télécharger avec gh

gh pr create, gh pr edit, gh pr comment, et les commandes gh issue correspondantes acceptent --attach '<path>#<alt text>' (gh 2.99.0+). Si gh rejette le drapeau, demande à l'utilisateur de le mettre à jour. Ne pousse pas de branches asset, ne valide pas d'images et ne télécharge pas via la boîte de commentaires du navigateur.

Écris le fichier body avec des références d'images Markdown relatives, puis passe les mêmes chemins à --attach. gh télécharge chaque fichier et réécrit la référence correspondante par l'URL téléchargée sur place :

gh pr edit 123 --body-file pr-body.md \
  --attach './shots/logs-before.png' --attach './shots/logs-after.png'

Comportement	Détail
Chemins	Résolus par rapport au répertoire courant et doivent correspondre exactement aux références du body.
Pièces jointes non référencées	Sont ajoutées à la fin du body comme `![alt](url)`.
Sans drapeau body	`gh pr edit --attach` conserve le body existant et ajoute les images.
Tableaux HTML	`<img src="./x.png">` n'est pas réécrit. Attache d'abord, copie les URLs ajoutées dans les tags `<img>`, supprime les lignes ajoutées, puis écris le body final avec `--body-file`.

Avant d'écrire un body que l'utilisateur peut avoir modifié, récupère-le à nouveau et compare-le avec la version que tu as lue en dernier. Garde le libellé et les modifications de tableau de l'utilisateur, remplace uniquement tes lignes et URLs, et conserve les fins de ligne du body. Supprimer une image du body ne supprime pas le fichier téléchargé.

Étape 6 : Garder les captures d'écran à jour

Quand un commit ultérieur change ce qu'une capture d'écran montre, reprends les paires affectées, vérifie à nouveau quelles paires appartiennent à Changed et Unchanged, et mets à jour le body sans attendre d'être demandé.

pr-screenshots