Ever seen a Gherkin scenario that looks like this?

Scenario: Prime customers shipping is free for Prime items

Given I access URL "https://www.amazon.com"
And I click the "Hello, Sign in" link
And the "Sign-In" page is displayed
When I enter email address "someprimeemailaddress@thisisfake.com"
And I click the "Continue" button
Then the "Password" page is displayed
When I enter email address "donotputpasswordsingherkin"
And I click the "Continue" button
Then I am logged in
And the "Home" page is displayed
When I enter "Crocs that will make me look cool" in the search textbox
And I click the hourglass image
And the search results are displayed
And "Crocs shoes" are displayed on the search results page
And I click on the first item in the search results
And the "Item Detail" page for the selected item is displayed
And I select "13 Women/11 Men" from the size combo box
And the "Inspired By" page is displayed
When I click the "Proceed to Checkout" button
Then the "Checkout" page is displayed
And there is 1 item in the order
And The Shipping & Handling cost for the order is "$0.00"
And I click the "Place your Order" button
And the "Order Placed" page is displayed

Besides searching for "Crocs that will make me look cool", what is wrong with this scenario?

In my role, I focus on QA Test Automation and I work with clients to build automated tests. Many times those tests are driven by Gherkin scenarios, and I have seen scenarios like the one above.

I have a couple Gherkin rules that I try to encourage that should help out with this scenario.

Rule 1 - use declarative syntax when writing scenarios

One of the goals of Behavior Driven Design (BDD) and Gherkin in general is to provide a mechanism to facilitate communication between the business stakeholders and the development team. The goal of these scenarios is to describe business rules in the domain language understood by the business.

The scenario above uses an imperative style of communication. In this example we are using the scenario as a way to describe HOW to complete a task, instead of WHAT the user does. This can lead to a long list of tasks, without clear direction on the business rule being described. What is the rule being described here? Looks like lots of things! (see rule 2)

Another drawback is that it's very painful to read and verify. Imagine a 2-hour meeting with QA, developers, and stakeholders where you review 30 scenarios like this. They are boring, hard to follow, and easy to ignore.

With declarative language we can describe WHAT the user does, without describing HOW to do it. If you find yourself referring to buttons and text boxes in your scenarios, consider other options. In fact, try to imagine that you are describing business rules without referring to an application at all. For example, we could replace the first 11 lines with a single line:

Given a Prime customer is authenticated

Rule 2 - only one When/Then combination per scenario

Looking at the scenario above it's clear we would are describing an end-to-end scenario instead of describing one behavior. With BDD you want one scenario to describe a single behavior, and that means you want a single When/Then combination. The "When" describes the user interaction and the "Then" describes the expected results. So, the question is, what behavior are we describing with this scenario?

It's hard to say. There are plenty of "Whens" and "Thens", but looking at the scenario description I see "Prime customers shipping is free for Prime items". Let's assume that's the business rule we want to describe. So let's try this:

Scenario: Prime customers shipping is free for Prime items

Given a Prime customer is authenticated
When the authenticated customer enters checkout with a single Prime item
Then the shipping is free

How's that? It's certainly much easier to read, it's very clear what the business rule is, and it provides a concrete example for validating it works as expected.

In addition, focusing on the business rule allows us to see other things we need.

• What if the item is not Prime eligible? We need a scenario for that.
• What if there are multiple Prime items? We need a scenario for that.
• What if the order is a combination of Prime and non-Prime items? We need a scenario for that.
• What if the customer is not a Prime customer? We need a scenario for that.

Wrap-up

Rules and standards for writing Gherkin can actually be a pretty controversial topic. If you are starting a new project, NOW is the time to reach agreement on how you are going to use BDD and Gherkin on your project.

If the project is well underway and has lots of imperative/procedural scenarios in place, backed by an automation framework to automate those steps, it will be more challenging to make a change.

In that situation, baby steps may allow you to agree write new scenarios with a declarative syntax. For test automation you could abstract the multiple procedural steps into a single declarative step and continue to use your automation steps under the hood.

And if you're still not sure, imagine how much more pleasant those scenario review meetings are going to be!