Software Development Practices: Getting Specific with Acceptance Criteria

If you’ve been following our product development practices series, you know how to think about identifying problems and articulating those problems as user stories. But even the best user story can’t encompass all of the details of the user experience that need to be considered in the development process.  This week’s post explains the important role of acceptance criteria.

What are Acceptance Criteria?

Acceptance criteria are a critical companion to user stories. They outline the specific way in which the system should behave to satisfy the user’s expectations in the story. Acceptance criteria can take several forms. The format that I typically use for acceptance criteria is similar to the 3-point form for user stories. It is

Given …
When …
Then …

“Given . . . ” is the portion of the acceptance criteria which outlines the context that the client starts from. It describes the state the system is in when the user starts interacting with it.  A good example of something that might go in this portion is whether or not the user is logged in.

“When . . . ” is the portion of the acceptance criteria which outlines the event(s) which happens. It describes the key action(s) the user performs in the UI.

“Then . . . ” is the portion of the acceptance criteria which outlines the event(s) outcome(s). It often addresses the output of the system, and may describe a report, user interface, message, command output, etc.

A complete set of acceptance criteria should include all the items that you want to use to judge whether or not the system is working the way you want. They are specific – nearly a step-by-step description of what the user will be doing in the UI and how the UI should respond. It’s important to make sure that each acceptance criteria can be tested and verified.

Creating Acceptance Criteria

Let’s look at a real world example associated with one of the stories for the demonstration application for WorldCat Registry Hours. The story is:

As a library patron,
I want to view my library’s hours and determine when the library opens and closes
so that I can pick up a book on hold.

The first acceptance criteria associated with this story is:

Given I am on the library homepage
When I go to the library hours page
Then I see the name of the library
And a section for normal hours
And the normal hours section contains a paragraph for each day of the week
And a section for special hours
And the normal special section contains a paragraph for each special hours

Think about how the system should behave for both success and failure. If you want a particular error message to appear under certain conditions, that is also an acceptance criteria.  For example, in our hours demonstration application, we need acceptance criteria to describe how the system should behave when there are no hours to display:

Given I am on a page for branch library hours
When there are no hours for that branch
Then the message “This branch has no hours” will be displayed

It is a good exercise for workflow experts and developers to work on acceptance criteria collaboratively. Working through these steps together helps everyone involved to clearly understand what should be built. At OCLC, the developers, product owners, and testers discuss and collaborate on these to make sure that they are complete. We are constantly reevaluating them as the system is developed.

When to Use Acceptance Criteria

Because acceptance criteria are used side by side with user stories, they are created fairly early in the development process. Acceptance criteria have to be completed before developers can begin work on a story. While it is possible to write them at the same time as the user stories, more often, they are written later in the release cycle just before developers work on a particular story. Writing acceptance criteria helps the team to define how a feature or piece of functionality will work from the user’s perspective and remove any existing ambiguity from the requirements.

Once the acceptance criteria are complete they are used as the basis for testing, which is the focus of our next post.