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
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 conserverHANDTEST_ROOTentre les commandes : définissez-le dans la même commande.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.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.- 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. Ensuiteboard --before <png> --after <png> --title ... --caption ... --out <dossier>/<id>_<topic>_BEFORE_AFTER.png. - 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 :
archivele 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,archivele dossier, et revenez à l'étape 3. La refonte crée les mêmes noms de fichiers ; l'ancienne prise passe dansprevious/. Quandinita écrit le nouveau README.md, copiez les lignes qui tiennent toujours depuisprevious/<stamp>_README.md;pairréé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.