Given/When/Then Works Incredibly Well

When I am preparing development work, I write Gherkin-style stories, which follow the “Given/When/Then” format. I learned this technique at Hashrocket and have practiced it ever since. It’s incredibly effective. But why? In this post, I’ll try to answer that question.

I can think of two arguments for this technique: images and words hide complexity, while stories expose complexity.

Words and Images Hide Complexity

Words and images hide complexity.

When I’ve worked on teams that don’t widely use Gherkin syntax, we encounter a different version of this problem again and again:

“I finished the ticket and shipped it to QA, but then I noticed this one little thing I missed. I’m working on that now.”

That “little thing” is often significant. It might be a change to functionality, an important use case, or a key requirement that blocks shipping.

This is rework, and rework is bad. Why do these details, that were written in the ticket, get missed? Because words hide complexity.

Here’s a part of that fateful ticket:

“Then when they finish filling out the form, if they’re a new customer, they’ll be redirected to the welcome page, and if they’re an existing customer, they’ll be redirected to their dashboard. Unless they’ve come from our holiday marketing page– always send those people to the refer-a-friend page.”

There is so much complexity hiding this paragraph… three stories at least! Many tickets I’ve seen contain multiple paragraphs like this. They omit information, duplicate information, and contradict themselves. That’s our brains work when dumping information.

Images are even higher bandwidth than stories and can be even more confusing. Put two engineers, a designer, and a stakeholder in front of some wireframes and ask them to describe what a page does. It’s amazing how many disagreements can arise.

Stories Reveal Complexity

So, what’s the solution? Gherkin stories. Stories reveal complexity. The format is designed so that complexity has nowhere to hide.

Let’s take our previous wall of text and turn it into stories.

“Then when they finish filling out the form, if they’re a new customer, they’ll be redirected to the welcome page, and if they’re an existing customer, they’ll be redirected to their dashboard. Unless they’ve come from our holiday marketing page– always send those people to the refer-a-friend page.”

Where does this behavior start? We ask the question and learn that it starts on the checkout page.

Given I am on the checkout page

Now we’re filling out that form:

Given I am on the checkout page
When I finish filling out the form

Pause; what does “finish filling out the form” mean? Are we clicking submit, blurring a field, or leaving the page? We clarify with the stakeholder: the customer is submitting the form with a labeled button, so we add that detail.

Given I am on the checkout page
When I fill out the form completely
And I click "Pay Now"

We’re already a little bit clearer!

Here’s where we get to our three-way-fork: some customers are redirected to the welcome page, some to the dashboard, and some to the refer-a-friend page. There’s no ‘if’ or ‘or’ keywords in Gherkin. If you find yourself using one, you need another story.

We need to break our story into three.

### New Customer Completes Checkout

Given I am a new customer
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see the welcome page

### Existing Customer Completes Checkout

Given I am an existing customer
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see my dashboard

### Referred Customer Completes Checkout

Given I am a new customer coming from the holiday marketing page
And I am on the checkout page
When I fill out the form completely
And I click "Pay Now"
Then I see the refer-a-friend page

What’s happening here? We’re translating a wall of text into three deliverable units of work. It’s more words, sure, but that’s the point– measured in stories, this is three stories! They might be small, but they are different experiences.

Because we wrote these stories, the engineer who is going to implement them is starting off knowing that they need to track:

1. Whether the customer is new or returning
2. Which page they may have been referred from.

The QA tester who tests the story is better off too, because they have three complete checklists to follow telling them exactly what success means.

Write Stories!

I have yet to see an alternative to this approach that works for a team. You can survive without stories with one or two engineers, but as your team grows you’re going to need them because at a certain small scale, nobody can know everything that’s going on.

• Agile