The basics of Scenario Outlines - Writing Great Specifications v11 MEAP

What Scenario Outlinesare

The relationship between Scenario Outlinesand normal scenarios How Scenario Outlinescan help remove redundancies in Gherkin scenarios according to the Don’t Repeat Yourself principle

The advantages of usingScenario Outlines

Maintaining Scenario Outlinesover time

The disadvantages of technical syntax that Scenario Outlinesuse

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

write this chapter, I can happily laugh at my former self because I now already know one.

It’s called a Scenario Outline.

NOTE

NOTE Scenario OutlineScenario Outline

A Scenario Outlineis a template that similar scenarios can share so you don’t have to repeat the same Given-When-Thens throughout your feature file.

Scenario Outlines look similar to normal scenarios, but there are some differences which we’ll talk about throughout the chapter.

The process of getting from raw scenarios to reusable Scenario Outlinesis usually an iterative one, as we’ll see later on. When we talked about key process patterns of Specification by Example in chapter 1, we called the process "refining examples."

Refining examples means taking raw examples and merging similar examples

removing irrelevant examples focusing on key examples

making sure key examples are easy to understand Outlines can efficiently help you do all that.

Using Scenario Outlinesis a difficult skill to get right. This is why, to make sure we get it right, we will explore the topic in two connected chapters. The chapter you’re reading right now will cover the basics. We will go through a tutorial for learning the syntax of Scenario Outlines. You will learn how to apply the syntax to a real world project, based on a realistic example. We will also see that ^Outlinescan change—grow or shrink—over time, and why that happens. After we understand how ^Outlines work, we’ll also talk about the advantages and disadvantages they bring to the table. And in the next chapter, we will talk about the advanced techniques for usingScenario Outlines

—techniques that elevate the upsides to their full potential, simultaneously reducing the downsides.

To create a connection between the chapters, both this chapter and chapter 5 use the same example. The example is an e-commerce shopping application similar to Amazon: the Like Amazon, our company hopes to become go-to retailer of

everything store. the

books, movies, music and games along with electronics, toys, apparel, sports, tools, groceries, or garden items.

The plans for the future are ambitious. Right now, though, our store sells only books in digital formats such as PDFs and audiobooks. We’re still an early-stage startup and

4.1 Example

building a digital shop was the easiest way to release the minimal viable product and start growing revenue.

But the management feels that it’s high time the company moves from digital only to selling physical items, too. They chose to start with physical book formats, such as hardcovers, paperbacks, and audio CDs, for two reasons. First, the company is already a book-selling startup, so there will be no rebranding expenses. Second, and more importantly, shipping physical book formats will require building a working shipping infrastructure. We will be able to use such an infrastructure in the future to add new products such as toys or tools in the future.

In this section, we’re going to review an existing feature file for one of the core functionalities of the store: shipping orders. Because shipping digital products isn’t the same as selling physical ones, we’ll need to add some new scenarios to specify new shipping capabilities of the system.

Along the way, we’ll notice that the scenarios become too similar to each other, which makes for a boring reading, and that the feature file grew in size, which doesn’t seem efficient at all. We’ll then be able to rewrite the feature file by merging multiple scenarios into a singleScenario Outline.

So the management gave us a green light to implement shipping physical orders. Even though this is a huge change, we won’t start from the scratch. Fortunately, our system already has basic functionalities, like the orders status page, that we can use to expand upon. Another good part is that we will be able to connect with external shipping APIs and let other companies handle behind-the-scenes shipments management. The only thing we have to do right now is to specify how our customers will be able to order shipping for the new formats we’re going to offer and implement the scenarios.

Before we do that, though, let’s have a look at the two existing scenarios. The scenarios were written a few months ago to handle the most basic use cases.

Listing 4.1 The initial example with two simple scenarios Listing 4.1 The initial example with two simple scenarios

4.2 Using

Scenario OutlinesScenario Outlines

4.2.1 Spotting redundancies in Gherkin scenarios

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

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

With digital books, the case was simple. They were sent either by email or directly to a mobile device such as a Kindle reader. Going physical will force us to let customers provide their shipping addresses and make sure the books they buy are shipped there by integrating with external APIs of a shipping company of our choice—a task that will be probably handled within the automation layer, though.

Oh, one more thing—have you noticed that our two scenarios look almost the same?

In fact, the scenarios from listing 4.1 share the same basic structure because of an example-counterexample relationship. Because there are only to ways to ship a digital order order, either by a device integration or by an email download link, each of the scenarios is a counterexample to the other. So whoever wrote this feature file clearly wanted to let you know that the system ships PDFs differently than audiobooks.

To illustrate contrast, examples and counterexamples usually share the same basic structure, differing in details. So do our two scenarios.

Have a look. The Whens in both scenarios are the same. They make Simona pay for her order.

Listing 4.2 The first redundancy in both scenarios Listing 4.2 The first redundancy in both scenarios

The repeating ^When creates the underlying structure of all our scenarios. The differences lie in the ^Givensand ^Thens, but even they are very similar in each scenario.

In Gherkin, repetitions aren’t uncommon. While the syntax looks like a natural language, the scenarios often aren’t too pretty. They’re written and read by technical teams or busy non-technical stakeholders who often value brevity over beauty of language. Some redundancies are to be expected—especially in shorter specifications.

And even though this isn’t a problem right now, in a two-scenario feature file, we’ll see that there are cases when repetitions become too awkward to dismiss in writing and too difficult to maintain in the specification suite long-term.

Let’s see what happens when we add the new physical formats and discuss new shipping features.

Here are the three types of books we decided to add hardcovers

paperbacks audio CDs

Unlike the digital formats, these three are sent to a shipping address of a user’s choice by an external shipping company.

When she pays for it

The new scenarios should be easy enough to write. After all, we’re going to use the same template that we established when we analyzed the initial examples.

Listing 4.3 Scenarios for new shipping options added Listing 4.3 Scenarios for new shipping options added

Three new scenarios

Now it’s even worse, isn’t it? We ended up with five scenarios which are almost exactly the same. It’s an inelegant and inefficient solution. It also isn’t perfect from the readability’s point of view. I can imagine people reading only the first scenario and then skimming through the remaining examples—which is warranted in this case, but a bad Ta

Tablble 4e 4.1.1 AlmmAll bl booook fk forormamatsts

Foorrmmaatt SShhiippppeedd

PDF to a mobile device

Audiobook with an email download link Hardcover to shipping address Paperback to shipping address Audio CD to shipping address

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

Scenario: Shipping hardcovers

Given a hardcover book in Simona’s cart When she pays for it

Then the book should be shipped physically

Scenario: Shipping paperbacks

Given a paperback book in Simona’s cart When she pays for it

Then the book should be shipped physically

Scenario: Shipping Audio CDs

Given an Audio CD book in Simona’s cart When she pays for it

Then the book should be shipped physically

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

habit in general. What if some of the scenarios hides an important detail despite looking similar to the others? A skimming reader could miss that easily. But how could we make sure that will not happen?

Ideally, we would have two types of scenarios.

The first one would somehow visually group similar examples together and use the same underlying template for all examples. The visual grouping would notify the reader that it’s safe to skim through the examples.

The second type of scenarios would be reserved for scenarios which are important enough to stand on their own, letting readers know that they should focus reading it.

Scenario Outlines are, in fact, the scenarios from the first bullet point. To understand how Scenario Outlines work, we will have to forget about our rule for using concrete examples. We will do it only for a little while and only to see if adding a bit of abstraction will help us remove redundancy from our scenarios. We shall also look for a way to visually distinct similar steps and build a shared template for such scenarios.

Having added the new book formats, we ended up with five different ^Givens splattered throughout our feature file.

Given a PDF book in Simona’s cart Given an audiobook in Simona’s cart Given a hardcover book in Simona’s cart Given a paperback book in Simona’s cart Given an Audio CD book in Simona’s cart

Because they all share the same sentence structure, they can be easily abstracted away into a simple template similar to this

Listing 4.4 A general template for all our Listing 4.4 A general template for all ourGivensGivens

Now, we already said that each of the five scenarios in the specification uses the exact same Whento perform the main action of the scenarios—so let’s just add that step to our template without modifying it.

Listing

Listing 4.5 4.5 An An extended extended template template which which includes includes a a When Whenstep, step, tootoo

4.2.2 Refactoring redundant scenarios withScenario OutlinesScenario Outlines

Given a <format> book in Simona’s cart

Given a <format> book in Simona’s cart When she pays for it

to what we’ve already done with the Givens. Just as there were several kinds of the latter, there are also several different kinds of the former

Then the book should be sent to a mobile device Then the book should be sent over email

Then the book should be shipped physically

The list is shorter this time, but remember that the three scenarios for hardcovers, paperbacks, and audio CDs use the exact same ^Then because these formats are shipped using the same method. Despite that, our three Thenscould still be abstracted away into a similar template which looks like this

Listing 4.6 A general template for all our Listing 4.6 A general template for all ourThensThens

and which would result in a scenario template similar to this Listing 4.7 A full scenario template

Listing 4.7 A full scenario template

Do you remember the table we used to write down new examples in our specification? It went something like that

Have a look at the <format> and <shipped>attributes from our scenario template and at the header row of the table above. In fact, we could just use the table to put each of the formats in the scenario template, along with an accompanying shipping method. And if we could make the <shipped>attribute dependent on the <format> attribute inside our automation layer, we could change the outcome of the scenario based on our template every time we executed the specification suite—without changing the rest of the steps!

The good news: we can do that. The template you read above is completely valid Gherkin. Gherkin lets you group similar scenarios that share the same structure in special

Then the book should be <shipped>

Given a <format> book in Simona’s cart When she pays for it

Then the book should be <shipped>

Tablble 4e 4.2.2 AlmmAll bl booook fk forormamatsts

Foorrmmaatt SShhiippppeedd

PDF to mobile a device

Audiobook sent over email

Hardcover to shipping address

Paperback so shipping address

Audio CD to shipping address

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

scenarios called Scenario Outlines. They are automatable templates for removing redundancy in similar scenarios. Outlinesuse visual signs such as attributes and tables to group related examples so you don’t have to worry about missing anything important.

Here’s what a full Scenario Outlinelooks like:

Listing 4.8 Introducing

Listing 4.8 IntroducingScenario OutlinesScenario Outlines

Scenario Outline is the keyword that lets the test runner recognize outlines There are two variables: format and shipped

Examples to replace the angle brackets with

The result is similar to a diagram we analyzed in chapter 1 when we talked about the process of collecting and refining examples.

4.3 The structure of a

Scenario OutlineScenario Outline

Feature: Shipping

Scenario Outline: Shipping

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 |

| Hardcover | shipped physically |

| Paperback | shipped physically |

| Audio CD | shipped physically |

Figure 4.1 Every acceptance criterion generates new examples; every example generates Figure 4.1 Every acceptance criterion generates new examples; every example generates new scenario. Teams should refine their specifications to merge

new scenario. Teams should refine their specifications to merge similar examples, rejectsimilar examples, reject the ones that introduce noise, and to

the ones that introduce noise, and to choose the most meaningful or descriptive ones.choose the most meaningful or descriptive ones.

Thanks to Scenario Outlines, we can take raw examples from raw scenarios and put them into refined scenario groups. Grouping raw examples is possible because every

is built from three elements: the table, parameters, and the

Outline Examples Scenario

keyword. We shall now analyze this structure section by section, starting from

Outline

the end—the Examplestable.

The Examples table simply contains all the examples. The syntax is straightforward.

Tables can be created very easily. Use the vertical stroke as the first character of the line, and separate each table cell with it. The first row is the header row with all theScenario

parameters. After the header, each example has its own row.

Outline

4.3.1 The ExamplesExamplestable

Scenario Outline parameters are the parameters within the angle brackets, like or . They allow the test runner to paste the examples from the table

into the Outlinewe wrote.

If we have the following steps

Listing 4.9 Scenario variables within a Given-When-Then template Listing 4.9 Scenario variables within a Given-When-Then template

and the following table, which is a simplified version of our full table Listing 4.10 Examples

Listing 4.10 Examples

then the ^Outlinewould produce and run two scenarios:

one where <format>gets replaced with PDFand <shipped>withsent to a mobile device

one where <format>gets replaced with Paperbackand <shipped>withsent over email

So the scenario made from the example will run as

Listing 4.11 A scenario generated from the PDF example Listing 4.11 A scenario generated from the PDF example

and the scenario made from the second example will run as Listing 4.12 A scenario generated from the audiobook example Listing 4.12 A scenario generated from the audiobook example

and each of the steps from the generated scenarios would have an accompanying step definition in the automation layer that lets each example run as an automated test.

4.3.2 Parameters

Given a <format> book in Simona's cart When she pays for it

Then the book should be <shipped>

Examples:

| format | shipped |

Given a PDF book in Simona’s cart When she pays for it

Then the book should be sent to a mobile device

Given an audiobook in Simona’s cart When she pays for it

Then the book should be sent over email

Outlines rely on patterns to match attributes with the examples from the table.

When a test runner sees a Gherkin scenario with multiple examples, it runs the scenario template as many times as there are examples, replacing abstract attributes with concrete values dictated. Each time it replaces a pattern called <pattern_name> with a corresponding example. Every pattern' name has to be written without using any space and within angle brackets.

With Scenario Outlines, you’re able to test for multiple cases that share similarities but yield different outcomes. The simplest examples are two contrasting cases for the same acceptance criterion: the first being a success scenario, and the second being a failure scenario. The success scenario defines what conditions are needed foe the user to succeed given his intentions. Failure scenarios, on the other hand, define every other behavior that will fall short.

As you can see, merging similar scenarios means writing separate scenarios first and looking for similarities later. It’s a simple technique used by beginners. People usually

In document Writing Great Specifications v11 MEAP (Page 94-114)