Comment documenter un bug avec des captures d'écran pas à pas sur Mac

Un rapport de bug est utile lorsqu'une autre personne peut le reproduire sans vous poser de question. Les captures d'écran pas à pas éliminent la plupart des suppositions : le développeur voit chaque écran que vous avez vu, dans l'ordre.

Cet article décrit ce qu'un rapport reproductible doit contenir et comment capturer les étapes sur Mac avec Temposhot Action Capture.

Les exemples ci-dessous suivent un cas concret du début à la fin. Une application web affiche une liste de projets, et le renommage d'un projet ne met pas à jour la liste tant que la page n'est pas rechargée. Ce cas utilise un compte de test, nécessite 7 actions obligatoires pour reproduire le bug et échoue dans 3 essais sur 5.

Noter l'environnement en premier

De nombreux bugs n'apparaissent que dans une version, un navigateur ou un type de compte donné. Notez l'environnement avant de reproduire le bug, tant que la configuration est encore présente en mémoire.

Détail	Exemple
Version de l'application ou du site	Numéro de build indiqué dans la fenêtre About ou en pied de page
Version de macOS	Depuis About This Mac
Modèle du Mac et puce	Depuis About This Mac
Navigateur et version	Pour les applications web, depuis la page About du navigateur
Type de compte ou rôle	Free, paid, admin, viewer
Langue et région	Si le bug concerne le texte, les dates ou les devises
Date et heure	Avec le fuseau horaire, pour pouvoir rapprocher les journaux

Copiez les valeurs sous forme de texte. Une capture de la fenêtre About constitue une bonne preuve, mais les développeurs ne peuvent pas rechercher dans une image.

Relever les valeurs qui modifient le résultat

Tous les détails ne comptent pas pour chaque bug. Les valeurs à noter sont celles qui pourraient changer le résultat si elles étaient différentes. Pour le bug de renommage, la version du navigateur et le rôle du compte comptent, car la vue de liste est mise en cache différemment pour les rôles viewer et editor.

Un test rapide permet de voir quels détails comptent. Modifiez une seule valeur, par exemple le navigateur, puis recommencez. Si le bug disparaît, notez-le comme constat : « Se reproduit dans le navigateur de bureau, pas dans l'application mobile. »

Placer l'environnement en première page

Placez le bloc d'environnement en haut du rapport, au-dessus des étapes. Un développeur qui parcourt un outil de suivi lit le titre et les premières lignes avant de décider d'ouvrir les pièces jointes. Si l'environnement se trouve à la page 6 d'un PDF, le développeur peut essayer un autre navigateur et répondre « cannot reproduce ».

Joindre les journaux et la console sous forme de texte

Pour une application web, la console du navigateur affiche souvent une erreur au moment de l'échec. Copiez les lignes d'erreur sous forme de texte et collez-les sous le bloc d'environnement. Une capture de la console est un complément utile, mais le développeur a besoin du texte pour rechercher le message dans le code source.

Ne gardez que les lignes proches de l'échec. Un vidage de console de 400 lignes contenant une seule erreur pertinente oblige le lecteur à la chercher. Notez l'heure de l'erreur afin de la rapprocher du journal des tentatives.

Pour une application Mac, l'équivalent est un rapport de plantage ou une boîte de dialogue d'erreur. Copiez le texte de la boîte de dialogue à l'identique, y compris tout code d'erreur, et capturez la boîte de dialogue avec le raccourci manuel pendant l'exécution.

Indiquer le résultat attendu et le résultat réel

Deux phrases courtes encadrent l'ensemble du rapport :

• Attendu : « Après avoir sélectionné Save, le nouveau nom apparaît dans la liste. »
• Réel : « Après avoir sélectionné Save, la liste affiche toujours l'ancien nom. Le rechargement de la page affiche le nouveau nom. »

Décrivez ce que vous observez, pas ce que vous pensez être la cause. « La liste ne se rafraîchit pas » est une observation. « Le cache est cassé » est une supposition.

Rédiger des observations, pas des diagnostics

Un diagnostic dans un rapport de bug envoie le développeur au mauvais endroit. Si la vraie cause est un événement manquant et non un cache, « le cache est cassé » fait perdre du temps. Une observation est un élément que n'importe qui peut vérifier à l'écran.

Indiquez le contournement comme un fait, sans jugement de gravité. L'équipe qui trie le rapport décide de la gravité.

Reproduire à partir d'un point de départ connu

Un rapport qui commence par « ouvrez l'application » alors que vous étiez déjà au milieu d'une session masque la configuration réelle. Partez d'un état que n'importe qui peut atteindre : une connexion fraîche, un nouveau projet, une URL précise.

Reproduisez le bug au moins deux fois avant d'enregistrer. S'il n'apparaît que parfois, notez la fréquence, par exemple « 3 essais sur 5 ».

Préparer l'état initial

Pour le bug de renommage, l'état initial est une fenêtre de navigateur déconnectée, sur la page de connexion. La déconnexion préalable efface la session précédente, si bien que le développeur part du même point que la personne qui a signalé le bug.

Journaliser chaque tentative

Les bugs intermittents nécessitent un court journal des tentatives. Notez l'heure de chaque tentative et si elle a échoué, afin que le développeur puisse la rapprocher des journaux du serveur. Cinq tentatives suffisent généralement pour obtenir une fréquence.

Réduire le parcours au minimum

Le premier parcours qui montre un bug est rarement le plus court. Avant l'enregistrement, retirez une action à la fois et vérifiez si le bug apparaît toujours. Dans l'exemple, ouvrir les détails du projet avant de le renommer s'est révélé inutile, ce qui a ramené le parcours de 9 actions à 7.

Un parcours plus court aide de deux façons. Le développeur passe moins de temps à chaque reproduction, et moins d'actions signifient moins d'endroits où le lecteur peut prendre une autre voie. Arrêtez de réduire lorsque la suppression de toute action restante fait disparaître le bug.

Si le bug n'apparaît pas pendant l'exécution enregistrée, conservez tout de même l'enregistrement. Répétez les dernières actions et appuyez sur le raccourci manuel lorsque l'échec apparaît. Un enregistrement d'une exécution réussie reste utile lorsqu'il montre le parcours exact.

Capturer une capture d'écran par action requise

1. Ouvrir Action Capture

   Appuyez sur Command+3 et sélectionnez Start Action Capture. Choisissez Specific Window pour une seule application, ou Active Window si les étapes traversent plusieurs applications.

2. Effectuer les étapes

   Chaque clic accepté enregistre la fenêtre juste avant le clic, si bien que chaque page montre le contrôle avant que vous n'agissiez dessus.

3. Capturer l'échec

   Lorsque le mauvais résultat apparaît, appuyez sur Shift+Command+2 ou sélectionnez Capture now dans la barre flottante. L'écran d'échec apparaît souvent sans clic.

4. Terminer la capture

   Sélectionnez Finish capture. Le Document s'ouvre dans l'éditeur avec une page par étape.

Avec Parse clicked elements activé, les titres de page commencent par Click "[[element-name]]". Activez Show cursor on click captures et Mark clicked area sous Visual Annotations pour que chaque page montre l'endroit du clic. Si le bug se trouve dans Temposhot lui-même, activez Include toolbar in captures pour que la barre flottante apparaisse dans les étapes.

Configurer l'exécution une seule fois

Les réglages de Configure Action Capture sont enregistrés sur le Mac et réutilisés pour les exécutions suivantes. Une configuration prévue pour les rapports de bug reste en place pour le rapport suivant.

Choisissez Specific Window pour un bug situé dans une seule fenêtre de navigateur. Un clic sur une autre fenêtre est alors ignoré, sauf si Capture outside clicks est activé. Choisissez Active Window lorsque la reproduction passe d'une application à une autre, par exemple d'un lien dans un e-mail vers un navigateur.

Tenir l'exécution dans la limite d'étapes

Le forfait gratuit limite une exécution d'Action Capture à 5 étapes. Le bug de renommage nécessite 7 actions obligatoires plus l'écran d'échec, si bien qu'une exécution gratuite se met en pause après la cinquième étape. Les étapes enregistrées jusqu'alors restent dans l'exécution.

Deux solutions existent. Divisez la reproduction en deux exécutions à une coupure naturelle, par exemple après la connexion, puis ajoutez la seconde exécution au même Document. Ou activez Temposhot Pro, qui supprime la limite afin qu'une seule exécution couvre toutes les étapes.

Utiliser le clavier pendant l'exécution

Garder les mains sur le clavier pendant une reproduction évite des clics supplémentaires qui créent des pages parasites. Les raccourcis ci-dessous couvrent l'exécution et la modification qui suit.

Temposhot ignore les clics trop rapprochés. Un double-clic sur un élément de liste produit une seule étape, et non deux.

Lorsque l'exécution manque des clics

Une exécution qui enregistre moins d'étapes que prévu a une liste courte de causes. Vérifiez-les dans cet ordre avant d'enregistrer à nouveau.

• La barre flottante affiche Paused. Sélectionnez Resume capture ; les clics effectués pendant la pause ne sont pas enregistrés.
• La cible est Specific Window et le clic a atterri dans une autre fenêtre. Cliquez dans la cible, ou activez Capture outside clicks.
• Mouse click capture est réglé sur un mode qui exige ou ignore une touche maintenue. Remettez Capture every mouse click pour les rapports de bug.
• L'autorisation Accessibility manque. Screen Recording et Accessibility doivent afficher Granted dans Permissions Required.

Si les titres analysés affichent tous Click here, l'application cible expose peu de données d'accessibilité pour ses contrôles. Les étapes sont tout de même enregistrées ; seuls les titres doivent être réécrits à la main.

Ajouter du texte qui explique les changements d'état

Les captures d'écran montrent des écrans. Elles ne montrent pas toujours ce qui a changé entre eux. Utilisez Page description pour cela : « Le compteur devrait afficher 4 ici. Il affiche 3. »

Sur la page d'échec, dessinez un Rectangle (R) autour de la mauvaise valeur et ajoutez une étiquette Text (T) avec la valeur attendue. Supprimez les pages issues de clics parasites afin que la séquence ne contienne que les actions obligatoires. Réécrivez les titres en étapes simples, par exemple « Sélectionner Save ». Le guide de l'éditeur présente chaque outil et raccourci.

Nettoyer l'exemple

L'exécution enregistrée du renommage a produit 9 pages. Une page provenait d'un clic sur une zone vide de la liste, une autre d'un clic sur la barre d'adresse du navigateur. Ces deux pages ont été supprimées et la page d'échec issue du raccourci manuel a été conservée, ce qui donne 7 pages d'action et la page d'échec.

Les titres analysés ne sont qu'un point de départ. Click "Rename" devient « Sélectionner Rename dans le menu du projet », ce qui indique aussi au lecteur où se trouve le contrôle. Les pages pour lesquelles l'analyseur n'a trouvé aucun nom affichent Click here et doivent toujours être réécrites.

Modèles de description pour les changements d'état

Trois courts modèles couvrent la plupart des descriptions de page d'un rapport de bug. « Avant cette étape, la liste affiche 12 projets » enregistre une valeur de départ. « Attendre 2 secondes après la saisie » enregistre une temporisation que la capture d'écran ne peut pas montrer. « Ici, la liste devrait afficher Q3 Budget » enregistre l'état attendu sur la page où l'échec se produit.

Limitez chaque description à une ou deux phrases. Les descriptions longues repoussent la capture d'écran plus bas dans le PDF, et lorsque les descriptions sont réglées sur Before image, le lecteur voit d'abord le texte.

Annoter la page d'échec

La page d'échec porte le plus d'informations, elle reçoit donc le plus d'annotations. Un rectangle autour de l'ancien nom et une étiquette de texte avec le nouveau nom suffisent en général. Plus de 3 annotations sur une même page rendent la mauvaise valeur plus difficile à trouver.

Utilisez Framing avec un niveau tel que Close (niveau 4) sur la page d'échec lorsque la liste est petite dans une grande fenêtre. L'image source reste inchangée, et Show full image la rétablit si le développeur a besoin du contexte complet.

Protéger les informations privées

Les rapports de bug sont copiés dans des outils de suivi, des fils de discussion et des tickets de fournisseurs. Considérez chaque capture d'écran comme publique au sein de votre organisation.

• Reproduisez le bug avec un compte de test et des données d'exemple lorsque c'est possible.
• Rognez les barres latérales, les onglets du navigateur et les notifications avec Framing (F) et Custom.
• Floutez les noms, adresses e-mail, jetons et identifiants avec Blur (B, Pro).
• Supprimez les jetons de session et les clés API de toute URL ou de tout texte de journal que vous collez.

Vérifier chaque page à la taille d'export

Un floutage qui masque une valeur sur le canevas à 50 pour cent de zoom peut rester lisible à taille réelle. Réglez Blur strength dans l'Object Inspector à une valeur où le texte est illisible ; la valeur par défaut est 12 sur une échelle de 2 à 80. Parcourez ensuite l'aperçu d'export avant l'envoi.

Les URL présentes dans la barre d'adresse du navigateur constituent une fuite fréquente. Un lien de partage ou un jeton de réinitialisation dans la barre est visible sur chaque page d'une reproduction dans le navigateur. Rognez donc la barre d'adresse avec le cadrage ou floutez-la sur chaque page.

Utiliser cette structure de rapport de bug

1. Titre : ce qui échoue, et où. « L'élément renommé ne se met pas à jour dans la vue liste. »
2. Environnement : les valeurs du tableau ci-dessus.
3. Étapes pour reproduire : numérotées, à partir d'un état connu.
4. Résultat attendu et Résultat réel.
5. Fréquence : toujours, ou à quelle fréquence.
6. Preuves : le guide de captures exporté, ainsi que les journaux ou erreurs de console en texte.
7. Contournement : s'il en existe un.

Exportez depuis le Document avec Export PDF pour une seule pièce jointe, ou avec More export formats pour les pages PNG que les outils de suivi affichent en ligne. Les noms de fichiers d'image suivent les titres de page. Le guide d'export répertorie tous les formats.

Choisir l'export selon l'outil de suivi

Les outils de suivi n'affichent pas les pièces jointes de la même manière. Les pages PNG en ligne conviennent lorsque l'outil prévisualise les images dans le corps du ticket, car le développeur lit les étapes sans ouvrir de fichier. Un PDF unique convient lorsque l'outil ne fait que lister les pièces jointes, ou lorsque le rapport part chez un prestataire externe.

Le format ZIP package contient les pages PNG générées et un fichier document.json dans une seule archive. Il convient à un ticket chez un prestataire qui n'accepte qu'un fichier et qui a besoin à la fois des images et du texte des pages.

Exemple de rapport complété

Le rapport de renommage se présente ainsi dans l'outil de suivi. Le titre est « Le projet renommé conserve son ancien nom dans la liste Projects jusqu'au rechargement. » Le bloc d'environnement indique le numéro de build, la version de macOS, la version du navigateur, le rôle editor et les heures des tentatives, de 14:02 à 14:20.

Les étapes forment 7 lignes numérotées, de « Se connecter en tant que qa-editor » à « Fermer la boîte de dialogue de renommage ». Le résultat attendu et le résultat réel sont les deux phrases vues plus haut, et la fréquence est « 3 essais sur 5 ». La preuve est un PDF de 8 pages, et le contournement est « Recharger la page ».

Le PDF utilise les réglages d'export par défaut : A4, Landscape, page de couverture activée, numéros d'étape activés, numéros de page activés, descriptions avant l'image. La personnalisation de ces réglages nécessite Temposhot Pro ; les valeurs par défaut conviennent déjà à un rapport de bug.

Écrire aussi les étapes en texte

Collez les étapes numérotées en texte dans le corps du ticket, même lorsque le PDF les contient déjà. Le texte peut être recherché, cité dans les commentaires et copié dans un cas de test. Les captures servent alors de preuve pour chaque étape au lieu d'être la seule trace de celle-ci.

Tester le rapport avant de l'envoyer

Relisez le rapport du début à la fin comme si vous n'aviez jamais vu le bug. Mieux encore, demandez à un collègue de le suivre sur son Mac. S'il reproduit le bug sans poser de question, le rapport est prêt.

Lacunes courantes relevées lors d'un essai à blanc

Un essai à blanc mené par un collègue relève en général l'une de trois lacunes. L'état initial manque, par exemple un projet qui doit déjà exister. Une étape se produit sans clic, comme un raccourci clavier, et n'a pas de page. Ou l'échec dépend du temps, par exemple la sélection de Save moins de 2 secondes après la saisie.

Ajoutez l'état manquant à la première étape, ajoutez une page pour l'action au clavier avec le raccourci manuel, et indiquez la temporisation dans la description de la page. Relancez ensuite l'essai à blanc.

Conserver le Document source

Le Document reste modifiable après l'export. Si le développeur demande un écran supplémentaire, ouvrez le Document, ajoutez la page avec Capture new images…, puis exportez à nouveau. Les fichiers déjà exportés ne se mettent pas à jour d'eux-mêmes.

Questions fréquentes

Un rapport de bug doit-il contenir une vidéo ou des captures d'écran ?

Les captures d'écran conviennent à la plupart des bugs et sont faciles à parcourir et à annoter. La vidéo aide pour les problèmes de temporisation et les animations. Voir comparaison entre le guide de captures d'écran pas à pas et l'enregistrement d'écran.

Combien de captures d'écran un rapport de bug nécessite-t-il ?

Une par action obligatoire, plus l'écran d'échec. Supprimez les pages qui ne modifient pas le résultat.

Où sont stockées les captures après l'envoi du rapport ?

Le Document reste sur votre Mac. Temposhot ne propose pas de lien hébergé ; joignez donc les fichiers exportés au suivi des bugs ou au ticket.

Que faire si le bug nécessite plus de 5 étapes avec le forfait gratuit ?

L'exécution se met en pause à la limite d'étapes et conserve les étapes enregistrées jusqu'alors. Divisez la reproduction en deux exécutions et ajoutez-les au même Document, ou utilisez Temposhot Pro pour enregistrer au-delà de la limite.

Peut-on capturer un bug qui apparaît sans clic ?

Oui. Appuyez sur le raccourci de capture manuelle, Shift+Command+2 par défaut, lorsque le mauvais état apparaît. L'étape est enregistrée sans clic et reçoit le réglage du marqueur de clic s'il est configuré.

Transformer vos clics en guide clair étape par étape

Action Capture enregistre les étapes de reproduction au fur et à mesure que vous les effectuez, avec des marques de clic et des titres provisoires. Téléchargez Temposhot et joignez votre prochain rapport de bug sous forme de guide ordonné.