Stop Writing Reactive Gherkin Scenarios. Go Outside-In!

A Simple Guide to Outside-In Scenario Outlines

(The article is excerpted from my book, Writing Great Specifications. Today, you can get WGS 39% off—check out the ending of the post.)

As people who are familiar with Gherkin or Cucumber probably already know, Scenario Outlines are templates for similar scenarios. But what the same people don’t know is that the method that they have been most probably using to create their Outlines is reactive instead of proactive. In this article, I am going to show you a proactive way for writing Scenario Outlines in Gherkin.

Thanks to Scenario Outlines, you don’t have to repeat the same Given-When-Thens in your feature files.

So if we have two scenarios that are very similar

Feature: Shipping

Scenario: Shipping PDFs

Given a PDF book in Simona’s cart  
 When she pays for it  
 Then the book should be sent to a mobile device

Scenario: Shipping audiobooks

Given an audiobook in Simona’s cart  
 When she pays for it  
 Then the book should be sent over email

we can easily merge them into a single Scenario Outline with two examples like that

Feature: Shipping

Scenario: Shipping methods

Given a <format> book in Simona’s cart  
 When she pays for it  
 Then the book should be <shipped>

Examples:  
  | format    | shipped                 |   
  | PDF       | sent to a mobile device |  
  | audiobook | sent over email         | 

Merging redundant scenarios is one way of creating Scenario Outlines, but it’s not the only one. I like to call the other way an outside-in method for writing Scenario Outlines.

An outside-in Scenario Outline is written directly out of examples collected by the team during analysis, rather than by merging similar scenarios.

The outside-in method consists of two steps:

1. collect real-world examples for your specification in the form of a table;
2. write the Scenario Outline based on the table, adjusting the steps and parameters to the data.

The outside-in method requires you to analyze examples first and write scenarios later. The table you create in the first step doesn’t even have to be a Gherkin table. It can be a simple spreadsheet created in Excel. The merging method, on the other hand, assumes evolving scenarios into Scenario Outlines only if you notice redundancy and the specification becomes difficult to manage. In that sense, the outside-in method is much more proactive than the merging method—and since it’s better to be a proactive delivery team than a reactive one, outside-in Scenario Outlines can end up becoming a great asset to your development efforts.

Introducing some business context

For the purposes of this article, imagine that you work for a company based around an e-commerce shopping application like Amazon. This company wants to be the online retailer of books, movies, music and games along with electronics, toys, apparel, sports, tools, groceries, and garden items. Selling books was the original purpose of the company. After that, it decided on expansion, adding products such as e-readers, tablets, and headphones, chosen to fit into the store’s reading landscape. Now we have to deal with shipping all these different kinds of products. There’s still a lot of work ahead, and the business is already diverse — and, thankfully, full of different examples to work with for the purposes of writing scenarios.

1. Collect examples in a table

To derive a Scenario Outline from examples, we first need some examples. And to get examples, we need a new feature to implement. Thankfully, our theoretical company owners can happily oblige. The company’s current priority is to get more items into the store, to expand the marketplace. Negotiating with big publishers and producers proved to be difficult, and the management wants to open the store to individual merchants who could sell both new and used items. The merchants would benefit from our advanced shipping infrastructure — and we’d take a cut from their profits.

After some analysis, sales and marketing agreed upon a pricing model that works under the following rules:

• merchants can create their accounts and list new items for free;
• we take a cut after the item is successfully sold;
• our cut depends on the purchaser’s shipping location, because merchants must pay for access to the global customer database made available thanks to our shipping infrastructure.

Let’s now settle on the price ranges and remake our list into the draft of the examples table (Table 1). The commission was designed based on shipping distances from our US operations base and our infrastructure in each region.

Table 1

This table could be the result of a conversation between the non-technical stakeholders from sales and marketing and the delivery team of programmers, testers, and designers. One doesn’t need any technical skill to create or understand it, because there’s no Gherkin involved yet. If you fear that Scenario Outlines are too technical, you can keep your examples at the non-technical level during your specification workshops. There’s nothing wrong with that.

2. Derive Given-When-Thens out of the collected examples

Now that we have our Examples table, we can write the Given-When-Thens. To do that, we need to find a scenario template that works well with the structure of our table. For example, can you see that the Region row is like a question and the Commission row is like an answer to each question?

• North America? We take 10% of the purchase.
• South America? The cut is 11.4%.
• Europe and Asia? The commission is 12.9%.
• Africa? Be ready to give away 13.5%.

From a technical point of view, the questions define the state of the system before we decide how much of a commission to take — and the answers define an outcome based on the chosen state. System states are described by Givens and the outcomes should be written as Thens. We already have two-thirds of our scenario ready to write down!

Given a purchase from <region>Then we should take <commission> of the price

That certainly looks promising, but because this is a scenario about sellers, and not buyers, we could add another Given, which specifies that a merchant is our main actor. We can call the smaller shop Quick-Ship, for example.

Given a merchant called Quick-ShipAnd a purchase from <region>Then we should take <commission> of the price

With these three steps, we only need one more, which will specify the main action of the scenario.

Given a merchant called Quick-ShipAnd a purchase from <region>When Quick-Ship gets paid for the purchaseThen we should take <commission> of the price

3. Add the table to your scenario

The last thing we need to do is combine the Examples table we prepared earlier with the Given-When-Thens, and add remaining keywords like Feature or Scenario Outline.

Feature: Selling items through individual merchants

Scenario Outline: Merchant commissions

Given a merchant called Quick-Ship  
  And a purchase from <region>  
 When Quick-Ship gets paid for the purchase  
 Then we should take <commission> of the price

Examples:  
  | region        | commission |  
  | North America | 10%        |  
  | South America | 11.4%      |  
  | Europe        | 12.9%      |  
  | Asia          | 12.9%      |  
  | Africa        | 13.5%      |

As you see, with a little creativity, we easily arrived at a complete Scenario Outline. Choosing examples to derive our Outlines is a separate art, though, and one that requires a lot more space to cover appropriately — so we won’t be covering it in this article. But for now, we know how to write outside-in Scenario Outlines!

4. Profit!

Generally, I prefer the outside-in method. Scenario Outlines made from merging often look too programmatic, which makes business people reluctant to read the Outlines. I think it has something to do with the “Don’t Repeat Yourself” principle, which is the founding principle of the merging technique. The cost of elegant structure and removed redundancy is often sacrificing Gherkin’s natural language and putting too many things into brackets and parameters. In contrast, the outside-in method puts emphasis on a gradual evolution from a non-Gherkin table, which any non-technical person can read, to a Gherkin scenario, which they don’t need if they read the examples. This evolution often makes the resulting Outline look more natural.

For more on scenarios, Scenario Outlines, Gherkin, and what they can do to help your business run like a top, download the free first chapter of Writing Great Specifications.

Get WGS for a third of the price!

You can also read my presentation on Slideshare to find a 39% discount code!