Communitygithub.com

hand-test

Testez manuellement un changement que les gens voient, entendent ou ressentent. AVANT et APRÈS sont lus côte à côte dans une vidéo et un tableau, l'agent les vérifie et le changement attend l'approbation d'une personne. Utilisez-le lorsque l'utilisateur demande un test manuel, une vidéo avant/après, une preuve visuelle pour une PR, un rapport de version de ce qui a changé pour les utilisateurs, ou dit « montre-moi ce qui a changé ».

Qu'est-ce que hand-test ?

Ce skill implémente un processus rigoureux de test manuel pour les changements visuels, auditifs ou tactiles dans une application. Il guide l'agent à travers sept étapes : classer le changement, planifier un script de test reproductible, enregistrer les états AVANT et APRÈS, générer une vidéo et un tableau comparatifs, effectuer un auto-examen, remettre les preuves à un approbateur humain, et enregistrer le verdict. Le skill utilise un script Python (`scripts/handtest.py`) avec des dépendances comme ffmpeg et Pillow. Il prend en charge les dépôts avec des PR et nécessite un fichier de configuration `docs/agents/hand-test.md`. Le résultat est un dossier de preuves contenant une vidéo synchronisée, un tableau avant/après, et des captures d'écran, tout étant vérifié automatiquement avant soumission humaine. Il est idéal pour les équipes de développement qui veulent valider des changements d'interface utilisateur, de comportement, de timing ou de design avec une preuve visuelle claire et minimiser les malentendus.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Test manuel (Hand test)

Les tests prouvent ce que le code fait. Un test manuel prouve qu'une personne obtient ce qui était prévu. Pour chaque changement qu'une personne peut voir, entendre ou ressentir, vous créez une preuve qu'un étranger peut juger en une minute, à froid : une vidéo et un tableau, AVANT (badge rouge) à côté d'APRÈS (badge vert), au même endroit et avec la même action, de sorte que seul le changement diffère. Le changement reste non fusionné jusqu'à ce que l'approbateur dise OK.

Les faits du projet se trouvent dans docs/agents/hand-test.md dans le dépôt de l'utilisateur : comment obtenir AVANT, comment piloter et capturer cette surface, les règles de l'appareil, où vont les preuves, qui approuve, et ce que font OK et Pas OK. Si ce fichier manque, suivez d'abord SETUP.md.

L'outil est scripts/handtest.py. Exécutez-le avec uv run <dossier de ce skill>/scripts/handtest.py <commande> ; --help sur n'importe quelle commande liste ses options. Il nécessite ffmpeg et ffprobe dans le PATH ; uv apporte Pillow. Sans uv, créez un environnement virtuel en dehors du dépôt (python3 -m venv <dir> && <dir>/bin/pip install pillow) et exécutez l'outil avec <dir>/bin/python.

1. Classer le changement

Ajoutez une section ## Hand test dans le corps de la PR (ou là où le changement est décrit) :

  • yes: <quoi regarder> pour tout ce qu'une personne voit, entend ou ressent : UI, comportement, timing, son, texte, design.
  • no: <pourquoi rien n'est vu, entendu ou ressenti> pour l'outillage, la construction, les tests, la documentation, ou un refactor avec le même résultat.

En cas de doute, c'est yes.

Fait quand : la section est présente. Un no termine le skill.

2. Planifier la prise

Nommez le moment : l'étape unique où le changement se manifeste. Quand le changement est à l'écran dès la première image (une couleur, un libellé, une disposition), le moment est l'arrivée de l'écran, ou la première étape après celui-ci.

Écrivez les étapes comme un script qui pilote l'application réelle, identique pour les deux côtés (commandes par surface dans CAPTURE.md) :

  • Entrée réelle via l'UI propre de l'application : un raccourci de test saute le code qu'une personne frappe.
  • Trouvez les éléments par leur libellé ou leur rôle, jamais par coordonnées : le déplacement de la disposition est souvent le changement lui-même.
  • Attendez un état réel (un libellé affiché, une requête terminée) avant le moment, jamais sur un minuteur fixe. Tenez un temps fixe après lui.
  • Même appareil, taille de fenêtre, langue, données et état de départ des deux côtés.
  • Remettez tout en place dans un finally.

AVANT vient du véritable ancien état : la construction du commit de base, ou le changement désactivé à l'exécution. Pas de modifications de fichiers sauvegardés pour cela.

Si le changement est une question d'espace, de temps ou de sensation que personne n'a tranchée avant la construction (à quel point c'est grand, rapide, comment ça doit se sentir), arrêtez-vous et dites-le à l'utilisateur. Cela appartient à une esquisse interactive avant la construction ; un test manuel vérifie une décision, il n'en prend pas une.

Fait quand : le script s'exécute à sec (rien enregistré) sur AVANT et sur APRÈS, trouve chaque élément (ou atteint chaque état, là où seules des images fixes peuvent être prises), et laisse l'appareil et l'arbre de travail tels quels, avec la somme de contrôle de l'arbre égale avant et après.

3. Enregistrer les deux côtés

Enregistrez AVANT, puis APRÈS, avec le même script. Respectez les règles de l'appareil du projet : touchez uniquement l'application testée, ne désinstallez rien, ne modifiez aucun paramètre système, et n'envoyez d'entrée que lorsque l'application testée est au premier plan.

Fait quand : deux enregistrements bruts existent, chacun montre le moment, et la somme de contrôle de l'arbre de travail correspond toujours.

4. Créer la preuve

  1. init --out "$HANDTEST_ROOT/<groupe>" --id <N> --topic <kebab-case> --title "<mots simples>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>". Le groupe, OK et Pas OK viennent du fichier projet. Votre shell peut ne pas conserver HANDTEST_ROOT entre les commandes : définissez-le dans la même commande.
  2. find-change <raw> --from <s> --to <s> sur chaque enregistrement autour du moment. Le temps de synchronisation est l'image où l'image change, pas le temps enregistré d'une étape.
  3. pair --before <raw> --after <raw> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <dossier>/<id>_<topic>.mp4. Il remplit les temps de la vidéo dans README.md et PACKAGE.md, et imprime où le moment tombe dans la vidéo.
  4. Une image fixe par côté, un battement après le moment, à partir des enregistrements bruts : stills <raw> --at <s> --out <scratch>/before, la même chose pour APRÈS. Il imprime chaque fichier. Ensuite board --before <png> --after <png> --title ... --caption ... --out <dossier>/<id>_<topic>_BEFORE_AFTER.png.
  5. Remplissez chaque marque <fill in: ...>. Les règles pour les mots et les nombres sont dans EVIDENCE.md.

Fait quand : check <dossier> imprime "prêt pour une personne".

5. Passage du relecteur

Avant qu'une personne ne le voie, examinez-le vous-même comme le ferait un étranger. Extrayez des images fixes de la vidéo deux fois : stills <video> --every 1 --out <scratch>, puis stills <video> --at <t-0.5> <t> <t+0.5> --out <scratch>, où t est le temps du moment dans la vidéo, pas dans un enregistrement brut (pair l'a imprimé ; handtest.json le contient comme video.change_at). Regardez chaque image fixe et le tableau.

  • Chacune doit montrer ce que sa légende dit de regarder. Couvert, vide, le mauvais état, la mauvaise langue, une superposition sur le changement : archive le dossier et enregistrez à nouveau à partir de l'étape 3. Enregistrez à nouveau plutôt que d'expliquer une mauvaise image dans le README.
  • Un nombre doit correspondre à l'image. Quand ils diffèrent, le nombre est faux : trouvez pourquoi.
  • Un test vert avec une image fausse est une constatation. Signalez-le à l'utilisateur comme un bogue.

Fait quand : chaque image fixe et le tableau montrent ce que les légendes prétendent, et chaque nombre dans le README correspond à l'image.

6. Remettre

Placez le dossier là où vont les preuves du projet. Postez PACKAGE.md là où le fichier projet le dit, en nommant uniquement le chemin relatif du dossier, jamais un compte ou un chemin absolu. Complétez la ligne yes de la PR avec ce chemin et qui il attend (le formulaire se trouve dans "La section PR" dans EVIDENCE.md). Demandez à l'approbateur. Le changement reste non fusionné (une PR en brouillon là où il y a des PR) pendant que le test manuel est ouvert.

Fait quand : le package est posté, la ligne de la PR nomme le dossier, l'approbateur est demandé, et rien du changement n'a été fusionné.

7. Enregistrer le verdict

Le verdict appartient à l'approbateur. N'enregistrez jamais un OK qu'il n'a pas donné.

  • OK : verdict <dossier> --ok --by "<qui>" (il refuse un dossier qui échoue à check), puis faites ce que le fichier projet dit que OK fait (généralement : marquer la PR comme prête).
  • Pas OK : verdict <dossier> --not-ok --by "<qui>" --note "<ce qu'ils ont dit>". Corrigez-le sur la même branche, archive le dossier, et revenez à l'étape 3. La refonte crée les mêmes noms de fichiers ; l'ancienne prise passe dans previous/. Quand init a écrit le nouveau README.md, copiez les lignes qui tiennent toujours depuis previous/<stamp>_README.md ; pair réécrit les temps.

Fait quand : handtest.json contient le verdict de la personne et le suivi correspond.

Une version

Gardez chaque dossier de test manuel sous un dossier de groupe par version, puis exécutez report <groupe> --title "<version>". Il écrit REPORT.md et un fichier index.html autonome, tests manuels en attente en premier. Voir EVIDENCE.md.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés