Ustagammon/docs/scenarios/README.md

Scénarios d'utilisation

La documentation utilisateur d'Ustagammon : un fichier par tâche réelle d'un joueur, écrit pour lui. Ces fichiers sont la seule source (ADR 0008) : l'application les met en forme comme pages d'aide, et ils sont exécutés comme tests d'intégration sur le domaine et le moteur réel.

make site copie ce dossier dans le site publié (docs/scenarios/) ; l'aide de l'application (bouton « Aide ») lit ces copies à l'exécution (app/src/ui/help.ts). Les fichiers affichés dans l'aide sont ceux de la liste FEATURES de help.ts.

make test les exécute avec Cucumber : les étapes, définies dans app/tests/steps/, pilotent le domaine branché sur le vrai moteur WebAssembly, avec des dés imposés pour que chaque exécution soit identique. Une étape sans définition fait échouer les tests.

Format

Gherkin standard (.feature), en français, validé par l'analyseur officiel de Cucumber (make test) :

# language: fr
Fonctionnalité: <la tâche>

  Un court paragraphe qui explique au joueur à quoi elle sert.

  Scénario: <un cas précis>
    Étant donné que <la situation de départ>
    Quand <ce que fait le joueur>
    Alors <ce qu'il constate>
    Et <autre constat>

Dans l'aide, chaque scénario devient une question repliable : son titre est la question, formulée comme le joueur se la pose (« Comment jouer un coup ? ») ; le paragraphe sous le titre est la réponse, qui doit se lire seule ; les étapes ne s'affichent pas. Une étiquette @position:<Position ID> au-dessus du scénario ajoute à la réponse le lien « Voir sur le plateau ». L'adresse d'une question (#/aide/<identifiant>) est tirée de son titre : changer un titre change son adresse, et les titres cités par app/src/ui/help-context.ts sont vérifiés par make test.

Règles d'écriture :

• la deuxième personne (« vous ») et les mots du glossaire (docs/glossaire/) ;
• des intentions, pas des gestes d'interface : « vous commencez une nouvelle partie », pas « vous touchez le bouton Nouvelle partie ». Le même scénario reste vrai quelle que soit l'interface, et peut piloter directement le domaine ;
• des constats vérifiables par le joueur, sans détail technique.

Scénarios

Fichier	Tâche	Depuis
jouer-une-partie.feature	Jouer une partie contre l'ordinateur	Étape 0d
jouer-un-match.feature	Choisir sa partie (libre ou match, niveau) et jouer un match	Étape 1c
comprendre-mes-coups.feature	Comprendre ses coups avec le conseil du maître	Étape 1d
mes-parties.feature	Retrouver mes parties, leurs branches, les exporter en SGF	Étape 1b
partager-une-position.feature	Ouvrir et partager le lien d'une position	Étape 0e.4
regler-l-application.feature	Régler l'application (menu), la mettre à jour	Étape 0e
decouvrir-l-application.feature	Premier lancement et accueil	Étape 0e.5
apprendre-les-regles.feature	Apprendre les règles avec le tutoriel	Étape 0e.5
installer-l-application.feature	Installer l'application	Étape 0e.5