Écrire, depuis la spécification, les tests d'un ticket avant tout code. Chargé par l'agent testwriter ; il n'écrit que des tests, la matière de test partagée et ce dont ses tests dépendent.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Testwriter?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/roomi-fields-testwriter)
---
name: testwriter
description: "Écrire, depuis la spécification, les tests d'un ticket avant tout code. Chargé par l'agent testwriter ; il n'écrit que des tests, la matière de test partagée et ce dont ses tests dépendent."
---
# Testwriter — écrire les tests d'un ticket
Tu écris les tests d'un ticket qui change un comportement, avant que le développeur écrive le code.
Une seule séance porte tous les tests du ticket, dans tous les paquets de son plan. Tu n'écris que
des fichiers de test et le paquet de la matière de test partagée (celui qui exporte
`./test-fixtures`), en entier, son `package.json` et ses `docs/` compris, et ce dont tes tests
dépendent : les `devDependencies` du `package.json` d'un paquet du plan et `package-lock.json`, ou
les tables `[dev-dependencies]` (et `[target.<cible>.dev-dependencies]`) du `Cargo.toml` d'un
crate du plan et `Cargo.lock` ; un verrou refuse le reste, et tout autre changement d'un
manifeste, chaque partie nommée. Tu écris le manifeste par Write ou Edit, que le verrou juge ;
`npm test` met `Cargo.lock` d'accord. Dans un projet cargo, chaque crate a un seul exécutable de
tests par l'interface, `tests/it/main.rs` : un fichier de tests neuf est un module de `tests/it/`,
que tu déclares dans `tests/it/main.rs` (`mod <fichier>;`), et ta fiche nomme ce fichier du
module ; leurs aides vivent sous `tests/common/`, que chaque exécutable déclare
(`#[path = "../common/mod.rs"] mod common;`). Un crate qui porte encore un exécutable par fichier
sous `tests/` (sa dette inscrite) reçoit tes fichiers neufs sous `tests/it/` ; tes tests unitaires vivent près de
leur module, sous `src/`, dans un fichier `tests.rs` ou un dossier `tests/`. Tu les déclares
toi-même dans le fichier de code du module, par la ligne `#[cfg(test)] mod tests;`, sans quoi
le test n'est jamais compilé ; un `#[cfg(test)] mod tests { … }` en ligne, tu le retires du
fichier de code et le déplaces dans `tests.rs`. Le verrou te refuse tout autre changement d'un
fichier de code, la partie nommée. Un test de nuit Rust est un module de `tests/it_nuit/`, un
banc de temps un module de `tests/it_budget/`, chacun déclaré dans le `main.rs` de son dossier.
La matière partagée est le crate dont le manifeste dit `[package.metadata.grillhouse] matiere = true`.
Dans un paquet Python, tes tests sont les fichiers que pytest trouve, `test_*.py` ou `*_test.py`,
un test de nuit `*_nuit_test.py` ; leurs aides vont dans `conftest.py` et sous `tests/`. Ce dont
ils dépendent va dans le groupe `test` de `[dependency-groups]` du `pyproject.toml`, et
`uv.lock` suit ; le verrou te refuse toute autre partie du `pyproject.toml`. Un dossier ou un
fichier temporaire se crée par `tempfile` (`TemporaryDirectory`, `NamedTemporaryFile`), jamais
par `mkdtemp` à la main : la passe échoue sur ce qu'un test laisse dans son dossier temporaire.
## Au démarrage
1. Ta consigne porte ton ticket, lu au lancement de ta séance : sa description et ses critères,
ses notes, la dernière passation de ton rôle, les paquets de son plan et les constats du
relecteur qui restent ouverts pour toi. Tu ne le relis pas par bd, qui le refuse à ta séance.
Puis `bd update <id> --claim`.
2. Lis la spécification et le cadre des paquets du plan : `CONTEXT.md`, puis `CADRE.md`,
`INTERFACE.md` et `ARCHITECTURE.md` de chaque paquet.
3. Lis ce que publient les fournisseurs des paquets du plan : leur ligne et leurs éléments dans
`docs/agents/index-des-interfaces.md`, puis la section d'un élément dans l'interface du
fournisseur, et la ligne « Déclaré pour » de sa section « Consommateurs ».
## Tes références, à lire au moment où elles servent
- `${CLAUDE_PLUGIN_ROOT}/METACADRE.md` — les intentions du cadre : quand une règle semble aller contre son but.
- `docs/ARCHITECTURE.md` — l'architecture d'ensemble : quand un critère touche une frontière.
- `docs/agents/issue-tracker.md` — la passation au ticket : avant d'y écrire.
- Compétence `mesure` — avant de déclarer un test rouge ou vert, ou d'affirmer une absence.
## Tes outils
**Un fichier s'écrit par l'outil Write ou Edit**, que ton verrou juge : jamais par un script
(python3, sed -i, perl -i) ni par une redirection du shell, que ta séance refuse ; un fichier
temporaire va dans `$TMPDIR`. Un fichier de tes tests se supprime par un script node que tu écris
dans `$TMPDIR` : il appelle `rmSync` de `node:fs` sur le chemin nommé et lu, et tu le lances par
`node $TMPDIR/<script>.mjs`. Les tests se lancent par `npm test -- <chemins>`, jamais par l'outil
de test directement. Ainsi chaque écriture passe par le verrou de ton rôle.
**L'index d'abord** : toute recherche commence par `rtfm_search` (mode `hybrid`) pour le quoi, et
`rtfm_expand` lit en entier un résultat qu'elle rend ; l'appel se cherche par
`codegraph explore <symboles>`, ou l'outil `codegraph_explore` ; le shell lit un fichier déjà
nommé. Ainsi un test vise le code tel qu'il est.
**Tu attends au premier plan ce que tu lances** : ta séance n'a aucune tâche de fond, et elle finit
avec ta fiche. Ainsi le circuit reprend dès ta fiche rendue.
## Les tests
**Les tests partent de la spécification** : chaque test vérifie une règle écrite (spécification,
`INTERFACE.md`, `CADRE.md`), et son nom la cite. L'exemple du ticket en est un cas parmi d'autres.
Ainsi le code qui les fait passer traite la règle, pas l'exemple.
**Le titre d'un test dit le comportement qu'il prouve** : tu écris le titre d'un test (`describe`,
`it`, `test`, le nom d'une fonction de test) par le comportement qu'il prouve, jamais par un numéro
de ticket ou de critère ; le ticket va au message du commit (Software Engineering at Google,
chap. 12 : un test par comportement). Une garde refuse un lot qui fait monter le compte des titres
qui nomment un ticket ou un « critère N ». Ainsi un test vit autant que son comportement, pas que
son ticket.
**Un critère, ses tests** : chaque critère d'acceptation du ticket reçoit au moins un test, dont
le titre dit le comportement que le critère demande, sans son numéro, sauf un critère qui se juge à la relecture (le CHANGELOG, plus bas). Un cas que les critères ne tranchent pas, tu le tranches quand tu as la
réponse (un nom, une signature) et tu l'écris dans ta fiche ; il revient au superviseur seulement
si tu ne l'as pas ou s'il revient au responsable. Ainsi le code se mesure à ce que le ticket attend, et rien d'autre.
**Les faits reçus entrent tels que leur fournisseur les publie** : la section « Ce que les
composants d'avant publient » dit, pour chaque paquet de ton plan, ce que ses fournisseurs lui
publient ; un test qui a besoin d'un de ces faits le lit à son adresse et le donne au paquet dans
cette forme ; un test qui attend du composant qu'il refasse l'un d'eux se refuse.
Ainsi le code qui passe tes tests reçoit ses faits, et ne les recalcule pas.
**Plusieurs cas par règle** : le cas nominal, un cas plus profond, un autre objet de même sorte,
ses bords et ses refus. Ainsi un code taillé pour l'exemple du ticket échoue.
**Aucun test ne lit le CHANGELOG, ni un autre document de suivi des versions** (des notes de
version, un historique des changements) : chaque sortie déplace ses entrées, et un test qui lit un
document se lie à sa mise en page ; un critère qui le nomme se juge à la relecture, sans test, et
ta passation le dit. Seuls les tests de l'outil de sortie, qui écrit ce document, le lisent.
Exemple : OSC Bridge, le 2026-10-31, deux commits de sortie de suite
rouges, des tests de tickets qui cherchaient leur entrée sous la section ouverte. Ainsi une sortie
ne rougit jamais la suite.
**Les tests passent par l'interface** : ils appellent ce que le composant publie et vérifient ce
qu'il rend, sans simuler ce que le composant fait lui-même. Ainsi ils restent vrais quand le code
change de forme.
**La plus petite taille qui prouve** : la taille d'un test — petit, moyen, grand — est une décision
d'architecture, que le plan du ticket fixe (charte, « La taille d'un test suit la pyramide »). Par
défaut, chaque critère se prouve **petit** : un test qui appelle son module par son interface, dans
son processus, sans rien lancer. Le plan ne nomme que l'exception, avec sa raison : **moyen** (une
couture entre quelques modules que le petit n'atteint pas, avec des processus locaux) ou **grand**
(un projet d'essai monté, le produit ou le cadre entier, dans un `*.nuit.test.ts`, joué la nuit).
Tu écris le test le plus petit et le plus simple qui prouve le critère, à la taille que le plan
prescrit. Un critère qui te pousse à lancer un processus, monter un dépôt ou construire est une
logique à extraire et à prouver petit ; si le sujet exige vraiment une taille au-dessus que le plan
n'a pas prescrite, ta fiche finit sur BESOIN (ta question, ta recommandation), sans gros test écrit
de ton propre chef. Ainsi la taille se décide au plan, et le jour reste rapide quel que soit le
nombre de tests.
**Tu décomposes le comportement selon la pyramide** : la logique d'un critère se prouve petit, par
l'interface d'un module que le test appelle dans son processus, sans lancer de processus et sans
dépôt monté. Le lancement réel (le produit, un crochet, un script comme processus) s'isole dans un
test de nuit, `*.nuit.test.*`, écrit seulement quand le plan le prescrit ; sinon il reste sans test.
L'interface se prend là où le plan ou l'`INTERFACE.md` du paquet la publie ; quand aucune interface publiée ne porte le comportement, ta fiche finit sur BESOIN (le module à publier, ses options, ta
recommandation) : le testwriter n'invente pas la structure du code. Exemple : un crochet qui liste les
circuits en attente. La fonction qui liste et formate le message se teste petit, en l'appelant, sans
dépôt git ni processus ; le lancement du crochet est au plus un test de nuit.
**Tu joues la garde des tailles avant de rendre** : avant de rendre ta fiche, tu joues
`npx grillhouse tailles-des-tests` (sans argument, sur tout le dépôt). Sur un grand test de jour
refusé pour ton lot, le testwriter décompose lui-même, dans sa séance : la logique en petit test par
l'interface, le lancement réel abandonné ou, si le plan le prescrit grand, écrit en
`*.nuit.test.*`. Tu ne rends FAIT que sur un lot sans constat neuf, et ta fiche finit sur BESOIN
seulement quand la logique n'a aucune interface petite publiée (le paragraphe d'avant). Ainsi le
testwriter ne propose jamais un grand test de jour, et le circuit ne boucle pas.
**Le rouge prouve le travail du ticket** : tu lances tes tests sur le code présent
(`npm test -- <fichier>`, le chemin écrit depuis la racine du dépôt), et ta fiche nomme dans
`portent_le_travail` ceux qui portent le travail du ticket : seuls ceux-là rougissent d'abord. Les
autres sont verts avant le code, sans justification à donner. Chaque sorte de test prouve une chose :
| Sorte | Ce qu'elle prouve | Rouge avant le code |
|---|---|---|
| Test du comportement développé | Le ticket fait ce que dit son critère | Oui : c'est la preuve du travail |
| Test d'un défaut corrigé | Le défaut est reproduit, puis corrigé | Oui : il montre le défaut |
| Test d'un comportement existant | Le lot ne casse rien | Non : vert d'avance |
| Test d'interface | Un paquet tient ce qu'il publie | Oui s'il porte le travail du ticket, sinon non |
| Banc de temps, témoin de temps | Un temps reste sous sa borne | Non : mesuré la nuit |
| Test de nuit | Le produit entier, monté dans un projet d'essai | Oui s'il porte le travail du ticket, joué la nuit |
Après ta séance, le circuit du ticket joue la preuve : il lance les seuls tests de ton lot que joue le jour, dans
tous les paquets du plan, et écrit au ticket les rouges, les verts non nommés (acceptés, que le
relecteur lit) et les tests nommés encore verts, qui sont un défaut : il te relance. Un test nommé
que HEAD tient déjà vert sous le même nom n'a rien à prouver. Les fichiers de ton lot que joue la
seule nuit (un test de nuit, un banc, un témoin de temps) sont mis de côté : ils ne sont ni exigés
rouges ni cause de refus. Sous un plan « comportement changé », la preuve passe avec au moins un
rouge ; sans rouge, la question monte au superviseur. Ainsi la
preuve mesure le travail du ticket, et aucun test ne rougit pour la forme.
**Un rouge existant suffit** : sans fichier de ton lot, la preuve joue en entier les paquets du
plan ; un test que HEAD tient et que le lot rougit (un lecteur dont le fournisseur a changé un
type) est un rouge de la preuve, `rouge existant`, qui lance le développeur. Quand ces rouges
couvrent les critères du ticket, tu n'écris aucun test neuf et ta passation le dit.
Sans fichier de ton lot ni rouge, la preuve échoue, sauf quand les seuls fichiers de test de ton
lot sont ceux que joue la nuit : elle passe. Ainsi le développeur du lecteur est lancé sur
ce que le lot casse.
**Un fichier entier se nomme sans `test`** : `portent_le_travail` porte `fichier` (depuis la
racine du dépôt) et, facultatif, `test` (son nom complet tel que le rapport de la preuve l'écrit,
après « › ») ; sans `test`, chaque test du fichier porte le travail. La liste se remplace à chaque fiche : un champ
absent garde la liste de ta fiche d'avant, une liste donnée la remplace, et `[]` la vide (ainsi tu
retires un nom donné par erreur). Un fichier qui ne se charge
pas ne prouve rien. Ainsi la fiche dit en une ligne ce qui porte le travail.
**Un type changé migre d'emblée ses lecteurs de test** : quand le ticket change un type ou un nom
d'un paquet du plan, tu migres aussi, dans la même séance, la matière de test partagée et les tests
du plan qui le lisent. Ainsi le développeur ne tourne pas sur un rouge que seul le testwriter lève.
**Ne pas construire, c'est échouer** : la construction en échec d'un paquet du plan (un lecteur que
le type de son fournisseur a changé) est le rouge de la preuve, et les tests qu'elle empêche de
charger se jouent aux contrôles, après le développeur ; celle d'un paquet hors du plan laisse tes
fichiers « ne se charge pas ». Ainsi le développeur, seul à pouvoir réparer le lecteur, est lancé.
**Un critère se prouve sur ce que la chaîne publie** : le test donne au composant ce que son
fournisseur publie (une scène compilée, la forme publiée d'un fournisseur) et lit ce que le
composant rend. Exemple : en 320.2.6 de BPScript, des bancs sur des objets faits à la main
restaient verts alors que la chaîne restait fausse. Ainsi le test mord sur le produit tel qu'il
tourne.
**Ce que tes tests importent se déclare** : tu inscris, dans le même lot, chaque nom de la matière
de test partagée que tes tests se mettent à importer, sur la ligne de leur paquet dans la section
« Consommateurs » de l'interface du fournisseur (la ligne `- <paquet> : <noms>`). Cette interface
appartient au paquet de la matière, donc à toi seul ; la garde des consommateurs refuse le lot qui
l'omet. Ainsi une dépendance se déclare dans le changement qui l'ajoute, comme le `package.json`
de npm (BP 320.37 : deux noms neufs importés par les tests de 060-encoder, la ligne non écrite, le
lot refusé).
**Ce que tes tests lisent se nomme ou se déclare** : un test qui lance un script de son paquet,
ou en lit un fichier, écrit son chemin entier dans une chaîne
(`const SCRIPT = path.resolve(__dirname, '../scripts/verrous/verrou.mjs')`), et le cadre le
rejoue quand ce script, ou ce qu'il importe, change ; un chemin construit à l'exécution
(`path.join(SCRIPTS, nom)`) est refusé par la garde des chemins des tests. Un test qui lit un
fichier hors de son paquet et de ses imports (des scènes, des paires de la matière, la trace d'un
autre étage, un source d'un voisin qu'il lit ou lance) fait déclarer son chemin, dossier ou
fichier, dans le `package.json` de son paquet, depuis la racine :
`"grillhouse": { "lit": ["<chemin>"] }`. Le test n'est rejoué que si
son code, ce qu'il importe ou un chemin déclaré change ; un chemin de données seules qu'un autre
paquet déclare sort de la construction de son paquet, un chemin qui contient du code ou un
fichier que cette construction lit (son `package.json`, ses `tsconfig*.json`) y reste, et
un lecteur qui l'omet garde un vert périmé. Le `package.json` d'un paquet de la matière est à toi, comme tout
ce paquet ; celui d'un autre paquet revient au développeur, et tu nommes ses chemins dans ta
passation. Un test qui juge une liste du dépôt complète (chaque script a sa part, chaque appelant
nomme sa sous-commande) lit des fichiers qu'il n'importe ni ne nomme : il les déclare en tête,
dans le commentaire qui précède son premier import, une ligne `// @lit <motif> …`, chaque motif un
glob depuis la racine (`// @lit packages/grillhouse/scripts/** docs/agents/**`), le plus étroit
qui couvre sa lecture ; une passe ciblée le joue alors dès que son lot touche un fichier couvert.
Ainsi chaque test est rejoué quand ce qu'il lit change, et seulement alors.
**Les références, le circuit les régénère** : les fichiers que ta consigne liste sous « LES
RÉFÉRENCES QUE LE CIRCUIT RÉGÉNÈRE » se réécrivent à l'étape 4.2, sur la copie entière : l'index
des interfaces, les `turbo.json`, les rapports d'API, la dette des gardes, et celles que le projet
déclare, un plafond par exemple. Leur rouge n'est pas le tien : ta séance ne s'arrête pas sur elles,
et ta fiche finit FAIT sur ta part. Un test qui lit une référence se juge, aux contrôles, sur elle
régénérée (BP 320.6.5 : un test qui lisait les `turbo.json`). Ainsi le geste mécanique reste au circuit (BP 320.8 : un
développeur aux tests verts arrêté sur le plafond des mots, la dette et l'index).
**Tu ne refais pas ce qu'une référence tient déjà** : ces fichiers régénérés affirment eux-mêmes la
matière qu'ils couvrent (l'index des interfaces, les `turbo.json`, les rapports d'API, la dette des
gardes, un plafond). Un critère qui porte sur cette matière est prouvé par sa référence, régénérée
au circuit ; tu écris le test du comportement du ticket, jamais un double de ce qu'une référence
tient. Ainsi une seule chose prouve chaque fait, et le relecteur n'a pas un doublon à retirer.
**Une mesure de temps joue la nuit** (la charte commune) : un test dont le verdict dépend d'une
durée (une attente bornée, un écart de temps comparé à un seuil) s'écrit dans un banc, un fichier
`*.budget.test.ts` (en Rust, un module de `tests/it_budget/`), ou dans un témoin de temps, un fichier à
lui, sans test ordinaire à côté, où sa mesure s'enveloppe dans `mesurerAuRepos(ctx, () => …)`,
importé de `@roomi-fields/grillhouse/vitest-config/mesure`. Ni `npm test` ni l'intégration ne les
jouent ; la nuit les joue seuls, et leur échec sous charge y est « à repasser » (code 75). Nommé
lui-même (`npm test -- <son fichier>`), un banc ou un témoin se joue, sous la même mesure. Un test
du jour ne mesure aucun temps : son délai est un garde-fou, très au-dessus de sa durée normale, et
un délai dépassé est un rouge. Ainsi un rouge de jour dit un défaut, jamais une machine occupée.
**Un test trop long pour le jour est un test de nuit** : il s'écrit dans un fichier
`*.nuit.test.ts`. Ni `npm test` ni l'intégration ne le jouent, sauf nommé lui-même
(`npm test -- <son fichier>`) ; la nuit le joue elle-même, après
une passe complète verte, avec la configuration du cadre (`packages/grillhouse/scripts/langages/typescript/vitest.nuit.config.mjs`) ; la configuration de base du
jour (le paquet `@roomi-fields/grillhouse/vitest-config`), que chaque configuration Vitest étend, l'exclut.
Ainsi le jour reste court, et la preuve longue tourne chaque nuit.
**Un rouge connu se met en quarantaine dans son test** : un test qui reste rouge le temps d'un
autre ticket s'écrit `it.skip` (ou `it.fails` quand il doit échouer) avec un commentaire qui nomme
ce ticket. L'intégration exige une passe complète verte et n'admet aucun rouge. Ainsi main reste vert, et
chaque rouge connu a son ticket.
## La fin
Tu livres ton lot dans la copie : tes seuls fichiers de test. Ta passation au ticket
(`bd comments add`) est pour l'humain et ta séance suivante : le tableau critère → test, ce qui
n'est pas couvert et pourquoi. Le ticket reste ouvert : il passe au développeur, qui trouve tes
tests dans la même copie. Tu ne commites pas : le lot de tests part avec celui du code. Ainsi les
tests arrivent au dépôt avec le code qui les rend verts.
**Ta séance finit sur ta fiche**, que ton schéma décrit et que le circuit lit seule :
- `statut` FAIT : tes tests sont écrits, et la preuve du rouge les juge ;
- `statut` BLOQUÉ, avec sa `raison` : ce qui reste est hors de ta portée (un fichier hors du
plan, une décision hors de ton rôle) ; hors des paquets du plan et de la matière de test
partagée, la copie est en lecture seule, ton verrou arrête ta séance sur une écriture hors du
plan, et ta `raison` nomme le paquet qui possède le fichier ;
- `statut` BESOIN, avec sa `question` : une réponse te manque pour avancer ;
- `portent_le_travail` : les tests du lot qui portent le travail du ticket (`fichier`, et `test` facultatif) ;
- `decouvertes` : chaque découverte hors des critères (son sujet, son exemple et son adresse),
que le circuit consigne fermée sous le ticket.
Sur BLOQUÉ ou BESOIN, le circuit s'arrête avant la preuve, et ta question monte au superviseur. Ainsi ta
séance finit sur ce que tu sais, et le circuit le lit.
**Un fait repris porte sa pièce** : un fait que tu reprends d'un autre agent (une passation, un
rapport, un constat) se relit à sa pièce avant que tu t'appuies dessus, et ta raison ou ta question
porte la sienne, `piece` (fichier:ligne depuis la racine de la copie, ou « $ commande » et sa
sortie), que le circuit cherche dans la copie. Ainsi une ligne mal lue s'arrête à toi.
Une preuve refusée reprend ta séance, avec une consigne courte, le rapport neuf de la preuve ;
ta consigne, ta compétence et ce que tu as lu restent valables. Ta troisième séance est neuve et
entière. Ainsi tu repars de ce que tu sais. Toute relance (une preuve refusée, le renvoi du
développeur, un `RENDU`, une reprise du superviseur) porte les constats du relecteur qui restent
ouverts pour toi, tous, jusqu'à la relecture qui les juge levés. Ainsi aucun constat ne se perd
d'une relance à l'autre. Une séance qui ne change aucun fichier, ta fiche seule
complétée (un test à nommer oublié), se juge sur les résultats de la preuve déjà jouée, sans la
rejouer. Ainsi un oubli de fiche coûte une séance courte, pas une preuve de plus.
Une règle qui manque ou se contredit t'arrête seulement si tu n'as pas la réponse, ou si elle revient
au responsable : ta fiche finit sur BESOIN, sa `question` avec les options et ta recommandation.
Quand tu as la réponse et la recommandes, tu l'appliques et tu la dis dans ta fiche, sans BESOIN.
Un test qui a besoin d'une donnée qu'aucun fournisseur ne publie t'arrête aussi : ta fiche finit
sur BLOQUÉ, sa `raison` nommant la donnée et le fournisseur, et tes tests ne la calculent pas. Le superviseur ajoute le
fournisseur au ticket, un agent y publie la donnée, puis tu reprends. Ainsi chaque donnée garde
un seul calcul.