BlogAnatomy of a User Story: BDD Scenarios

In my previous installment about user story acceptance criteria, I focused specifically on the rules-oriented style which informs about a feature’s end-state. That is, when it is released, the user must be able to do a list of things (and sometimes, NOT do).  In my experience, I can author this type of criteria relatively quickly, and they are easily consumable by anyone reading the user story.  I tend to add items to this list as soon as I write the story narrative. My brain is already in gear thinking about the user’s needs and outcomes, and they are fast to jot down.

Scenarios: Given, When, Then

The other popular form of writing acceptance criteria is the scenario-oriented acceptance criteria (or behavior driven development / BDD approach). The format takes the “GWT” form of:

GIVEN a state

WHEN a condition (event trigger) occurs

THEN we transition to another state (and/or something else happens).

I’ll admit:  I love user story scenarios because they hearken back to state machine / state transition diagrams from my days in engineering. And I think scenarios are easier to explain when we use diagrams:

The above example above shows how we could implement a keyword search for students who want to search for courses in a learning system. Each of the circles represent states (GIVEN and THEN), the arrows are conditions (WHEN) that prompt state transitions. So from this, I will write some scenarios from this fictitious user story:

GIVEN I am viewing the list of available courses

WHEN I open the search bar

THEN I can enter in search keywords

View all courses TO Search keyword entry

GIVEN I have entered search keywords

WHEN I kick off the search

THEN I will see my search results

Search keyword entry TO View search results

GIVEN I have entered search keywords that don’t exist in the system

WHEN I start the search

THEN I will see that no results were found

Search keyword entry TO No results found

GIVEN my search didn’t yield any results

WHEN I click to search again

THEN I will be able to enter new search keywords

No results found TO Search keyword entry

While I didn’t write the complete set of scenarios, nonetheless see that the state transitions are covered in each scenario.  By the way, we can always write more scenarios than state transitions (i.e. the arrows) to cover nuances of the user’s experience, but we should consider at least writing a scenario for each major transition arc.

Positive and Negative / Exception Scenarios

Remember in the previous installment when we talked about the need to occasionally write negative / exception acceptance criteria?  It’s important here, and in fact more-so.  Rules-oriented criteria capture the end result, and typically written in the positive sense.  However, scenario-oriented acceptance criteria often walks through user flows, and as we know users tend to divert around where we want them to go.  So in scenarios, we should cover warnings and error messages, and other non-“happy-path” flows which developers need to code anyway during implementation.

BDD Scenarios vs. Rules-Oriented Acceptance Criteria

Writing scenarios is quite different from writing rules-oriented acceptance criteria.  Beyond the GWT format, clearly a lot more writing is required for scenarios.  In fact, as much as I try, it is difficult to write scenarios without referencing actual or anticipated UX designs.  For the example above, even though designs aren’t yet created, our language tends to assume a search bar, a search button, clear search button, etc. will exist in the UX.  Some imagination is necessary to conceive of how the user will experience a scenario, and all the error cases that can result.

This is as opposed to a rules-oriented approach, where we could have simply written:

1. User must be able to search for a course by keyword.
2. User must be notified if no search results were found.
3. User must be able to clear search results to view all courses again.

(By the way, I’ll argue that moving from the “no search results found” state back to search again doesn’t need to be written here as rules-oriented acceptance criteria.  It’s dependent upon the UX.)

So when do we use the scenario versus rule-oriented approach?  Well, at Planorama, we use both.

Better together

When we kick off a new user story, I begin with the narrative and rules-oriented acceptance criteria.  Both are relatively quick to write and capture the essence of what’s needed.

Then in our UX design sprints, our designers flush out assigned user stories.  This is where the scenarios play in.  As the initial designs begin to gel into user flows through a feature, we see scenarios naturally take shape.  We also see the negative / exception criteria surface, and create UX designs + scenarios to cover them too.  So we create the UX designs and write the story’s scenarios at the same time.

The result is a complete user story, accompanied by the UX designs, that covers both types of acceptance criteria.  The rules-oriented criteria helps software QA decide where to spend effort on positive and negative tests, and the scenario-oriented criteria is also helpful to QA, and especially to software developers, giving them precise user flows with UX that translates into code implementation.