Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 50 ยท Requirements Engineering

User Stories, Use Cases and Acceptance Criteria

Learn the user story format, the INVEST checklist, how use case scenarios work, and how Given/When/Then acceptance criteria make requirements testable.

Once you know what stakeholders need, you must write it down in a form that developers, testers and the business can all understand. Two popular forms are the user story, a short sentence from the user's point of view that starts a conversation, and the use case, a structured description of how a user and the system interact to reach a goal. Both are completed by acceptance criteria: concrete conditions that say when the work is done.

Stories and use cases are writing styles, so the real work is careful thinking. The examples run as Node.js stand-ins (single file, no packages): a small parser that checks story text, and a tiny scenario runner that executes Given/When/Then steps against a toy account. They illustrate the ideas; real teams use tools such as Cucumber or their test framework for the same purpose.

User stories

A user story describes a small piece of value for a specific kind of user. The classic template has three parts:

TEXT
As a <role>, I want <capability>, so that <benefit>.

For example: As a shopper, I want to save items for later, so that I can buy them when I have money. The role says who benefits, the capability says what they can do, and the benefit says why it matters. The benefit is the part people skip, and it is the most useful: it lets the team propose a better solution than the one the user named, and it tells them when to stop.

A story is deliberately brief. It is a "token for a conversation", often written on a card, and the details come from talking to the person who needs it. The three Cs describe this: the Card (the short text), the Conversation (details discussed), and the Confirmation (the acceptance criteria that confirm it works).

The INVEST checklist

How do you know a story is good? A widely used checklist is INVEST:

  • Independent: can be built and delivered without waiting for other stories, as far as possible.
  • Negotiable: details can be discussed; it is not a contract.
  • Valuable: it delivers value to a user or the business, not a technical task like "create the table".
  • Estimable: the team knows enough to estimate its size (see estimation).
  • Small: it fits in one iteration, preferably a few days of work.
  • Testable: you can say how to check it.

A story that is too large is called an epic. "As a manager, I want reports" is an epic: split it into stories you can finish ("see this week's sales total", "export the sales list"). Split by workflow step, rule variation, or data type, not by technical layer, so that each slice still delivers something usable.

A story has three parts

Role Who benefits.
Capability What they can do.
Benefit Why it matters.

Skip the benefit and the team loses the reason behind the feature.

1 / 2

Use cases

A use case describes how an actor (a person or another system) interacts with the system to achieve a goal. It is more detailed than a story and is common in plan-driven projects and regulated domains. A typical use case has:

  • Name (a verb phrase: "Withdraw cash") and primary actor (the customer).
  • Preconditions: what must be true first (the customer has a card and an account).
  • Main success scenario: the numbered steps of the normal path.
  • Extensions (alternative flows): what happens when something differs or goes wrong, tied to a step number.
  • Postconditions: what is true afterwards (balance reduced, receipt printed).
TEXT
Use case: Withdraw cash
Primary actor: Customer
Precondition: Customer has inserted a valid card.
Main success scenario:
  1. Customer enters the PIN.
  2. System verifies the PIN.
  3. Customer chooses an amount.
  4. System checks the balance.
  5. System dispenses cash and updates the balance.
Extensions:
  2a. PIN is wrong: system asks again (after 3 failures it keeps the card).
  4a. Balance too low: system shows the available balance and returns to step 3.
Postcondition: Balance is reduced by the amount; a transaction is recorded.

Use cases are strong at exposing alternative and error paths, which stories tend to leave for later. Many requirement errors hide in the extensions. The diagram form of use cases appears in use case diagrams.

Stories and use cases are not rivals. A use case can be sliced into several stories ("withdraw with correct PIN", "handle low balance"), and a story's acceptance criteria often read like a use case's extensions.

Acceptance criteria and Given/When/Then

Acceptance criteria are the conditions a story must meet to be accepted. Weak criteria ("works well") are as bad as vague requirements (writing testable requirements). A very popular format for concrete criteria is Given/When/Then, from behavior-driven development:

TEXT
Scenario: Withdrawal exceeds balance
  Given an account with a balance of 100
  When the customer withdraws 150
  Then the withdrawal is refused
  And the balance is still 100
  • Given sets the starting state.
  • When names the action or event.
  • Then states the observable result.
  • And continues the previous keyword.

Each scenario covers one example of behavior and is specific enough to automate. Several scenarios per story cover the happy path, boundaries and errors. Keep them about behavior, not about screens and button names, so they survive a redesign.

Stand-in 1: check stories automatically

The first stand-in parses stories with a regular expression, extracts role, capability and benefit, and applies a few INVEST-style heuristics. A script cannot judge value, but it can catch missing benefits, "and" lists that signal epics, and technical-task wording.

Node.js Parse and check user stories

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 node:readline or process.stdin), it gets the next line from this box.

Only the first story is clean. Try rewriting the others: "As a manager, I want to see this week's sales total, so that I can plan staffing." passes all the checks.

Stand-in 2: run Given/When/Then scenarios

The second stand-in reads scenarios written in nearly plain English and runs each line against a toy Account. This is the core mechanism of behavior-driven tools: step definitions are patterns that map a sentence to code. The account and its rules are invented.

Node.js Execute Given/When/Then scenarios

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 node:readline or process.stdin), it gets the next line from this box.

The third scenario fails on purpose: its last line claims the balance is 5, but withdrawing exactly the balance leaves 0. That is the value of executable criteria: a wrong expectation is caught by running it. Fix the number to 0 and run it again. Note how the sentences are plain English, so a business person can read and challenge them, while the step definitions hold the code.

Writing good acceptance criteria

  • Write them before coding, together with the product owner and a tester, so developers and testers share the same picture.
  • Prefer examples with concrete numbers to abstract rules. Boundaries ("exactly the balance", "one cent over") are where bugs live; see test design techniques.
  • Cover the happy path, key alternatives and error cases, but keep the set small. Ten scenarios per story usually signals that the story is too big.
  • Keep criteria independent of the interface unless the interface is the requirement.
  • Include non-functional criteria when they matter ("results appear in under 2 seconds").
  • Define the team's Definition of Done separately: the common checklist (reviewed, tested, documented) applied to every story, as discussed in Scrum in practice.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which part of a user story is most often skipped, and why does it matter?

    The benefit tells the team why the feature exists, which guides design choices and shows when the story is done.
  2. 2. What does the 'S' in INVEST ask for?

    Small stories can be estimated, finished and demonstrated within an iteration. Large ones are epics and should be split.
  3. 3. In a use case, what is an extension?

    Extensions describe what happens when a step goes differently, such as a wrong PIN or too little balance.
  4. 4. Which Given/When/Then line belongs under 'Then'?

    'Then' states the observable result. 'Given' sets the starting state and 'When' names the action.
  5. 5. Why is 'As an admin, I want to create the users table' a weak story?

    Valuable stories deliver something a user or the business can use. Technical tasks belong inside stories that deliver value.

Summary

  • A user story states role, capability and benefit briefly and starts a conversation; INVEST helps judge its quality and epics should be split by workflow, rule or data, not by layer.
  • A use case lists a goal, preconditions, a main success scenario, extensions for alternative and error paths, and postconditions.
  • Acceptance criteria confirm a story is done; Given/When/Then expresses them as concrete, automatable examples.
  • Write criteria early, with concrete numbers and boundaries, and keep them independent of the interface.

Next: The Software Requirements Specification.