Scénarios en Gherkin standard validés par l'analyseur officiel ; ADR amendables #5

2026-11-02T12:53:45Z

pierre commented

2026-11-02 12:53:45 +00:00

Pourquoi

La MR !4 a introduit les scénarios d'utilisation au format « Markdown avec Gherkin » (.feature.md), vérifiés par un simple contrôle de motifs de texte. En relisant, Pierre a demandé si le Gherkin était utilisé de manière formelle. Ce n'était pas le cas, sur deux points :

aucun vrai analyseur Gherkin ne validait les fichiers : un scénario pouvait passer make test et être rejeté plus tard par Cucumber ;
la variante Markdown est la moins outillée de Cucumber, sa prise en charge des mots-clés français n'est pas assurée, et la plupart des outils ne lisent que les .feature classiques.

Pierre a aussi fait trois remarques :

piloter une application native de bout en bout risque d'être compliqué, alors qu'exécuter les scénarios sur le domaine, voire avec le moteur, comme tests d'intégration, a du sens ;
à terme, ces exécutions pourraient produire les captures d'écran de l'aide ;
mieux vaut amender un ADR que d'en créer un à chaque précision.

Quoi

Scénarios en Gherkin standard : docs/scenarios/jouer-une-partie.feature, qui commence par # language: fr. Les étapes décrivent désormais des intentions (« vous commencez une nouvelle partie », « vous jouez 8/5 6/5 ») et non des gestes d'interface (« vous touchez… »), pour pouvoir piloter directement le domaine. Un scénario « coup interdit refusé » a été ajouté.
Validation par l'analyseur officiel : make test passe chaque scénario dans @cucumber/gherkin (MIT), exécuté dans une image Docker construite par make setup (docker/gherkin/, sur node:22.11.0-alpine3.20). Le validateur refuse un fichier qui n'est pas en français ou qui n'a aucun scénario. Il refuse aussi une étape égarée dans une description.
ADR 0008 amendé : nouveau format, validation dès maintenant, exécution comme tests d'intégration sur le domaine et le vrai moteur, et en perspective les captures d'écran.
ADR 0001 amendé : un ADR accepté peut recevoir un amendement daté en fin de fichier. Un nouvel ADR n'est nécessaire que si la décision est abandonnée au profit d'une autre. L'index des ADR, docs/organisation.md et CLAUDE.md suivent.
CREDITS.md mentionne Node.js et @cucumber/gherkin.

Comment

Le validateur (docker/gherkin/validate.mjs, une quarantaine de lignes) utilise le Parser officiel de Gherkin et vérifie trois choses : la langue déclarée, la présence d'au moins un scénario, et l'absence de ligne commençant par un mot-clé d'étape (« Quand », « Alors »…) dans une description.

Ce dernier contrôle vient d'un essai : avec un titre mal orthographié (« Scnario: »), l'analyseur officiel ne signale aucune erreur. Il range le titre et les étapes qui suivent dans la description libre, et le scénario disparaît silencieusement. Le contrôle ajouté le détecte.

Vérifié dans les deux sens : le scénario actuel passe ; un fichier sans # language: fr et un fichier avec « Scnario: » sont refusés, chacun avec un message explicite.

L'image Docker est versionnée par son tag (ustagammon/gherkin:2 dans le Makefile). Il faut changer ce numéro à chaque modification de docker/gherkin/ pour que make setup la reconstruise.

Choix et compromis

Gherkin standard plutôt que Markdown avec Gherkin : un fichier .feature brut est moins agréable à lire tel quel. L'application le mettra en forme comme page d'aide, la source restant unique.
Exécution sur le domaine plutôt que par l'interface : on teste ce que fait l'application, pas où sont les boutons. Une erreur purement visuelle (bouton absent, mauvais libellé) ne sera pas détectée par ces tests. Les captures d'écran futures et la vérification manuelle à l'étape 0d couvrent ce point.
Le contrôle des étapes égarées peut, en théorie, refuser une description en prose qui commencerait une ligne par « Et » ou « Alors ». Il suffira alors de reformuler la phrase. Le message d'erreur l'explique.
Tag d'image manuel plutôt que calculé depuis le contenu : plus simple à comprendre, au prix d'un oubli possible. Le commentaire du Makefile le rappelle.

Risques et déploiement

make test exige maintenant l'image ustagammon/gherkin:2 : il faut lancer make setup une fois. Sinon, le test le dit explicitement. La construction télécharge l'image Node et deux paquets npm, à versions figées.
Les branches en cours de 0a.2 et 0a.3 modifient aussi le Makefile : de petits conflits sont attendus à leur fusion, je les résoudrai.

Retour arrière : annuler le commit de fusion.

Comment vérifier

git switch main && git pull
make setup
make lint && make test
less docs/adr/0008-glossaire-et-scenarios-source-unique.md
less docs/scenarios/jouer-une-partie.feature

Pour voir le validateur refuser un scénario, remplacer un Scénario: par Scnario: dans docs/scenarios/jouer-une-partie.feature, lancer make test, puis git checkout docs/scenarios.

Hors périmètre

L'exécution réelle des scénarios (définitions des étapes branchées sur le domaine) viendra avec le domaine, à l'étape 0d. L'outil d'exécution sera choisi avec le socle.
Les captures d'écran automatiques restent une perspective, notée dans l'ADR 0008.
Le diagnostic des MR qui restent « open » dans Gitea est en cours, dans une tâche à part.

Generated with Claude Code https://claude.com/claude-code

## Pourquoi La MR !4 a introduit les scénarios d'utilisation au format « Markdown avec Gherkin » (`.feature.md`), vérifiés par un simple contrôle de motifs de texte. En relisant, Pierre a demandé si le Gherkin était utilisé de manière formelle. Ce n'était pas le cas, sur deux points : - aucun vrai analyseur Gherkin ne validait les fichiers : un scénario pouvait passer `make test` et être rejeté plus tard par Cucumber ; - la variante Markdown est la moins outillée de Cucumber, sa prise en charge des mots-clés français n'est pas assurée, et la plupart des outils ne lisent que les `.feature` classiques. Pierre a aussi fait trois remarques : - piloter une application native de bout en bout risque d'être compliqué, alors qu'exécuter les scénarios sur le domaine, voire avec le moteur, comme tests d'intégration, a du sens ; - à terme, ces exécutions pourraient produire les captures d'écran de l'aide ; - mieux vaut amender un ADR que d'en créer un à chaque précision. ## Quoi - **Scénarios en Gherkin standard** : `docs/scenarios/jouer-une-partie.feature`, qui commence par `# language: fr`. Les étapes décrivent désormais des intentions (« vous commencez une nouvelle partie », « vous jouez 8/5 6/5 ») et non des gestes d'interface (« vous touchez… »), pour pouvoir piloter directement le domaine. Un scénario « coup interdit refusé » a été ajouté. - **Validation par l'analyseur officiel** : `make test` passe chaque scénario dans `@cucumber/gherkin` (MIT), exécuté dans une image Docker construite par `make setup` (`docker/gherkin/`, sur `node:22.11.0-alpine3.20`). Le validateur refuse un fichier qui n'est pas en français ou qui n'a aucun scénario. Il refuse aussi une étape égarée dans une description. - **ADR 0008 amendé** : nouveau format, validation dès maintenant, exécution comme tests d'intégration sur le domaine et le vrai moteur, et en perspective les captures d'écran. - **ADR 0001 amendé** : un ADR accepté peut recevoir un amendement daté en fin de fichier. Un nouvel ADR n'est nécessaire que si la décision est abandonnée au profit d'une autre. L'index des ADR, `docs/organisation.md` et `CLAUDE.md` suivent. - `CREDITS.md` mentionne Node.js et `@cucumber/gherkin`. ## Comment Le validateur (`docker/gherkin/validate.mjs`, une quarantaine de lignes) utilise le `Parser` officiel de Gherkin et vérifie trois choses : la langue déclarée, la présence d'au moins un scénario, et l'absence de ligne commençant par un mot-clé d'étape (« Quand », « Alors »…) dans une description. Ce dernier contrôle vient d'un essai : avec un titre mal orthographié (« Scnario: »), l'analyseur officiel ne signale aucune erreur. Il range le titre et les étapes qui suivent dans la description libre, et le scénario disparaît silencieusement. Le contrôle ajouté le détecte. Vérifié dans les deux sens : le scénario actuel passe ; un fichier sans `# language: fr` et un fichier avec « Scnario: » sont refusés, chacun avec un message explicite. L'image Docker est versionnée par son tag (`ustagammon/gherkin:2` dans le `Makefile`). Il faut changer ce numéro à chaque modification de `docker/gherkin/` pour que `make setup` la reconstruise. ## Choix et compromis - **Gherkin standard plutôt que Markdown avec Gherkin** : un fichier `.feature` brut est moins agréable à lire tel quel. L'application le mettra en forme comme page d'aide, la source restant unique. - **Exécution sur le domaine plutôt que par l'interface** : on teste ce que fait l'application, pas où sont les boutons. Une erreur purement visuelle (bouton absent, mauvais libellé) ne sera pas détectée par ces tests. Les captures d'écran futures et la vérification manuelle à l'étape 0d couvrent ce point. - **Le contrôle des étapes égarées** peut, en théorie, refuser une description en prose qui commencerait une ligne par « Et » ou « Alors ». Il suffira alors de reformuler la phrase. Le message d'erreur l'explique. - **Tag d'image manuel** plutôt que calculé depuis le contenu : plus simple à comprendre, au prix d'un oubli possible. Le commentaire du `Makefile` le rappelle. ## Risques et déploiement - `make test` exige maintenant l'image `ustagammon/gherkin:2` : il faut lancer `make setup` une fois. Sinon, le test le dit explicitement. La construction télécharge l'image Node et deux paquets npm, à versions figées. - Les branches en cours de 0a.2 et 0a.3 modifient aussi le `Makefile` : de petits conflits sont attendus à leur fusion, je les résoudrai. Retour arrière : annuler le commit de fusion. ## Comment vérifier ``` git switch main && git pull make setup make lint && make test less docs/adr/0008-glossaire-et-scenarios-source-unique.md less docs/scenarios/jouer-une-partie.feature ``` Pour voir le validateur refuser un scénario, remplacer un `Scénario:` par `Scnario:` dans `docs/scenarios/jouer-une-partie.feature`, lancer `make test`, puis `git checkout docs/scenarios`. ## Hors périmètre - L'exécution réelle des scénarios (définitions des étapes branchées sur le domaine) viendra avec le domaine, à l'étape 0d. L'outil d'exécution sera choisi avec le socle. - Les captures d'écran automatiques restent une perspective, notée dans l'ADR 0008. - Le diagnostic des MR qui restent « open » dans Gitea est en cours, dans une tâche à part. Generated with Claude Code https://claude.com/claude-code

pierre added 1 commit 2026-11-02 12:53:45 +00:00

Scénarios en Gherkin standard validés par l'analyseur officiel ; ADR amendables 2ab30a4abe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

pierre manually merged commit 3768746cf4 into main

2026-11-02 18:02:28 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: pierre/Ustagammon#5