by Inflectra on Thursday, April 25, 2024

What is Acceptance Criteria? Formats, Examples, & How to Write

Clear communication and well-defined goals are critical to any project, but especially those in software development. Let's discuss acceptance criteria, why they’re important, different formats, how to write them (including replicable examples), and some of the top tools for organizing them.

What is Acceptance Criteria?

Beginning with the basics, acceptance criteria are defined as a set of predetermined conditions that a software feature or functionality must meet to be considered “complete” and accepted by the stakeholders, users, or other systems it interacts with. Think of them like a checklist for each aspect of the final product so everyone is on the same page about what "done" looks like.

Why Do You Need Them?

Acceptance criteria serve several important purposes throughout the development pipeline:

Clarity and Alignment: They eliminate ambiguity by clearly defining expectations so that developers understand what to build, testers can effectively assess functionality, and stakeholders have a defined way to measure success.

Improved Communication: Acceptance criteria also facilitate clear communication across all parties involved because conversations about features can be more focused, resulting in fewer misunderstandings and reworks.

Reduced Risk: Defining success from the start helps surface potential issues earlier in the development process, which reduces the risk of delivering a product that doesn't meet user needs (or requires costly fixes down the road).

Objective Evaluation: Lastly, acceptance criteria provide an objective basis for evaluating a feature's completion and functionality. This allows for more structured testing so decisions about progress are driven by objective data and benchmarks.

Who Writes Acceptance Criteria?

In Agile methodologies like Scrum and Kanban, the responsibility of writing acceptance criteria typically falls on the Product Owner. They represent the voice of stakeholders and should have a robust understanding of user needs. However, remember that collaboration is key — developers, testers, and other team members should still contribute their expertise during the creation of these criteria (even if the final writing is done by the Product Owner).

When Should Criteria be Written?

While the timing may vary from project to project, the ideal stage to write acceptance criteria is typically as user stories are being refined. This is because acceptance criteria build on top of the user stories, detailing specific functionalities and success metrics (more on this relationship later).

Definition of Done vs. Acceptance Criteria

As mentioned earlier, acceptance criteria can be thought of as a checklist for when a feature is considered “done.” This might sound familiar, as Definition of Done (DoD) is another project management term that is sometimes used interchangeably. While they are closely related, these two terms do have distinct roles and definitions:

Definition of Done: This broader concept outlines the overall criteria for a work item to be considered finished. It may encompass coding standards, code review completion, and successful unit testing.

Acceptance Criteria: These focus specifically on the functionality and behavior of one user story, ensuring that the designated feature delivers the expected value to the user.

Types of Acceptance Criteria Formats

Now that we’ve discussed the general concepts and importance of acceptance criteria, it’s time to cover the two common formats used for writing them. There isn't a one-size-fits-all approach to this and it depends on the specific feature and its complexity. However, here's a general rule of thumb to keep in mind before we get into the specifics of each:

Scenario-oriented: Versatile choice that works well for most user stories, especially those with user interactions.

Rule-oriented: More suitable for capturing technical requirements or very simple functionalities.

Scenario-Oriented (Given/When/Then) Format

This popular format structures acceptance criteria using a clear and concise breakdown of information following three stages. Each criterion follows this format:

Given: [The initial state of the system or the context before the user interacts with it.]

When: [The action the user takes within the system.]

Then: [The expected outcome or system behavior resulting from the user's action.]

Example:

Given: A user is logged in to the e-commerce platform. (Sets the context)

When: The user searches for "running shoes" in the search bar. (Defines the user action)

Then: The system displays a list of products categorized as "running shoes." (Specifies the expected outcome)

By emphasizing user actions and expected outcomes, this format ensures that each of the criteria aligns with user needs. Each criterion also becomes a miniature test case, making it easier to verify if the feature functions as expected.

What is Gherkin?

Gherkin is a human-readable language designed specifically for writing behavior-driven development (BDD) scenarios. It leverages the Given/When/Then structure explained above to create acceptance criteria that are clear and concise.

Rule-Oriented Format

This criteria format is less common but uses short statements to define specific rules or functionalities the feature must follow. It's useful for capturing technical requirements and system behavior or for simple features with straightforward functionalities.

Example:

The system should allow users to upload profile pictures with a maximum size of 2MB.

All user passwords must be at least 8 characters long and contain a combination of letters and numbers.

User Stories & Acceptance Criteria

At this point, it should be clear that user stories and acceptance criteria are closely intertwined throughout the software development process. They work together to ensure a feature is built from start to finish to provide the promised value to end users.

User Stories vs. Acceptance Criteria

User stories and acceptance criteria are like two sides of the same coin. However, it’s important to understand the differences between these two (i.e. where one stops and the other begins).

Think of a user story as a simple wish list. It describes what a user wants to achieve, written in plain language from their perspective. For example, a user story might say: "As a customer, I want to search for products by category so I can easily find what I'm looking for."

Acceptance criteria, on the other hand, go deeper into technical functionalities. They translate the user story's desires into concrete details about how the feature should operate. For the product search example above, acceptance criteria might define that the search bar is visible, accepts keywords or product names, and filters results as the user types.

The user story outlines the "why" behind a feature (the problem it solves or the value it delivers to the user) and acceptance criteria focus on the "what" (specific functionalities and behaviors that need to be implemented to turn that user story into reality).

Examples of User Stories & Acceptance Criteria

Example User Story: As a customer, I want to search for products by category so I can easily find what I'm looking for.

Acceptance criteria:

The search bar should be visible at the top of every page.

Users can enter keywords or product names.

The search results should be displayed dynamically and update as the user inputs words or phrases.

Products should be categorized with the ability to filter by type, brand, and color.

Example User Story: As an administrator, I want to be able to manage user accounts so I can add, edit, and delete users.

Acceptance Criteria:

The system should display a list of all registered users.

Administrators can add new users by providing their name, email address, and password.

Administrators can edit existing user information.

Administrators can remove user accounts from the system.

The system should enforce password complexity rules. (Note: This might involve another user story and set of acceptance criteria to define)

Best Practices for Developing Acceptance Criteria

Now that we understand the different formats and have a few examples in mind, it’s time to start writing your acceptance criteria. Here are some best practices and tips to get clear and effective criteria:

Emphasize Collaboration

By involving stakeholders, developers, and testers in creating acceptance criteria, you can hear diverse perspectives and expertise. This results in a more comprehensive set of criteria that more effectively considers needs, feasibility, and requirements. Working together early in the process can help identify potential problems or misunderstandings before they become issues, reducing the risk of complicated fixes later in the development cycle when changes become more costly.

Focus on Outcomes

Spotlighting the desired outcome instead of a particular implementation path gives the development team the freedom to choose the most efficient way to achieve it. This might lead to more innovative solutions and allows non-technical stakeholders to better understand the feature's purpose without getting bogged down in details.

Prioritize Clarity & Conciseness

Similar to where we left off in the previous section, use clear and concise language that everyone involved can understand. Avoid technical jargon so there’s no room for misinterpretation. Another reason to incorporate this is that well-written acceptance criteria can also serve as helpful documentation, providing a clear understanding of the feature's purpose and behavior.

Testability is Paramount

Testable and measurable criteria allow for objective assessment of whether a feature/user story is complete. This removes subjectivity from the equation and assures that quality is maintained. When acceptance criteria are provably met through testing, there's very high confidence that the feature functions as intended, which mitigates risks and surprises down the road.

Maintain Traceability

Attaching and linking these criteria to user stories ensures that the developed features directly address defined user requirements. This helps to avoid scope creep and keeps the project focused on delivering value. If changes are needed, traceability helps clarify which user stories and criteria might be affected so you can make informed decisions about project adjustments.

Refine as Needed

Projects often evolve and change, which means that requirements will also need to shift. Re-evaluating acceptance criteria throughout the process keeps them relevant and reflects the most up-to-date understanding of the feature. However, keep in mind that it’s important to inform stakeholders of any modifications so that everyone is on the same page.

Examples of Bad Acceptance Criteria

On the opposite side, let's look at some examples of poorly written acceptance criteria and see why they fall short:

Ambiguous: "The system should be user-friendly." (This is subjective and lacks specifics on what constitutes “user-friendly”)

Implementation Focused: "The login button should be red." (This dictates implementation details instead of focusing on functionality)

Untestable: "The search function should be fast." (This lacks a clear definition of "fast" and how to test/measure it)

Incomplete: "The user can edit their profile information." (This doesn't specify which information can be edited)

Unrealistic: "The system should be able to handle 100,000 users simultaneously." (This might not be feasible within project constraints)

Duplicative: "The system should allow users to search by product name.” and “Users can search by product category." (These can be combined into a single, more concise criterion)

Negative Wording: "The system should not crash when there are many users logged in." (Phrasing it positively as "The system should be able to handle 50 users concurrently" is clearer)

Jargon-Heavy: "The system should utilize robust encryption algorithms to ensure data security." (Use simpler language everyone can understand)

Tools for Documenting Acceptance Criteria

It’s great to discuss and brainstorm acceptance criteria with your team, but you also need a way to document, organize, and track these — both through the current project and also for reference in future projects that might share similarities or templates. Here are some commonly used tools:

Jira: This popular Agile project management tool allows for the creation of user stories, linking acceptance criteria to them, and tracking their completion status. Teams can also use Jira for test case management, so criteria are thoroughly tested. NOTE: Atlassian has stopped supporting Jira Server as of February 2024, so other alternatives might be preferred for those looking to scale and receive ongoing help from their provider.

Trello: A popular Kanban-based project management tool, Trello offers boards, lists, and cards for organizing user stories and acceptance criteria. While not as feature-rich as other platforms, Trello's visual interface can be helpful for simple projects.

Asana: One of the most popular project management tools, Asana offers user story and task management functionalities and allows attaching criteria to tasks, which supports team collaboration and clarity.

Xray: A plugin for Atlassian Jira, this is specifically designed for managing test cases. Its narrow functionality integrates with Jira allowing teams to create and manage acceptance criteria alongside their test cases. NOTE: Atlassian has stopped supporting Jira Server as of February 2024, so other alternatives might be preferred for those looking to scale and receive ongoing help

SpiraTeam: For those looking for an all-in-one comprehensive Application Lifecycle Management tool, SpiraTeam incorporates out-of-the-box features for managing requirements, including acceptance criteria. It also allows linking these criteria to user stories, defining test cases, tracking their execution, and much more.