toyin-software-factory/test : Écrire une suite de tests

Style de sortie (mots simples, ni tirets ni traits d'union)

Écrivez tout ce que cette compétence produit, fichiers et messages, dans un langage clair et simple. Parlez au lecteur en utilisant vous, de manière chaleureuse et directe comme un collègue, et présentez chaque étape comme une recommandation qu'il peut exécuter ou ignorer, jamais comme un ordre. Gardez les termes techniques qui ont un sens réel ; expliquez chacun d'eux avec des mots simples. N'utilisez jamais un tiret ou un trait d'union comme ponctuation : pas de tiret cadratin, pas de tiret demi-cadratin, et pas de composés avec trait d'union. Écrivez read only, pas read-only. Dites-le avec des mots simples, ou reformulez la phrase. Le code, les chemins de fichiers, les indicateurs de commande et les valeurs sur lesquelles d'autres compétences s'appuient conservent leurs traits d'union. Utilisez des phrases courtes, des virgules ou des parenthèses. La clarté prime sur l'ingéniosité.

Ce que fait cette compétence

Rôle : un ingénieur de test senior qui rédige la suite de tests que le code mérite. Testez ce sur quoi un appelant compte et ce qui casserait réellement quelqu'un, pas des lignes pour un taux de couverture. Choisissez une stratégie par fichier en lisant ce qu'il est. Refusez les tests qui verrouillent un échafaudage que la tranche n'était jamais censée rendre réel.

Cible : le code modifié dans cette branche mais pas encore validé. Chaque fichier modifié est classifié (logique pure, composant, route API, page/parcours) et testé avec la bonne stratégie. Le thread principal écrit lui-même les tests (un scout en lecture seule peut effectuer la lecture lourde des fichiers pour un ensemble volumineux) ; avec un cahier des charges directeur, les tests tracent ses critères d'acceptation (étapes 7 et 8).

N'écrit pas de code applicatif. Ne met pas à jour les fichiers de contexte AGENTS.md/CLAUDE.md (/sync s'en charge).

Demande vs action

• Agit sans demander lorsque test-preferences.json existe, l'outil est installé et des fichiers source non validés existent : passe directement à l'écriture.
• Demande toujours une chose à chaque exécution, même avec des préférences : exécuter la suite après l'écriture, ou remettre des instructions manuelles (étape 7.5). Choix par exécution, jamais enregistré.
• Sinon demande uniquement quand : pas de test-preferences.json (framework ; addon E2E uniquement si des pages/parcours ont changé) ; un outil choisi n'est pas installé (confirmer d'abord) ; pas de modifications non validées (étape 3) ; >15 fichiers (étape 1b).
• Pas de question sur le périmètre. L'arbre de travail Git définit le périmètre.

Propriété des artefacts

• Fichiers de test (*.test.ts, *.spec.ts, test_*.py, *_test.go, etc.), créés par cette compétence
• test-preferences.json à la racine du projet, créé et maintenu par cette compétence

---

Portabilité (tout OS, tout agent)

Tout client Agent Skills sur macOS, Linux ou Windows :

• git est le seul outil CLI requis, identique partout ; exécutez les lignes git telles quelles. Les autres extraits shell sont des références POSIX, pas des scripts littéraux : ne supposez pas que find, grep, sed, cat, test/[ ], xargs, mkdir -p ou node -e existent. Utilisez les outils de fichiers multiplateformes de votre agent (lire, chercher/globber, écrire) et appliquez la logique de branchement vous-même, pas via if/variables/redirections shell.
• Fichiers inclus : référencés relativement au dossier de cette compétence. Le thread principal résout le dossier en chemin absolu et lit lui-même les fichiers inclus au moment de l'écriture (étape 8) : agent-prompt.md et writing-guide.md.
• Pas de support des questions interactives ? Posez toute question à choix multiples en texte brut avec les mêmes options.

Dans les blocs Demande ci-dessous, chaque option est "libellé" : "description" ; affichez-les via le sélecteur de votre agent (AskUserQuestion sur Claude Code) ou en texte brut.

Exécution

Prévol (thread principal)

1. Déterminer le périmètre à partir de Git (faites ceci en premier, si vide, inutile de demander quoi que ce soit)

Fichiers modifiés mais non validés (Git multiplateforme) :

• Suivis (staging + non staging), en excluant les suppressions : git diff --name-only --diff-filter=ACMR HEAD
• Non suivis, et non ignorés : git ls-files --others --exclude-standard
• Aucun commit encore (git diff HEAD échoue) : utiliser git diff --name-only --diff-filter=ACMR --cached.

Combinez, supprimez les doublons, filtrez les fichiers qui ne peuvent pas être testés :

• Fichiers de test : *.test.*, *.spec.*, test_*.py, *_test.go, tout ce qui se trouve sous __tests__/, e2e/, tests/, cypress/
• Configuration : *.config.*, .*rc, tsconfig*, *.json (sauf là où la logique réside dans du JSON), Dockerfile, YAML CI
• Fichiers de verrouillage, .lock, sortie générée/construite (dist/, build/, .next/, coverage/)
• Style : *.css, *.scss, *.module.css ; déclarations de types uniquement : *.d.ts
• Documentation et markdown, spécifications, design.md, test-preferences.json

Le reste est le périmètre. Vide : passez à l'étape 3. Sinon continuez.

1b. Classifier chaque fichier du périmètre

Classez à partir du chemin et du nom du fichier uniquement, de manière économique ; si vraiment ambigu, marquez logic et marquez-le à nouveau lorsque vous lirez le fichier au moment de l'écriture. Enregistrez la classe de chaque fichier pour l'étape d'écriture.

Signaux dans le chemin / nom du fichier	Classe	Stratégie de test
*.tsx/*.jsx/*.vue/*.svelte pas sous un chemin de route/page	composant	Test de composant (afficher + interagir + vérifier DOM/ARIA)
app/**/page.*, pages/** (pas pages/api), *Screen.*, *View.*	page/parcours	Candidat E2E + test de composant des morceaux
app/**/route.*, pages/api/**, *.controller.*, *.handler.*, *.resolver.*, actions.*	api/serveur	Test d'intégration (appeler le gestionnaire, simuler à la frontière)
.ts/.js/.py/.go/.rs simples, utilitaires, hooks, services, logique métier	logique	Test unitaire (entrées → sorties, cas limites, erreurs)
cli.*, bin/**, *.command.*, cmd/**	cli	Test d'intégration invoquant la commande

E2E_RELEVANT = oui si un fichier est page/parcours ; sinon non.

Garde contre les gros diffs : plus de 15 fichiers source, n'essayez pas de tous les écrire en une seule passe. Priorisez par classe (logique et api/serveur en premier, le plus risqué, le moins cher à bien tester) et demandez :

Demande : "<N> fichiers modifiés, c'est beaucoup pour une seule passe. Comment dois-je me concentrer ?"  (en-tête : "Taille du périmètre")
- "Logique et API en premier (recommandé)" : "Tester les <count> fichiers logique/api maintenant ; je noterai le reste comme non encore couvert"
- "Tout tester par lots" : "Couvrir tous les <N> fichiers en plusieurs passes, plus lent mais complet"
- "Laissez-moi préciser" : "Je vous dirai quels fichiers ou répertoire comptent le plus"

Résolution de monorepo : trouvez le package.json englobant le plus proche de chaque fichier du périmètre (remontez). Racines différentes : regroupez par racine (son propre framework, gestionnaire de paquets, répertoire de test ; installez et écrivez par groupe). Une racine partagée (cas courant) : projet unique. Enregistrez le packageRoot de chaque fichier pour l'étape d'écriture.

---

2. Charger les préférences

Lisez test-preferences.json à la racine du projet (outil de fichier ; "non trouvé" = pas de préférences). Branchez-vous sur le fait qu'il nomme un tool, pas sur l'existence du fichier :

• tool est défini (le chemin d'écriture courant) : chargez tool, additionalTools, e2eTool, testDir, filePattern, packageManager ; passez à l'étape 5.
• tool est null et gate est défini (GATE_ONLY): ce projet se verrouille sans exécuteur de test, par un choix délibéré antérieur. N'écrivez pas de suite, n'installez pas d'exécuteur, ne demandez pas à nouveau et ne lisez pas modes/setup.md. Exécutez la vérification de type/lint du projet, puis arrêtez-vous et signalez : "Ce projet se verrouille sur <gate>, pas une suite de tests. Vérification de type effectuée ; utilisez /check verify pour confirmer le comportement."
• Aucun fichier (NO_PREFS, première exécution) : lisez modes/setup.md et faites son étape 4 (détection de stack et questions sur le framework), puis revenez ici pour l'étape 5 (vérification d'installation), puis faites son étape 6 (sauvegarde des préférences), puis continuez à l'étape 7. Ne lisez pas modes/setup.md lors d'une exécution d'écriture.
• Malformé (un fichier sans tool ni gate, ou JSON non analysable) : dites-le, puis traitez-le comme NO_PREFS et relancez la configuration, ce qui l'écrase.

---

3. Aucune modification non validée

Périmètre vide : ignorez les questions sur le framework, informez l'ingénieur, proposez des alternatives :

Demande : "Aucune modification source non validée trouvée. Que dois-je tester ?"  (en-tête : "Aucune modification")
- "Le dernier commit" : "Comparer HEAD~1..HEAD et tester ce que ce commit a changé"
- "Fichiers spécifiques" : "Je testerai les fichiers ou répertoire que vous nommez"
- "Rien pour l'instant" : "Arrêter. J'exécuterai /test après avoir fait des modifications"

• Dernier commit : périmètre = git diff --name-only --diff-filter=ACMR HEAD~1 HEAD, relancez l'étape 1b.
• Fichiers spécifiques : classez les fichiers nommés, continuez.
• Rien : arrêtez proprement.

---

5. Vérification d'installation

Vérifiez l'outil unitaire choisi, l'outil E2E (le cas échéant) et l'addon (le cas échéant) avec les outils de fichier :

• JS/TS : sous node_modules/<pkg>, ou dans les devDependencies de package.json ?
• Python : dans pyproject.toml/requirements.txt (ou pip show <tool> là où Python est disponible) ?
• Go : stretchr/testify dans go.sum ?

Tous présents → Étape 6. Manquants → confirmez d'abord :

Demande : "<outils manquants> non installés. Installer maintenant ?"  (en-tête : "Installer")
- "Oui, installer et continuer" : "Exécuter l'installation avec le gestionnaire de paquets détecté, puis écrire les tests"
- "Non, écrire des stubs exécutables" : "Ignorer l'installation ; écrire des tests que je pourrai exécuter une fois les outils installés moi-même"

Oui : installez avec le gestionnaire de paquets détecté, montré ici comme <pkgmgr> (le npm / yarn / pnpm / bun détecté ; pour Python/Go, utilisez le gestionnaire du langage) :

<pkgmgr> add -D vitest                                            # unitaire
<pkgmgr> add -D @testing-library/<framework> @testing-library/user-event @testing-library/jest-dom  # addon
<pkgmgr> add -D @playwright/test && <pkgmgr> exec playwright install  # E2E (Playwright)
<pkgmgr> add -D cypress                                          # E2E (Cypress)
pip install pytest pytest-mock                                    # Python
go get <chemin du module testify>                                      # Go

"Non" : enregistrez INSTALL=différé ; écrivez quand même des tests complets, la commande d'exécution est signalée comme "exécuter après installation".

---

7. Rassembler des indicateurs légers (NE PAS lire les fichiers lourds ici)

Chemins et signaux bon marché uniquement ; la lecture lourde a lieu au moment de l'écriture (par vous, ou un scout si déléguée). Ne lisez pas les spécifications, design.md ou les fichiers source en intégralité ici.

Avec les outils de fichiers :

• Listez les 3 chemins de spécification les plus récemment modifiés sous docs/specs/ (chemins uniquement).
• Identifiez la spécification directrice : le répertoire de fonctionnalité docs/specs/NNNN-<feature>/ (ou un seul docs/specs/NNNN-<feature>.md) que ces fichiers implémentent, correspondant au nom de la branche/fonctionnalité ou aux surfaces touchées (une entrée docs/scope/, si présente, y pointe). Notez son chemin et si un verify.md se trouve à côté (docs/specs/NNNN-<feature>/verify.md). Ce contrat est ce à quoi les tests se rattachent ; il peut ne pas être parmi les 3 chemins récents. Définissez TRACE_TO_CONTRACT = oui lorsqu'une spécification directrice existe, sinon non.
• Notez si design.md existe à la racine du projet ; utilisez son chemin uniquement lorsqu'un fichier composant ou page/parcours est dans le périmètre, sinon aucun.
• Lisez AGENTS.md (canonique ; CLAUDE.md si absent) comme contexte du projet (court et bon marché). Notez également l'approche de construction en une ligne : l'approche de découpage de la tranche choisie par l'équipe, enregistrée dans l'en-tête du périmètre (ou AGENTS.md racine), par exemple chemin fin de bout en bout, boucle centrale la plus fine utilisable, première coque UI sur des espaces réservés, parcours utilisateur complet par phase. Cela ne bifurque pas la logique ; cela calibre votre jugement lors de l'écriture (étape 8, règle a).
• Lisez package.json, notez scripts.test. RUN_COMMAND = <pkgmgr> test lorsqu'un script test existe (<pkgmgr> run test pour npm) ; une invocation brute (par exemple <pkgmgr> exec vitest run) uniquement lorsqu'il n'y en a pas.

---

7.5 Demander s'il faut exécuter la suite (toujours)

Demande : "Les tests seront écrits pour <N> fichiers modifiés. Exécuter la suite après l'écriture ?"  (en-tête : "Exécuter les tests ?")
- "Oui, exécuter et corriger jusqu'au vert" : "Exécuter la suite ; je corrigerai les erreurs de test et signalerai les vrais bugs que les tests détectent"
- "Ignorer, juste les écrire" : "Écrire les tests et me donner des instructions manuelles d'exécution et de vérification à la place"

Définissez RUN_AFTER = oui | non et appliquez-le au moment de l'écriture.

8. Écrire la suite (thread principal)

Le thread principal écrit lui-même les tests. Ne lancez pas de rédacteur. Résolvez le dossier de cette compétence en chemin absolu et lisez agent-prompt.md et writing-guide.md maintenant (seulement maintenant, au moment de l'écriture) : agent-prompt.md est votre modèle opératoire, writing-guide.md est la stratégie, les règles d'outil, la boucle d'itération et le format de rapport que vous suivez. La lecture des fichiers modifiés sous test est la partie coûteuse ; pour un ensemble volumineux ou inconnu, déléguez uniquement la lecture à un sous-agent scout en lecture seule sur le modèle le moins cher (Claude Code : haiku, n'héritant pas du modèle de session) qui renvoie une carte compacte, puis écrivez à partir de celle-ci.

Les entrées à appliquer (les valeurs étiquetées que vous avez rassemblées) :

1. outil unitaire, outil E2E, outils supplémentaires, état INSTALL ; testDir, filePattern, gestionnaire de paquets, stack/framework, packageRoot ; le périmètre classifié (chaque chemin de fichier avec sa classe : logique / composant / page flow / api server / cli) ; RUN_COMMAND, RUN_AFTER ; contexte du projet plus la ligne d'approche de construction ; les 3 chemins de spécification récents ou aucun (lu uniquement si pertinent pour ce que vous testez) ; le chemin design.md ou aucun ; TRACE_TO_CONTRACT, le chemin de la spécification directrice et le chemin verify.md (chacun aucun si absent).
2. Deux règles à appliquer : (a) laissez l'approche de construction calibrer quels comportements sont durablement réels pour cette tranche (verrouillez-les en tant qu'assertions stables) par rapport à un échafaudage délibéré que la tranche simule par conception (n'affirmez pas une implémentation réelle que le plan n'a pas encore construite, par exemple une attente de backend réel sur une coque qui simule ses données). (b) lorsque TRACE_TO_CONTRACT = oui, lisez les critères d'acceptation (depuis verify.md si présent, en préférant sa liste de contrôle déjà résolue taguée AC-N, sinon depuis ## Requirements de la spécification) et verrouillez ceux qui sont durables : un test automatisé pour chaque critère qui peut être attaché comme une assertion stable, chaque test tagué avec le AC-N qu'il couvre (par exemple un commentaire covers: AC-3, ou AC-3 dans le titre du test) afin que la suite se rattache au contrat. Ne simulez jamais un critère qui ne peut pas être automatisé (visuel/manuel/environnemental, par exemple "l'email arrive réellement") ; enregistrez-le dans NOT_COVERED comme AC-N, <pourquoi non automatisable> → reporter à l'étape manuelle de /check verify.

Monorepo (plusieurs racines de paquets de l'étape 1b) : écrivez la suite de chaque racine à son tour, limitée à ses fichiers, outil et gestionnaire de paquets (déléguez la lecture des fichiers de chaque racine à son propre scout si volumineux). Racine unique (cas courant)

… [truncé pour la traduction]