Documenting acceptance criteria as individual scenarios


Anti-patterns in BDD

Working with BDD can be a great way to increase collaboration and conversation between team members. It can help teams with their shared understanding and keep teams on track with their delivery. However, succeeding with BDD requires patience, teamwork and feedback - both on what works and what doesn’t work for your team.

Working as a team can be fraught with anti-patterns, whether they’re caused by biases, losing sight of common goals, or relying too heavily on tooling. In this series, we are looking at some of these anti-patterns, uncovering what they look like, how they are formed, and how they can be avoided.

In today’s article, we’ll dig deeper into the anti-pattern of documenting all acceptance criteria as individual scenarios.

Documenting all acceptance criteria as individual scenarios

Imagine you are collaborating on the following user story:

Story: user registration
As a new user
I want to be able to register an account
So that I can access our products services

Acceptance criteria:

  • Registration page contains a form with the following fields

  • Email address

  • Password

  • Submit

  • The email field must contain a valid email address

  • The password field must contain at least one capital letter, lower case letter and number

  • Submitting the registration page form will create a new account

The agile team begins to create scenarios after writing acceptance criteria and produces the following:

Given I am an unregistered user
When I navigate to the registration page
Then there is an email input field

Given I am an unregistered user
When I navigate to the registration page
Then there is a password input field

Given I am an unregistered user
When I navigate to the registration page
Then there is name input field

Given I am an unregistered user
When I navigate to the registration page
And I enter an email address
Then the email address must be valid

Given I am an unregistered user
When I navigate to the registration page
And I enter a password

Then the password must contain a capital letter, a lowercase letter and a number

The scenarios go on and on, with all the individual acceptance criteria captured as individual scenarios. We end up with feature files that contain long, boring scenarios that are hard to maintain.

Why is documenting all acceptance criteria as individual scenarios an anti-pattern?

Building scenarios with a one-to-one relationship to acceptance criteria is an anti-pattern because it leads to a challenge in maintaining overly long feature files. A large number of scenarios for one feature negatively affects value and team engagement, which is definitely not what BDD is all about:

  • The volume of scenarios and their wording make it hard to appreciate the value of the feature.

  • People are less likely to engage with scenarios in a meaningful way since there is so much to read.

Additionally, this approach leads to scope creep. While there will always be a chance that small individual criteria are missed during the analysis phase, the problem arises when they are picked up later, and the temptation is to add scenarios without discussing it with the rest of the agile team. Not only does this lead to scope creep, but it also creates a bias in the agile team towards turning scenarios into test cases which is an anti-pattern in its own right.

What’s the solution?

Focusing on how to create unique and engaging examples will help to resolve this anti-pattern and establish good BDD practice.

When we are in collaborative sessions we use examples as a way to share our ideas so that others gain more insight into our ideas. One of the powerful aspects of examples is that they can include many details in just a few lines. Referring back to our registration example from before, we can say:

"I would go to the registration page. Enter my name ‘Mark’, email address ‘’ and my password ‘Passw0rd123’ before clicking ‘Register’. My account is then created and I can log in.

This example could then be translated into Gherkin syntax for future use, like so:

Given I am a new user of the product

When I register the following details

Given I am a new user of the product
When I register the following details
  | name | email                                      | password    |
  | mark  | | Passw0rd123 |
Then a new account will be created for me

With relatively few examples, we can clearly explain how a product works and avoid creating paragraphs of information. During a collaborative session, agile team members can raise any questions about the examples and agree on the scenarios. At the end of the collaborative session, they can decide which examples matter, and which don’t, and then formalise the examples using Gherkin syntax.

This results in a series of unique and engaging examples that fully and clearly describe the feature we want. The volume of scenarios is low, and they allow teams room to accommodate any additional small criteria that might crop up because the main behaviour has been discussed, agreed and captured.

So, in a collaborative session, aim to steer the conversation towards giving examples and writing them down; there are techniques you can use to organise your examples such as example mapping. Additionally, if a product owner, business analyst or any other business stakeholder joins a collaborative session and has some acceptance criteria in mind, you can use examples to illustrate the acceptance criteria rather than list the individual criteria down. By doing this you will avoid large amounts of examples, and the ones you have will be valuable and also useful in the future.

There's more where that came from...

This is blog post 3 of our 4 part anti-pattern series. You can find links to these below:

Anti-pattern post 1 - Missing an amigo

Anti-pattern post 2 - Using scenarios as test cases

Anti-pattern post 4 - Automated scenarios is enough test coverage

About the author

Mark Winteringham, aka @2bittester , is a coach, teacher, mentor, tester and international speaker, and ranked joint 8th in Agile Testing Days 2017 list of most influential agile testing professionals. Mark has worked on award-winning projects using various web, mobile and desktop technologies and he has been an agent for change for clients across a wide range of sectors, implementing successful BDD and automation in testing strategies. Mark’s focus for the past year or so has been educating teams on how not to use BDD, and he co-developed and delivers the Hindsight 2-day BDD & Cucumber training course.

You may also like…