Imagine that you ask your development 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, history, etc.) After two weeks of development, you receive a search bar feature where users must type in the category they are 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.
To prevent such issues from happening and provide a solution that meets the client’s needs and fits market requirements, there has to be high-quality software documentation. Here's when user stories and acceptance criteria (AC) come into play as they are the main formats of documenting requirements.
While user stories aim at describing what exactly the user wants the system to do, the goal of acceptance criteria is to explain the conditions that a specific user story must satisfy. In this post, we'll focus on acceptance criteria: We’ll clarify their purposes, types, and how they should be written (providing examples).
Acceptance criteria, explained
What are the acceptance criteria and their role in projects?
Acceptance criteria (AC) are the conditions that a software product must meet to be accepted by a user, a customer, or other systems. They are unique for each user story and define the feature behavior from the end-user’s perspective.
Acceptance criteria are the lowest-level functional requirements
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.
An important aspect in regard to acceptance criteria is that they have to be defined before the development team starts working on a particular user story. Otherwise, there’s a decent chance the deliverables won’t meet the needs and expectations of a client.
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.
Making the feature scope more detailed. 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. Your 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 to 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 clear pass or fail scenarios. They can also be used to verify the story via automated tests.
Conducting feature evaluations. 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.
Since different people can have different points of view and solution ideas regarding one problem, creating a unified vision of how the functionality should be implemented is necessary. That's exactly what clearly written acceptance criteria do.
Acceptance criteria types and structures
Based on the initial task and the complexity of requirements, acceptance criteria can be written in different formats, namely:
- scenario-oriented (the Given/When/Then template);
- rule-oriented (the checklist template); and
- custom formats.
Most commonly used, the first and the second formats have very specific structures, so we’ll mainly 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
As the name suggests, the scenario-oriented format is the acceptance criteria type that comes in the scenario form and illustrates each criterion. It is approached through the Given/When/Then (GWT) sequence that looks like this:
- 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.
The acceptance criteria template in this format includes 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
The acceptance criteria template in the Given/When/Then format
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.
Recovering the password acceptance criteria example
Scenario: Forgot password
- Given: The user navigates to the login page
- When: The user selects <forgot password> option
- And: Enters a valid email to receive a link for password recovery
- Then: The system sends the link to the entered email
- Given: The user receives the link via the email
- When: The user navigates 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 at an ATM so that I will be able to receive the money from my account quickly and in different places.
"Requesting money from the account at an ATM" acceptance criteria example, scenario 1
Scenario 1: Requesting the cash from a creditworthy account
- 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
"Requesting money from the account at an ATM" acceptance criteria example, scenario 2
Scenario 2: Requesting the cash from an overdrawn account
- 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
As you can see from the examples, scenario-oriented acceptance criteria can be quite effective in tons of situations. But they can't be considered a universal solution.
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:
- You’re working with user stories that describe system-level functionality that needs other methods of quality assurance.
- The target audience for acceptance criteria doesn’t need precise details of the test scenarios.
- GWT scenarios don’t fit the 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.
For instance, your criteria may be specified as an example of system behavior:
A simple set of AC for strong passwords by Mark Levison for agilepainpainrelief.com
This approach provides clear guidelines for password feature testing.
Ready-to-use acceptance criteria templates
All the above-mentioned formulas for writing acceptance criteria are easy to follow and, what’s more important, effective. They ensure the development team understands the task and the user story will be implemented correctly.
In case you need some downloadable acceptance criteria templates to quickly fill in the necessary information and organize your user stories, the following resources will be helpful.
- Klariti offers the MS Excel Acceptance Criteria Log template as a part of the Software Testing Template pack.
- Aha! provides a couple of templates that will capture different user stories and acceptance criteria.
- PowerSlides includes a template in the PPT format with six dynamic designs enabling writing simple user story sentences and acceptance criteria.
- At Stakeholder Map, you can download the fully-editable Excel project requirements template that includes acceptance criteria.
Now that you have some acceptance criteria examples and templates at hand, let's deal with who should be in charge of writing these sorts of software requirements.
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.
The process starts with user story prioritization and ends with negotiating details with the whole team
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.
To learn more about software planning and documentation, check our video.
Software documentation, explained
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 upon 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 enough technical background.
Reach consensus. The same problem may 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.
Follow these tips for guidance on how to phrase your AC.
Write in active voice, first-person. Active voice is when the subject of a sentence performs the action (verb). Sticking to active voice is a common recommendation within the Agile methodology. In this way, AC reflect the actual words the user would say. The use of passive voice may make it unclear who needs what. Instead of writing “Filters should be applied in search”, try providing a more informative explanation “The user should be able to apply a set of filters to find specific items”.
Avoid negative sentences. It is always a good idea to avoid using the adverb “not” as it often makes the requirements unclear and less verifiable. Although, the use of “not” is possible when there’s the need to present unique requirements to the system functionality. Say, “The login form should not be highlighted in red when the user enters incorrect values.”
Write simple, concise sentences. It is better to use several simple sentences instead of one complex one. The fewer needless words and conjunctions like “but,” “and,” “so,” and “as well as” in your acceptance criteria, the more understandable the requirements are for the development teams.
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, 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 formats and testing the new ones that work for you is a good practice.
