Description textuelle d'un cas d'utilisation et user stories

La description textuelle d'un cas d'utilisation est la fiche qui détaille, étape par étape, comment se déroule un cas : qui le déclenche, ce qui doit être vrai avant, le scénario nominal (le déroulement normal), les scénarios alternatifs et les scénarios d'erreur, et ce qui est vrai après. Le diagramme donne la liste des services ; la description dit comment chacun fonctionne. Ce chapitre donne un modèle de fiche, un exemple complet sur AppliFrais, et explique le lien avec les user stories des méthodes agiles.

Pourquoi une description textuelle

Une ellipse « Valider une fiche de frais » ne dit pas grand-chose. Que voit le comptable ? Que se passe-t-il si un justificatif manque ? Peut-on valider une fiche encore ouverte ? Ces questions, le développeur se les posera de toute façon ; mieux vaut que les réponses viennent du client, par écrit, avant le code.

La description textuelle sert à trois choses :

• valider le besoin avec le client, dans sa langue, sans notation à apprendre ;
• guider le développement : chaque étape du scénario devient un écran, une méthode, une vérification ;
• écrire la recette : chaque scénario, nominal ou non, devient un cas de test (plan de test et cahier de recette).

Le modèle de fiche

Il n'existe pas de format normalisé : UML définit le diagramme, pas la fiche. Le modèle ci-dessous, inspiré d'Alistair Cockburn et de Pascal Roques, est celui qu'on rencontre dans la plupart des cours et des sujets.

Le scénario nominal

Le scénario nominal (on dit aussi scénario principal, ou « chemin heureux ») décrit le déroulement le plus courant, sans erreur ni variante. Quelques règles d'écriture :

• une étape par ligne, numérotée ;
• chaque étape commence par son sujet : « Le comptable sélectionne… », « Le système affiche… » ;
• on alterne une action de l'acteur et une réponse du système ;
• on décrit ce qui se passe, pas l'interface : « Le comptable choisit une fiche », pas « Le comptable clique sur la ligne bleue du tableau » ;
• 5 à 10 étapes : au-delà, le cas est trop gros, ou trop détaillé.

Scénarios alternatifs et scénarios d'erreur

Une variante se rattache à l'étape où elle commence. On la numérote par le numéro de l'étape suivi d'une lettre : « 5a » est la première variante de l'étape 5. Elle se termine en disant où reprend le scénario (« retour à l'étape 4 ») ou que le cas s'arrête.

• Un scénario alternatif mène quand même à l'objectif, par un autre chemin : le comptable refuse un frais avant de valider, la fiche est validée quand même.
• Un scénario d'erreur (ou d'exception) empêche d'atteindre l'objectif : la fiche n'est pas clôturée, la base est indisponible.

On rencontre aussi, dans beaucoup de cours et de sujets français, les termes enchaînements alternatifs et enchaînements d'exception, numérotés A1, A2… et E1, E2…, avec l'étape où ils commencent (« A1 : démarre au point 4 ») et celle où ils reprennent. Les deux numérotations sont justes ; suis celle du sujet.

Exemple complet de description textuelle

Nom : Valider une fiche de frais.

Acteur principal : Comptable. Acteurs secondaires : aucun.

Objectif : contrôler une fiche clôturée et fixer le montant qui sera remboursé au visiteur.

Préconditions : le comptable est authentifié.

Déclencheur : le comptable ouvre l'écran de validation.

Scénario nominal

1. Le système affiche la liste des visiteurs qui ont une fiche clôturée pour le mois précédent.
2. Le comptable choisit un visiteur.
3. Le système affiche le détail de la fiche : les frais forfaitisés avec leurs quantités et leurs montants, les frais hors forfait avec leur date, leur libellé et leur montant, le nombre de justificatifs et le total (cas inclus « Consulter le détail d'une fiche »).
4. Le comptable contrôle chaque frais et confirme la validation.
5. Le système calcule le montant validé (total des frais forfaitisés et des frais hors forfait non refusés), enregistre la fiche à l'état « validée » avec la date du jour et le nom du comptable.
6. Le système affiche un message de confirmation avec le montant validé et revient à la liste de l'étape 1, sans le visiteur traité.

Scénarios alternatifs

• 1a. Le comptable veut traiter un mois plus ancien (une fiche restée clôturée après une absence). Il choisit le mois ; le système affiche les visiteurs qui ont une fiche clôturée pour ce mois. Retour à l'étape 2.
• 4a. Un frais hors forfait n'est pas conforme (extension « Refuser un frais hors forfait »). Le comptable le refuse en indiquant un motif. Le système le marque « refusé » : il reste visible sur la fiche, mais n'est plus compté dans le total. Retour à l'étape 4.

Scénarios d'erreur

• 1b. Aucune fiche n'est à valider. Le système affiche « Aucune fiche clôturée à valider ». Fin du cas.
• 4b. Le comptable doit demander une précision au visiteur avant de décider. Il abandonne la validation ; la fiche reste clôturée et le système revient à l'étape 1. L'objectif n'est pas atteint pour cette fiche : le cas reprendra plus tard.
• 5a. La fiche a changé d'état entre l'affichage et la validation (un autre comptable l'a validée entre-temps). Le système refuse l'enregistrement, affiche « Cette fiche a déjà été validée » et revient à l'étape 1.
• 5b. L'enregistrement échoue (base indisponible). Le système affiche un message d'erreur sans détail technique et journalise l'incident ; la fiche reste clôturée. Fin du cas.

Postconditions : la fiche est à l'état « validée » ; son montant validé, la date de validation et le comptable qui l'a validée sont enregistrés.

Règles de gestion

• RG1 : seule une fiche à l'état « clôturée » peut être validée.
• RG2 : le montant d'une ligne forfaitisée est la quantité multipliée par le montant unitaire du forfait (étape 110 €, kilomètre 0,62 €, nuitée 80 €, repas 25 €).
• RG3 : un frais hors forfait refusé n'est pas remboursé.

Exigences non fonctionnelles : seul un utilisateur ayant le rôle comptable accède à cet écran ; chaque validation est journalisée (qui, quand, quelle fiche).

Du texte au diagramme de séquence système

Un diagramme de séquence système (DSS) dessine le scénario nominal avec deux lignes de vie seulement : l'acteur et le système, vu comme une boîte noire. Chaque étape de l'acteur devient un message vers le système, chaque réponse du système un message de retour. C'est une étape intermédiaire entre la description textuelle et le diagramme de séquence détaillé, qui ouvre la boîte noire pour montrer les objets (chapitre 7).

Les scénarios peuvent aussi se dessiner en diagramme d'activité, avec une décision pour chaque variante : c'est utile quand les alternatives sont nombreuses (chapitre 8).

Cas d'utilisation et user stories

Dans un projet agile, le besoin s'exprime le plus souvent en user stories (« récits utilisateur ») : une phrase courte, écrite du point de vue de l'utilisateur, qui tient sur une carte.

En tant que comptable, je veux refuser un frais hors forfait non conforme afin de ne pas rembourser une dépense que le règlement interdit.

Chaque story est accompagnée de critères d'acceptation, souvent écrits au format « Étant donné… Quand… Alors… » (Given / When / Then) :

Étant donné une fiche clôturée qui contient un frais hors forfait de 60 € intitulé « Cadeau à un praticien », quand le comptable refuse ce frais avec le motif « Cadeau interdit », alors le frais apparaît comme refusé avec son motif et le total de la fiche diminue de 60 €.

User stories et cas d'utilisation ne s'opposent pas : ils découpent le même besoin à des grains différents.

En pratique, un cas d'utilisation donne plusieurs stories : une pour le scénario nominal, une par variante importante. « Valider une fiche de frais » se découpe en « valider une fiche », « refuser un frais hors forfait », « corriger une quantité forfaitisée ». Inversement, le diagramme de cas d'utilisation donne une carte des stories, utile pour vérifier qu'aucun acteur n'est oublié. Le cours Gestion de projet détaille l'écriture des stories, les critères INVEST et l'estimation.

Exercices

Exercice 1 sur 3 Nominal, alternatif ou erreur ? Réussi À revoir

Voici des événements du cas « Saisir un frais hors forfait » d'AppliFrais. Classe chacun.

1. Le visiteur saisit la date, le libellé et le montant, et le système enregistre la ligne.
2. Le visiteur saisit une date qui n'appartient pas au mois de la fiche ; le système refuse la saisie.
3. Le visiteur joint la photo du ticket de taxi.
4. La fiche du mois est déjà clôturée : le système affiche qu'elle ne peut plus être modifiée.
5. Le visiteur saisit un montant négatif.

Voir la réponseMasquer la réponse de l'exercice 1

1. Nominal : c'est le déroulement normal.
2. Erreur, rattachée à l'étape de saisie. Le système affiche le message et redemande la date : on peut aussi le présenter comme une alternative qui revient à l'étape de saisie, puisque l'objectif reste atteignable. L'important est de ne pas l'oublier.
3. Alternatif : c'est l'extension « Joindre un justificatif », qui mène quand même à l'objectif.
4. Erreur : l'objectif ne peut pas être atteint (la fiche n'accepte plus de frais). On la traite en scénario d'erreur ; si on en faisait une précondition, le cas ne démarrerait même pas.
5. Erreur de saisie, traitée comme le point 2 : message, puis retour à l'étape de saisie.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 2 sur 3 Rédiger un scénario nominal Réussi À revoir

Rédige le scénario nominal du cas « Saisir un frais hors forfait » (acteur : visiteur), en 5 à 7 étapes, avec ses préconditions et ses postconditions.

Voir la réponseMasquer la réponse de l'exercice 2

Préconditions : le visiteur est authentifié.

1. Le visiteur demande à saisir un frais hors forfait.
2. Le système affiche le formulaire de saisie et la liste des frais hors forfait déjà saisis pour le mois.
3. Le visiteur saisit la date, le libellé et le montant du frais.
4. Le système vérifie que la date appartient au mois de la fiche, que le libellé n'est pas vide et que le montant est strictement positif.
5. Le système enregistre la ligne sur la fiche du mois et met à jour le total hors forfait.
6. Le système affiche la liste mise à jour avec un message de confirmation.

Postconditions : une nouvelle ligne hors forfait est enregistrée sur la fiche du mois, à l'état « non refusée ».

Les variantes : 1a (la fiche du mois n'existe pas encore : le système la crée à l'état « créée », puis l'étape 2), 1b (la fiche est clôturée : message, fin du cas), 3a (le visiteur joint un justificatif), 4a (date hors du mois, libellé vide ou montant invalide : message et retour à l'étape 3). L'état de la fiche se vérifie pendant le cas, à l'étape 1 : ce n'est pas une précondition.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 3 sur 3 Du cas d'utilisation aux user stories Réussi À revoir

Écris trois user stories, avec un critère d'acceptation chacune, tirées du cas « Réserver un jeu » de la ludothèque du chapitre 2 (le paiement de la cotisation est exigé si elle n'est pas à jour, la livraison à domicile est une option).

Voir la réponseMasquer la réponse de l'exercice 3

1. En tant qu'adhérent, je veux réserver un jeu pour une date de retrait afin d'être sûr qu'il soit disponible ce jour-là. Critère : étant donné un jeu disponible le samedi 14 novembre, quand je le réserve avec une cotisation à jour, alors la réservation apparaît dans mon compte et le jeu n'est plus proposé à cette date.
2. En tant qu'adhérent dont la cotisation a expiré, je veux la payer en ligne au moment de réserver afin de ne pas me déplacer. Critère : étant donné une cotisation expirée et un paiement refusé par la plateforme, quand je valide la réservation, alors la réservation n'est pas enregistrée et un message m'invite à réessayer.
3. En tant qu'adhérent, je veux demander la livraison du jeu à domicile afin de ne pas avoir à venir le chercher. Critère : étant donné une réservation en cours, quand je coche la livraison et que je saisis mon adresse, alors le récapitulatif affiche l'adresse et la date de livraison avant la confirmation.

La deuxième story correspond à l'extension « Payer la cotisation », la troisième à l'extension « Demander la livraison à domicile » : le diagramme de cas d'utilisation sert de carte pour ne pas en oublier.

Tu avais trouvé ?

Oui, j'avais bonPas encore