I recently started writing user stories and acceptance tests. My first drafts of acceptance tests were bad. There was little clarity around what I would actually be delivering to the client and a lot of ambiguity.

It’s important to make sure you and the client, whether that person is part of you own company or a company that you are consulting for, are on the same page. The last thing you would want would be to do a week’s worth of work and then have the client disagree with the deliverables.

The Given/When/Then strategy for writing user stories and acceptance tests made it significantly easier for me to think through all the features needed and estimate how long it would take to complete the features.

User Story

What is a user story? It’s a description of an objective a person should be able to achieve when using your website/application/software.

I’ve found two very similar formats for user stories:

  • As a [role] I want [action] so that [achievement].
  • As a [role] I need [action] in order to [achievement].

Example: As a user, I want to upload a profile picture so that other members can see my picture.

Acceptance Criteria

It’s pretty clear that my example user story doesn’t provide much explanation. Based on this user story, you certainly wouldn’t be able to start coding with any confidence that you were building the same thing the client was expecting.

Acceptance criteria are added to user stories in order to provide a more detailed description and help software engineers start building the product. Acceptance criteria define the boundaries of a user story, and are used to confirm when a story is completed.


Now we need a template for writing accurate, thorough acceptance criteria and that’s where the Given/When/Then strategy comes in.

Here’s the basic template:

  • Given (some context) and (some other optional context)
  • When (some action is carried out)
  • Then (a set of observable consequences should occur)


Story: As a user, I want to upload a profile picture so that other members can see my picture.

Acceptance Criteria: Given a user is logged in and looking at their profile, when a user clicks on the update profile picture link below their profile picture, then the user is prompted to upload a new picture from their computer directory and the selected picture becomes the current profile picture.

Phew, that is a long explanation of the story, but at least we now have much more clarity around the client’s expectations.


Leave a Reply

Your email address will not be published.