Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Use Case and Activity Diagrams

Writing Use Case Specifications

Write complete use case specifications with preconditions, main success scenario, alternative and exception flows, and postconditions, using a template and a worked example.

A use case diagram is only a table of contents. The real value sits in the use case specification: a short, structured text that describes, step by step, how an actor and the system interact to reach the goal. Developers build from it, testers write test cases from it, and customers confirm that it is what they want.

The template

There are many templates; this one covers what most teams need.

Field What goes in it
Name Verb phrase, same as in the diagram
Primary actor Who starts it
Supporting actors External systems or roles involved
Goal One sentence: what the primary actor wants
Preconditions What must be true before it starts
Trigger The event that starts the use case
Main success scenario Numbered steps of the "happy path"
Alternative flows Valid variations, referencing step numbers
Exception flows Failures and how the system reacts
Postconditions What is true afterward (success guarantee, minimal guarantee)
Business rules / notes Constraints, non-functional needs

A worked example: Withdraw Cash

Primary actor: Account Holder. Supporting actor: Bank Host System. Goal: Receive cash from their account. Preconditions: The ATM is in service and has cash. The holder has a valid card. Trigger: The holder inserts a card.

Main success scenario

  1. The holder inserts the card.
  2. The system reads the card and asks for the PIN.
  3. The holder enters the PIN.
  4. The system verifies the PIN with the Bank Host System.
  5. The system shows the available services; the holder chooses "Withdraw cash".
  6. The holder enters an amount.
  7. The system asks the Bank Host System to authorize the amount.
  8. The system dispenses the cash and returns the card.
  9. The system prints a receipt on request.

Alternative flows

  • 6a. The holder chooses a preset amount. Continue at step 7.
  • 9a. The holder declines the receipt. The use case ends.

Exception flows

  • 4a. PIN invalid. The system shows an error and allows two more attempts (return to step 3). After three failures it keeps the card and the use case ends.
  • 7a. Insufficient funds. The system tells the holder and offers a lower amount (return to step 6).
  • 7b. Host system unavailable. The system cancels, returns the card and shows a notice.
  • 8a. ATM has too little cash. The system offers the largest amount it can dispense.

Postconditions (success): The account is debited, the cash is dispensed, the transaction is logged. Postconditions (failure): The account is unchanged, the card is returned or retained.

Writing good steps

  • One actor action or one system action per step. Alternate between them: "The holder ... The system ...".
  • Active voice and present tense. "The system verifies the PIN."
  • Describe intent, not UI. "The holder identifies themselves" beats "the holder clicks the blue Login button on the top right".
  • Name the actor each time. Avoid passive sentences like "The PIN is checked".
  • Keep it short. Aim for 5-12 steps in the main scenario; more suggests splitting with an include.
  • Number everything so alternatives can refer to it (6a, 7b).

The main scenario is the case where everything goes right. Most of the real work is in the alternative and exception flows, so budget time for them. They are where most defects are born.

From text to diagram

A specification can be turned into an activity diagram to see all paths at once. Here is the PIN-and-withdraw part as a flowchart (the next lesson teaches the notation properly).

flowchart TD
    A(["Insert card"]) --> B["Enter PIN"]
    B --> C{"PIN valid?"}
    C -- "no, attempts left" --> B
    C -- "no, 3 failures" --> X(["Keep card, end"])
    C -- yes --> D["Enter amount"]
    D --> E{"Funds available?"}
    E -- no --> D
    E -- yes --> F["Dispense cash and return card"]
    F --> G(["End"])

Exception 4a and 7a appear as loops back to earlier steps.

Python Represent a specification as data and print it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Turning flows into test cases

Every path through a specification is a test case. With this simple count you can see how fast paths multiply.

Python Count and list scenario paths for testing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real scenarios prune impossible combinations (after "invalid x3" nothing else happens), but the exercise explains why every alternative flow deserves a test.

Levels and styles

  • Brief: a paragraph summary, good for early planning.
  • Casual: a few paragraphs, informal.
  • Fully dressed: the complete template above, for critical or complex goals.
  • Two-column (actor | system) tables make interaction visible at a glance.
  • User stories are a lighter agile alternative: "As an account holder I want to withdraw cash so that I can pay in cash." Stories point to a use case-like conversation; the specification holds the details when risk is high.

A use case in six parts

Goal One sentence.
Pre and trigger Start conditions.
Main scenario Numbered happy path.
Alternatives Valid variations.

Plus exceptions and postconditions.

1 / 2

Common mistakes

  • Describing the UI. Screens change; goals do not.
  • Omitting failure paths. "Happy path only" specs produce fragile software.
  • Hidden design decisions such as "the system writes to the ACCOUNTS table".
  • Huge main scenarios with dozens of steps and many nested conditions.
  • Vague postconditions. "The order is processed" is unusable; state what is true: "the order is stored, stock reduced, receipt emailed".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main success scenario?

    It is the happy path; alternatives and exceptions branch from it.
  2. 2. Which is the best step wording?

    Active voice, a named actor, and intent without UI detail.
  3. 3. How do alternative flows refer to the main scenario?

    Numbering allows alternatives to branch from and return to specific steps.
  4. 4. Why are exception flows important?

    Failures such as invalid input or unavailable services need an explicit, agreed response.

Summary

  • The diagram is the index; the specification is the substance.
  • A template covers actors, goal, preconditions, main scenario, alternatives, exceptions and postconditions.
  • Write short, numbered, actor-named steps about intent, not UI.
  • Every path is a test case; failure paths deserve the most care.
  • Flowcharts or activity diagrams can visualize all paths of a specification.

Next: Activity Diagram Basics