Imagine that you ask your development team to enable users to search for a product in an online bookstore by category. You expect a straightforward interface with category links to click on (e.g., fantasy, nonfiction, 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.
There must be high-quality software documentation to prevent such issues from happening and provide a solution that meets customer needs and achieves a product/market fit. 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 to describe what the user wants the system to do, the goal of acceptance criteria is to explain the conditions a specific user story must satisfy.
In this post, we’ll focus on acceptance criteria: We’ll clarify their purposes, formats, and best practices on how to write AC effectively. We will also provide acceptance criteria examples.
What are the acceptance criteria and their roles in projects?
Acceptance criteria (AC) are the conditions 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.
Well-written acceptance criteria help avoid unexpected results at the end of a development stage and ensure that all stakeholders and users are satisfied with what they get.
Good acceptance criteria should possess specific qualities.
Clarity: They should be straightforward and easy to understand for all team members, avoiding any confusion.
Conciseness: The criteria should communicate the necessary information without unnecessary detail.
Testability: Each criterion must be verifiable, allowing testers to clearly determine whether it has been met.
Result-oriented: The focus should be on delivering results that gratify the customer, emphasizing the end benefit or value.
It’s important to note that acceptance criteria describe what the end result should be, not the process of achieving it. For instance, a criterion like “The system should allow users to filter search results by date, price, and location” clearly states the desired functionality without detailing how the feature should be implemented.
Another important aspect regarding acceptance criteria is that they must 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. But we’ll get to this later.
User story vs. acceptance criteria
In Agile development, teams identify the broadest, high-level objectives as epic-level requirements and actively break them into smaller chunks, such as user stories and acceptance criteria. Although user stories and acceptance criteria are closely related, they each serve distinct functions in the development process.
Acceptance criteria are the lowest-level functional requirements
User stories provide a high-level understanding of a feature from the user’s perspective, focusing on the what and why. They are narrative, flexible, and centered on user needs.
The standard format is a single sentence structured as follows:
As a <type of user>, I want to <perform some action> so that <some reason or benefit>.
As a traveler, I want to choose airplane seats online so that I have a window seat.
The user role: “As a traveler”
The action they want to perform: “I want to choose airplane seats online”
The reason or benefit: “so that I have the window seat”
Acceptance criteria, as mentioned, are detailed conditions that a feature must meet to be considered complete. They are more technical, offering a checklist that ensures the feature behaves as intended from an end-user perspective.
While user stories describe the desired outcome, acceptance criteria outline the necessary steps to achieve that outcome, ensuring alignment with user expectations.
Definition of done vs acceptance criteria
While some may use the definition of done and acceptance criteria interchangeably, they are different and have distinct roles.
The definition of done (DoD) is a checklist every user story must meet for the team to consider it complete, ensuring consistent quality across the project. For example, the DoD might include requirements like fully integrated and peer-reviewed code, all unit tests passed, complete documentation, no unresolved bugs, and final approval from a product owner for each story.
In contrast, acceptance criteria are specific to each user story, including test scenarios that confirm the software functions as expected for that feature.
So the key difference between the definition of done and acceptance criteria lies in their scope and application: DoD is a universal standard applicable to every user story within a project, while acceptance criteria vary from one user story to another, tailored to meet the unique requirements and functionality of each story.
Acceptance criteria main purposes
Clarifying the stakeholders’ requirements is a high-level goal. To make the purposes of AC more transparent, 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. An invalid password format is an example of a so-called negative scenario when a user makes 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 everyone is on the same page regarding the requirements: Developers know exactly what kind of behavior the feature must demonstrate, while stakeholders and the client understand what to expect.
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. You can also use AC to verify the story via automated tests.
Conducting feature evaluations. Acceptance criteria specify what exactly must be developed by the team. Once the team clarifies the requirements, they can divide user stories into tasks, enabling accurate estimation.
Since different people can have different points of view and solution ideas regarding one problem, creating a unified vision of implementing the functionality is necessary. That’s precisely what well-written acceptance criteria do.
Acceptance criteria examples and formats for user stories
Based on the initial task and the complexity of requirements, you can choose between different acceptance criteria formats, namely:
- scenario-oriented (the Given/When/Then acceptance criteria template);
- rule-oriented (the checklist acceptance criteria template); and
- custom formats.
Most commonly used, the first and the second acceptance criteria types 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.
Scenario-oriented acceptance criteria format (Gherkin 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. You can approach it 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, inherited from behavior-driven development (BDD), adopts Gherkin — a domain-specific language for writing acceptance criteria. Gherkin acceptance criteria format helps testers define when to begin and end testing a particular feature. It also reduces the time spent writing test cases as the team describes the system’s behavior upfront.
The acceptance criteria, when framed using Gherkin, follow a template with five main 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 example in the Given/When/Then format
By utilizing this template, teams can articulate acceptance criteria more precisely, ensuring clear and efficient communication between developers, testers, and stakeholders.
Let’s look at some examples.
The Given/When/Then acceptance criteria example 1
User story: As a website 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
The Given/When/Then acceptance criteria example 2
User story: As a bank card user, I want to be able to request 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
Sometimes, it’s challenging to fit acceptance criteria into the Given/When/Then structure. For instance, GWT would hardly be useful for the following circumstances:
- 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 described design and user experience constraints of a feature. Developers may miss some 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.
Rule-oriented acceptance criteria example
User story: As a traveler, I want to search by city, name, or street, so that I can have more 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 acceptance criteria formats
The two formats mentioned above cover most of the user stories. However, you can invent your 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 that 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 the writing of 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.
Who writes acceptance criteria?
The collaborative nature of cross-functional teams allows different team members to create acceptance criteria for user stories. Typically, the product owner is the person who starts the process of defining and writing some criteria while forming the sprint backlog.
In more complex scenarios, this task may shift to a business analyst, requirements analyst, or project manager who may take over writing acceptance criteria, especially in more complex scenarios. Even 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.
The process starts with user story prioritization and ends with negotiating details with the whole team
Throughout the project, the role of refining and expanding acceptance criteria can be taken up by different team members, ensuring diverse perspectives and comprehensive coverage of user needs.
To learn more about software planning and documentation, check out our video.
When to write acceptance criteria?
Effectively timing the documentation of acceptance criteria is crucial for capturing all customer needs and aligning development efforts. A practical approach is to define these criteria during the early stages of the project or before each sprint. But how early and when exactly?
In Agile development, defining and adapting acceptance criteria occurs at multiple stages.
Initial stage. At the start of the project, the team defines acceptance criteria for the first few sprints. This early-stage planning helps set a clear direction for the onset of development.
Before each sprint. As the project progresses, it’s a common practice to write acceptance criteria any time before the user story is ready to enter sprint planning. Typically, this occurs during backlog grooming sessions, when the team progressively develops and adds acceptance criteria to each user story planned for the next sprint.
Finalization at the sprint planning. Then the team finalizes AC during the sprint planning events. Once a sprint starts, it’s crucial to avoid changing acceptance criteria as they form the basis of what the team commits to delivering.
Potential mid-sprint adjustments. In certain cases, if acceptance criteria don’t block the ongoing work or significantly alter the scope and effort required, they can be adjusted during the sprint. However, it’s rather the exception than the rule: According to Scrum principles, once a sprint starts, it’s important to avoid any changes in requirements, story items, or dates, as such alterations could lead to rework and potentially jeopardize the development team’s ability to successfully meet their commitments.
With this understanding of when to write acceptance criteria, let’s now explore how to write them effectively.
How to write acceptance criteria? Best practices and general tips
Acceptance criteria look as if they are effortless to write. Despite their simplistic formats, the writing poses a challenge for many teams. We have collected some recommendations on how to write acceptance criteria like a pro.
Writing acceptance criteria best practices
First, have a deeper look at the best practices that help avoid common mistakes when writing your AC.
Don’t make AC too narrow. Acceptance criteria can be way too specific leaving 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 if 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 correctly.
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.
General tips on writing acceptance criteria
If you need more guidance on how to phrase your acceptance criteria so that they are easy to follow, here are a few valuable recommendations.
Write in active voice, first-person. Active voice is when the subject of a sentence performs the action (verb). Sticking to an active voice is a standard 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. However, 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 a single 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.
Writing acceptance criteria in Jira
Jira is one of the most widely used project management software programs for Agile teams. While a powerful tool, it doesn’t offer built-in features specifically for handling acceptance criteria. However, teams can effectively manage these criteria in Jira using several methods.
Using the Description Field. You can write the acceptance criteria in the issue’s description field, although this method might be less organized as the criteria can get lost in other content.
The Description Field can be found in system fields when you select Issues. Source: Atlassian documentation
Creating a Custom Field. It’s possible to add a custom field for acceptance criteria. This involves accessing the project settings, selecting issues, and creating a custom field using the “paragraph” option for rich text support. This field then appears on the issue screen, providing a dedicated space for acceptance criteria.
Using a Checklist App. Another alternative is to use a checklist app — like Issue Checklist Pro or Issue Checklist Free — from the Atlassian Marketplace. These apps allow you to create customizable checklists for acceptance criteria, with features like workflow validation, to ensure all checklist items are completed before an issue transitions to another status.
By adopting one or a combination of these approaches, you can effectively manage and track acceptance criteria within Jira, aligning your software development process with project goals and customer requirements.
Last but not least, 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. 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.
• • •
Originally published at https://www.altexsoft.com