Success of any project depends on the ability of a development team to meet their client’s needs. The communication between the client and the development team plays a vital role in delivering a solution that fits product and market requirements. The issues arise if customers explain their needs too vaguely and the team can’t understand clear requirements and eventually the business problem behind them. Imagine that you ask your team to enable users to search for a product in an online bookstore by categories. You expect to have a clear interface with category links to click on them (e.g. fantasy, non-fiction, historic, etc.) After two weeks of development, you receive a search bar feature where users must type in the category they interested in, instead of browsing pre-listed categories. While this also works, your initial goal was to expose all available categories and let users explore further.

This is when high-quality software documentation could help avoid the problem. User stories and acceptance criteria (AC) as the main formats of documenting requirements. A user story is a natural language description of a feature. It’s usually accompanied by acceptance criteria.

Acceptance criteria (AC) are the conditions that a software product must meet to be accepted by a user, a customer, or other system. They are unique for each user story and define the feature behavior from the end-user’s perspective. Well-written acceptance criteria help avoid unexpected results in the end of a development stage and ensure that all stakeholders and users are satisfied with what they get.

Acceptance criteria main purposes

Clarifying the stakeholder’s requirements is a high-level goal. To make the purposes of AC clearer, let’s break them down.

Feature scope detalization. AC define the boundaries of user stories. They provide precise details on functionality that help the team understand whether the story is completed and works as expected.

Describing negative scenarios. Yor AC may require the system to recognize unsafe password inputs and prevent a user from proceeding further. Invalid password format is an example of a so-called negative scenario when a user does invalid inputs or behaves unexpectedly. AC define these scenarios and explain how the system must react on them.

Setting communication. Acceptance criteria synchronize the visions of the client and the development team. They ensure that everyone has a common understanding of the requirements: Developers know exactly what kind of behavior the feature must demonstrate, while stakeholders and the client understand what’s expected from the feature.

Streamlining acceptance testing. AC are the basis of the user story acceptance testing. Each acceptance criterion must be independently testable and thus have a clear pass or fail scenarios. They can also be used to verify the story via automated tests.

Feature estimation. Acceptance criteria specify what exactly must be developed by the team. Once the team has precise requirements, they can split user stories into tasks that can be correctly estimated.

Acceptance criteria types and structures

AC can be written in different formats. There are two most common ones, and the third option is to devise your own format:

scenario-oriented (Given/When/Then)

rule-oriented (checklist)

custom formats

As the first and the second formats have very specific structures, we’ll mostly focus on them. However, you may find that other formats fit your product better so we’ll briefly touch on them as well.

Scenario-oriented acceptance criteria

Scenario-oriented format of writing AC is known as the Given/When/Then (GWT) type.

Given some precondition

When I do some action

Then I expect some result

This approach was inherited from behavior-driven development (BDD) and provides a consistent structure that helps testers define when to begin and end testing a particular feature. It also reduces the time spent on writing test cases as the behavior of the system is described upfront.

Each acceptance criteria written in this format has the following statements:

Scenario – the name for the behavior that will be described

Given – the beginning state of the scenario

When – specific action that the user makes

Then – the outcome of the action in “When”

And – used to continue any of three previous statements

When combined these statements cover all actions that a user takes to complete a task and experience the outcome.

Let’s look at some examples.

Example 1

User story: As a user, I want to be able to recover the password to my account, so that I will be able to access my account in case I forgot the password.

Scenario: Forgot password

Given: The user has navigated to the login page

When: The user selected forgot password option

And: Entered a valid email to receive a link for password recovery

Then: The system sent the link to the entered email

Given: The user received the link via the email

When: The user navigated through the link received in the email

Then: The system enables the user to set a new password

Example 2

User story:As a user, I want to be able to request the cash from my account in ATM so that I will be able to receive the money from my account quickly and in different places.

Acceptance criteria1:

Given: that the account is creditworthy

And: the card is valid

And: the dispenser contains cash

When: the customer requests the cash

Then: ensure the account is debited

And: ensure cash is dispensed

And: ensure the card is returned

Acceptance criteria2:

Given: that the account is overdrawn

And: the card is valid

When: the customer requests the cash

Then: ensure the rejection message is displayed

And: ensure cash isn’t dispensed

Rule-oriented acceptance criteria format

In some cases, it’s difficult to fit acceptance criteria into the Given/When/Then structure. For instance, GWT would hardly be useful for the following cases:

GWT scenarios don’t fit to describing design and user experience constraints of a feature. Developers may miss a number of critical details.

You can address these cases with the rule-oriented AC format.

The rule-oriented form entails that there is a set of rules that describe the behavior of a system. Based on these rules, you can draw specific scenarios.

Usually, criteria composed using this form look like a simple bullet list. Let’s have a look at an example.

Example

User story: As a user, I want to use a search field to type a city, name, or street, so that I could find matching hotel options.

Basic search interface acceptance criteria

The search field is placed on the top bar

Search starts once the user clicks “Search”

The field contains a placeholder with a grey-colored text: “Where are you going?”

The placeholder disappears once the user starts typing

Search is performed if a user types in a city, hotel name, street, or all combined

Search is in English, French, German, and Ukrainian

The user can’t type more than 200 symbols

The search doesn’t support special symbols (characters). If the user has typed a special symbol, show the warning message: “Search input cannot contain special symbols.”

Other formats

Most user stories can be covered with two formats mentioned above. However, you can invent your own acceptance criteria given they serve their purposes, are written clearly in plain English, and can’t be misinterpreted. Some teams even use plain text.

Sometimes, your criteria may be specified as an example of system behavior:

Roles responsible and how acceptance criteria are created

Some of the criteria are defined and written by the product owner when he or she creates the product backlog. And the others can be further specified by the team during user stories discussions after sprint planning. There are no strict recommendations to choosing the person responsible for writing the criteria. The client can document them if he or she has ample technical and product documentation knowledge. In this case, the client negotiates the criteria with the team to avoid mutual misunderstandings. Otherwise the criteria are created by a product owner, business analyst, requirements analyst, or a project manager.

The process starts with user story prioritization and ends with negotiating details with the whole team

Main challenges and best practices of writing acceptance criteria

Acceptance criteria look as if they are very easy to write. Despite their simplistic formats, the writing poses a challenge for many teams. Let’s have a deeper look at the best practices that help avoid common mistakes.

Document criteria before development. Acceptance criteria have to be documented before the actual development starts. This way, the team will likely capture all customer needs in advance. In the beginning, it’s enough to set the criteria for a small number of user stories to fill the backlogs for two sprints (if you practice Scrum or a similar method). They must be agreed by both parties. Then the documented acceptance criteria are used by developers to plan the technical process.

Don’t make AC too narrow. Acceptance criteria can be way too specific living little to no maneuver options for developers. To avoid this, remember that AC must convey the intent but not a final solution. Moreover, narrow AC may be bereft of multiple user behaviors that aren’t covered.

Keep your criteria achievable. This point closely intersects with the previous one. Effective acceptance criteria define the reasonable minimum chunk of functionality that you’re able to deliver. But in case you succumb to describing all little details, there’s a risk that your team will get stuck with hundreds of small tasks.

Keep AC measurable and not too broad. Broad acceptance criteria make a user story vague. Effective acceptance criteria must outline the scope of work so that the developers can plan and estimate their effort properly.

Avoid technical details. As we mentioned, acceptance criteria must be written in plain English. This will make them clear and easy to understand for everyone: Your stakeholders or managers may not have technical background.

Reach consensus. The same problem may can be solved differently by a team and stakeholders, depending on their vantage points. Make sure that you’ve communicated your AC to stakeholders and reached a mutual agreement. The same applies to team members. Everyone must review the AC and confirm they understand and agree with each line.

Write testable AC. This will allow testers to verify that all requirements were met. Otherwise, developers won’t understand if the user story is completed.

Final word

Don’t neglect the acceptance criteria as they – being simple and approachable – solve multiple problems at once. They document customer expectations, provide an end-user perspective, clarify requirements and prevent ambiguity, and eventually help quality assurance verify if the development goals were met. Regardless of whether you use Agile methods or not, make sure to choose the best format or experiment with your own ones. Different types of user stories and eventually features may require different fromats and testing the new ones that work for you is a good practice.