One sentence that says who wants what
A user story is one short sentence that says who wants something, what they want and why. Its acceptance criteria are the checks that show the story is done.
Stories keep a team talking about people instead of features. Checks give everyone the same answer to "is it finished?".
By the end of this lesson
Note
I can write a user story with acceptance checks.
Key words
| Word | What it means | Example |
|---|---|---|
| User story | one sentence saying who wants what, and why | |
| Acceptance check | a test that shows a story is done | Given, when, then |
| Given | the starting state before the action | |
| When | the action the person takes | |
| Then | the result you can see | |
| Definition of done | the checks that must all pass |
The cells students fill in are left blank in this preview.
A user story has three parts
The usual shape is: As a person, I want something, so that I get a benefit. The first part says who. The second says what. The third says why.
The reason matters most. If a better way exists to give the same benefit, the team can offer it.
Worked example: three stories for the booking system
| As a | I want | So that |
|---|---|---|
| lecturer | to see only my own bookings | I can plan my week |
| student | to book a room for a group | we have somewhere to work |
| lecturer | to cancel a booking | another group can use the room |
The cells students fill in are left blank in this preview.
Acceptance checks use given, when, then
A story alone is too loose to test. Add acceptance checks, each in three parts. Given says the starting state. When says what the person does. Then says what they see.
Take the story "As a lecturer, I want to see only my own bookings." Here is one check.
Given Asha has two bookings and Ben has one, when I ask for Asha's bookings, then I get two.
Run an acceptance check on the lab
The lab holds that exact state. Make the table, then ask the API for Asha's bookings with a filter in the address. The check passes if two rows come back.
Both rows are for Lab 2, one on Monday and one on Tuesday.
Give psql the password
export PGPASSWORD=shopShown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Make the bookings table
psql -h db -U shop -c "drop table if exists bookings; create table bookings (id serial primary key, room text not null, slot text not null, booked_by text not null, hours int not null, status text not null default 'booked'); insert into bookings (room, slot, booked_by, hours) values ('Lab 2', 'Mon 10:00', 'Asha', 2), ('Lab 4', 'Mon 10:00', 'Ben', 1), ('Lab 2', 'Tue 14:00', 'Asha', 3); notify pgrst, 'reload schema'"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Ask for Asha's bookings only
curl -s -w "\n" "http://api:3000/bookings?booked_by=eq.Asha&select=room,slot&order=id"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A common mistake
Warning
Many people think one passing check proves a story is done. One check shows the main case only. Add a check for a person who must not succeed, such as someone cancelling a booking that is not theirs.
A second story: cancelling a booking
Story: as a lecturer, I want to cancel a booking so that another group can use the room. Check: Given Asha booked Lab 2 (booking 1), when I cancel it, then its status is cancelled.
The first Run cancels booking 1 and prints the status code 204, which means done, nothing to send back. The second reads booking 1 and shows its status.
Cancel booking 1
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"status":"cancelled"}' "http://api:3000/bookings?id=eq.1"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
Read booking 1's status
curl -s -w "\n" "http://api:3000/bookings?id=eq.1&select=status"Shown here, not run. Create a free account to press Run and type it into your own lab’s terminal.
A good story is small and testable
Keep a story to one person and one benefit. "As a user I want to manage bookings" hides a dozen stories: book, move, cancel, list. Split it.
A story is ready when it has a who, a want and a why. It also needs at least two checks. One shows it working and one shows it refusing.