Jake Worth

Jake Worth

Given/When/Then Works Incredibly Well

Published: December 20, 2022 3 min read

  • agile

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 is incredibly effective. But why? In this post, I’ll try to answer that question.

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

Words Hide Complexity

Words hide complexity.

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

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

That little thing is usually not little. A major change in functionality, a use case that was missed, or a key requirement from a stakeholder that blocks shipping.

This is rework, and rework is bad. So why do these details, that were there in the story, get missed? Because words hide complexity.

Here’s an example of part of a story, from a 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! Most tickets I’ve seen contain multiple paragraphs like this. They omit information, duplicate information, and contradict themselves. That’s how brain dumps work.

Images are even higher bandwidth than stories and can be even more confusing. Put two developers, 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 ensures that complexity has nowhere to hide.

Let’s take that 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.”

Imagine this story starts on the checkout page.

Given I am on the checkout page

And our customer is filling out a form:

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

Hold on; 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 button, so we add that detail.

Given I am on the checkout page
When 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’re off track.

We need to break our story into three.

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

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

Given I am an existing customer coming from the holiday marketing page
And I am on the checkout page
When 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– this is three stories, not one! They might be small, but they aren’t the same experience.

The developer who is going to implement these stories is starting from a good place: they’ll know that they need to track whether the customer is new or returning, and which page they may have been referred from. The QA tester who tests the story is better off too because they have several checklists to follow telling them what passing or failing means.

Write Stories

I have yet to see an alternative to this approach that works for a team. You can get by without stories with one or two developers, but soon you are going to need them because nobody can know everything that’s going on.


Get better at programming by learning with me. Subscribe to my newsletter for weekly ideas, creations, and curated resources from across the world of programming. Join me today!