Le gabarit d'un scénario

Les scénarios de recette suivent le même gabarit, dans le même ordre. Cette page le fixe : elle sert de contrat au lecteur — qui sait ce qu’il a le droit d’y trouver — et de modèle à qui en écrit un.

Le format n’est pas inventé ici. Il vient de docs/test-plan-lot2.md et de docs/notifications-test-plan.md, deux plans qui ont été réellement joués ; cette page les industrialise.

La règle qui gouverne tout le reste

Un scénario qu’on ne peut pas rejouer à l’identique n’est pas un scénario.

Deux personnes qui déroulent le même scénario, à deux semaines d’écart, doivent partir du même état et obtenir le même résultat. C’est ce qui distingue une recette d’une visite guidée, et c’est ce qui rend un échec exploitable : si le résultat diffère, c’est le produit qui a changé, pas le testeur.

Tout ce qui suit découle de cette règle.

Les six sections, toujours dans cet ordre

Section	Ce qu’on y met
En-tête	domaine, durée indicative, niveau, étiquette automatisable ou manuel
Préparation	les commandes exactes, l’état de départ déclaré, les comptes et leurs rôles
Étapes	numérotées, une action par étape, avec son résultat attendu observable
Pièges connus	ce qui fait perdre du temps et n’a rien à voir avec un bug
Traçabilité	les identifiants de story que le scénario couvre
Checklist	la même chose en <Checklist>, copiable en Markdown

Aucune section n’est vide. Si un scénario n’a aucun piège connu, écrivez-le — « aucun piège identifié à ce jour » est une information, une section absente n’en est pas une.

Les quatre règles non négociables

1. Déclarer l’état de départ

Deux jeux de données sont possibles, et il faut choisir, pas laisser deviner :

Jeu de données	Quand l’employer	Ce qu’il donne
bun run demo:seed	dès qu’un scénario a besoin de volume ou de cas réalistes	l’établissement « Institut Supérieur Delacroix — DÉMO », dense, idempotent : même graine, mêmes données
Construction manuelle	quand le scénario porte sur la création elle-même, ou sur l’isolation entre deux établissements	un établissement nu, monté par les étapes du scénario

Un scénario qui ne dit pas d’où part son état est injouable : le lecteur ne saura pas si son résultat différent vient du produit ou de sa base.

Le raccourci du pro

bun run demo:seed détruit et recrée le tenant de démonstration à chaque exécution. C’est ce qui le rend sûr : un scénario qui a sali les données se rejoue en une commande, sans nettoyage manuel.

2. Un résultat attendu observable, à chaque étape

« Ça marche » n’est pas un résultat attendu. Un résultat observable est quelque chose qu’on peut lire à l’écran, citer entre guillemets, et comparer.

❌ Ce qu’on n’écrit pas	✅ Ce qu’on écrit
« la recherche ne renvoie rien »	la liste affiche « Aucune salle ne correspond à ces critères sur ce créneau. »
« le placement est refusé »	un message d’erreur apparaît : « Salle occupée : B-201 · 09:45 – 11:15 »
« le quota bloque »	« Quota atteint : 4 h réservées cette semaine sur 4 h autorisées. »
« l’écran est vide »	l’écran affiche « Aucune demande en attente. Tout est à jour ! »

Les libellés se citent exactement. Ils sont vérifiables dans le produit, et une citation approximative fait douter le testeur au moment où il a le moins de temps pour douter.

Quand le résultat n’est pas un texte — une couleur, une position, un badge — décrivez ce qu’il signifie, pas seulement ce qu’il est : « la cellule est hachurée et porte l’icône d’interdiction : le créneau est impossible ».

3. Étiqueter automatisable ou manuel

Chaque scénario porte l’une des deux étiquettes en en-tête.

• Automatisable — le scénario pourrait être joué par un test de bout en bout. L’étiquette n’affirme pas qu’il l’est ; elle dit qu’il mérite de l’être. L’ensemble des scénarios automatisables est la feuille de route des tests à écrire.
• Manuel — le scénario a besoin d’un œil humain. Une ligne de justification est obligatoire : « nécessite deux navigateurs simultanés », « porte sur un rendu visuel », « la progression d’un calcul long n’est pas déterministe ».

Sans la justification, l’étiquette manuel devient l’endroit où l’on range ce qu’on n’a pas eu envie d’automatiser.

4. Tracer les stories couvertes

Chaque scénario liste les identifiants de story qu’il couvre — STORY-030, V60. C’est ce qui permet de répondre, dans les deux sens :

• « cette story est-elle recettée ? » — en cherchant son identifiant dans la recette ;
• « que casse-t-on si ce scénario échoue ? » — en lisant sa ligne de traçabilité.

Les comptes de test

Convention reprise de docs/test-plan-lot2.md, et valable pour toute la recette. Les prénoms sont stables : un scénario qui dit « bob » parle du même profil qu’un autre scénario. Chaque compte existe pour éprouver une permission Le droit de faire une chose précise dans l'application — modifier le planning, approuver une demande, consulter le journal. ou une portée La limite posée sur un rôle attribué : il ne vaut alors que pour certains campus ou certaines formations, et jamais au-delà. précise.

Compte	Ce qu’il est	Ce qu’il sert à éprouver
alice	administratrice, créatrice de l’établissement	le référentiel, les rôles, la publication, l’approbation
bob	rôle personnalisé « Demandeur » — permission room.book	la réservation, les quotas, le circuit d’approbation
dave	rôle personnalisé « Valideur A » — booking.approve, limité au campus A	la portée d’un rôle
carol	administratrice d’un second établissement	l’isolation entre établissements

Un scénario qui a besoin d’un cinquième compte le nomme et dit son rôle en préparation. Sur le tenant de démonstration, les comptes sont ceux du seed — ils sont rappelés sur Avant une démonstration.

Les ports — la source unique

Cette table est la seule vérité du site sur ce sujet. Les scénarios y renvoient plutôt que de recopier une valeur.

Ce qui tourne	Adresse
L’application web	http://localhost:3000
L’API	http://localhost:3001
Swagger (l’API en interactif)	http://localhost:3001/docs
Le solveur	http://localhost:8082 — sa sonde de disponibilité : http://localhost:8082/q/health/ready
PostgreSQL	localhost:5432
Redis	localhost:6379

Si vous cherchez le web sur le port 5173, vous ne trouverez rien

5173 est l’ancien port par défaut de Vite. Il n’a jamais été celui de ce produit, mais il est resté dans les habitudes — et il figurait encore, jusqu’à récemment, dans docs/demo-script.md, qui annonçait « API (3000) + web (5173) », faux sur les deux.

Le symptôme : on ouvre http://localhost:5173, rien ne répond, et on croit que l’environnement n’a pas démarré. Il a démarré, ailleurs.

Les valeurs de la table ci-dessus sont vérifiées dans trois fichiers indépendants : apps/api/src/main.ts écoute sur 3001 par défaut, apps/web/package.json lance vite dev --port 3000, et docker-compose.yml publie 3001:3001 et 3000:3000. docs/demo-script.md et docs/test-plan-lot2.md disent désormais la même chose.

Un exemple complet

Voici un scénario court, rédigé au gabarit. C’est le modèle dont les dix-sept autres héritent.

---

En-tête

Domaine — Réservation & quotas Durée — ~8 min Niveau — complet Étiquette — automatisable

Préparation

Jeu de données : construction manuelle — le scénario porte sur les règles, qui n’existent pas dans le seed de démonstration.

docker compose up -d postgres redis
cd packages/db && bun run db:migrate
cd ../.. && bun run dev

Comptes : alice (administratrice), bob (rôle « Demandeur », room.book).

État de départ : alice a créé un campus, un bâtiment et une salle A-101 de 40 places ; bob n’a aucune réservation.

Étapes

#	Action	Résultat attendu
1	alice ouvre Administration → Règles de réservation, profil « Demandeur », active « Heures max par semaine » = 2, enregistre	« Règles enregistrées. »
2	bob ouvre Réservation, cherche une salle libre sur un créneau de 2 h, réserve	« Réservation confirmée. »
3	bob réserve un second créneau de 1 h la même semaine	le bouton « Réserver » est refusé avec « Quota atteint : 2 h réservées cette semaine sur 2 h autorisées. »
4	bob réserve un créneau de 1 h la semaine suivante	« Réservation confirmée. » — le quota est hebdomadaire
5	alice porte le quota à 4 h et enregistre	« Règles enregistrées. »
6	bob réessaie le créneau de l’étape 3	« Réservation confirmée. »

Pièges connus

• Le quota compte les demandes en attente, pas seulement les réservations confirmées. Une demande soumise à validation consomme déjà le quota.
• La semaine est celle du créneau visé, du lundi au lundi dans le fuseau de l’établissement — pas les sept jours glissants.

Traçabilité

STORY-012 (règles de réservation & quotas), V61 (écran d’administration), V30 (recherche de disponibilité).

Checklist

• Activer « Heures max par semaine » = 2 sur le profil « Demandeur » → « Règles enregistrées. »
• Réserver 2 h avec bob → « Réservation confirmée. »
• Retenter 1 h la même semaine → « Quota atteint : 2 h réservées cette semaine sur 2 h autorisées. »
• Réserver 1 h la semaine suivante → « Réservation confirmée. »
• Porter le quota à 4 h, retenter → « Réservation confirmée. »

---

Écrire la checklist

C’est la section la plus utilisée du scénario, et celle qu’on rédige le plus vite mal.

• Une action par ligne, à l’impératif, dans l’ordre.
• Le résultat attendu dans la même ligne, après une flèche, en gras.
• Pas de paragraphe : une ligne qui ne tient pas sur deux lignes d’écran est trop longue.
• Elle répète les étapes, elle ne les remplace pas : le tableau porte le détail, la checklist porte le geste.

Le bouton « Copier en Markdown » transforme la liste en cases à cocher collables dans une demande de fusion ou un ticket. C’est ce qui fait passer la recette de la documentation au travail réel — n’écrivez pas une checklist qu’on n’aurait pas envie de coller.

Ce qu’un scénario ne fait pas

• Il ne décrit pas un écran. C’est le rôle de la référence ; un scénario y renvoie.
• Il n’enseigne pas. C’est le rôle des guides ; un scénario suppose qu’on sait déjà se servir du produit.
• Il ne teste pas les cas d’échec pour eux-mêmes. Les chemins qui doivent échouer ont leur propre page : Les chemins qui échouent.

Pages liées

• La recette — les deux niveaux de parcours et l’ordre des domaines.
• Chemin critique — le parcours de 30 minutes, écrit à ce gabarit.
• Avant une démonstration — la checklist de pré-vol.
• Les pièges connus — le recueil de ce que les scénarios déterrent.
• Référence écran par écran — la description des écrans que les scénarios traversent.