Scenario Outline and Examples
In short: Five scenarios that differ only in the amount become one Scenario Outline with an Examples table: every row is a separate example. A Background holds the start shared by all the scenarios. A Rule groups the examples under the business rule they show, like the green cards under the blue one.
Problem
The same thing five times
Someone described delivery with five scenarios. They differ only in the amount: 30, 49.99, 50, 50.01 and 120 €. Otherwise they are identical, line by line.
You read the file and have to compare five blocks to see what is different. And when the fee becomes 5.90 €, you fix three places and forget the fourth.
The idea
An outline and examples
Scenarios that differ only in their values become one Scenario Outline. In place of the values there are names in <>, and the values are in an Examples table:
Feature: Free delivery
Scenario Outline: Delivery for an order of <total> € Given a cart of <total> € When I place the order Then delivery is <delivery> €
Examples: | total | delivery | | 30.00 | 4.90 | | 49.99 | 4.90 | | 50.00 | 0.00 | | 120.00 | 0.00 |Every row of the table is a separate scenario. This outline runs four times. If it fails, the report says which row of Examples.
Now the differences are visible at once: one column of amounts and one column of delivery. The table is very close to what the owner writes in an email: "up to 49.99 € you pay 4.90 €, from 50 € nothing".
Try it
Which row?
Exercise
An outline for delivery
1. From copies to an outline. The start is three copied scenarios.
Turn the scenarios for 30 € and 50 € into one Scenario Outline with Examples. Add the rows that catch the last bugs too: the check tells you where to look.
Solution
Feature: Free delivery
Scenario Outline: Delivery for an order of <total> €
Given a cart of <total> €
When I place the order
Then delivery is <delivery> €
Examples:
| total | delivery |
| 30.00 | 4.90 |
| 49.99 | 4.90 |
| 50.00 | 0.00 |
| 120.00 | 0.00 |
Scenario: An empty cart
Given an empty cart
When I place the order
Then the order is refused
The two new rows are 49.99 € (an amount with cents just under the boundary catches the rounding to whole euros) and an amount from 100 € up (it catches the old tariff for big orders). The empty cart stays a separate scenario: it has no delivery, it is refused.
The idea
A data table
Sometimes one step needs several rows of input. For example a cart with several products:
Feature: The cart total
Scenario: A cart with two products Given a cart with the products: | product | price | count | | T-shirt | 20.00 | 2 | | mug | 9.99 | 1 | When I place the order Then the total is 49.99 €This is a data table. It is the input of one step, and the scenario runs once. Examples do the opposite: they repeat the whole scenario for every row.
The vocabulary in the tasks here has only simple steps, so the data table is for reading only.
The idea
Background
If all the scenarios in a file start the same way, for example "the customer is logged in", that start can move into a Background. Its steps run before every scenario under it, as if they were written in it.
Feature: At most 10 of a product
Background: Given the cart has 9 of the product
Scenario: The tenth item is accepted When I add 1 more Then the cart has 10 of the product
Scenario: Two more are refused When I add 2 more Then adding is refusedBe careful with it. Whoever reads the second scenario cannot see where it starts without going back up. So a background is short and holds only what is really shared.
The idea
Rule
In Example Mapping the blue cards are the rules and the green ones are the examples under them. In Gherkin the same thing is said with the keyword Rule: under it are the scenarios that show it.
Feature: At most 10 of a product
Rule: The cart holds at most 10 of a product
Scenario: The tenth item is accepted Given the cart has 9 of the product When I add 1 more Then the cart has 10 of the product
Rule: You add at least 1 item
Scenario: Zero items is not adding Given the cart has 5 of the product When I add 0 more Then adding is refusedNow the file says not only what we check, but also why. If a scenario fails, you see at once which rule is broken. Each rule can have its own background.
Exercise
The limit with rules
2. Two rules. The rules are written, with nothing under them.
Put examples under each rule (with an outline or with scenarios) so that all six bugs in the limit are caught.
Solution
Feature: At most 10 of a product
Rule: The cart holds at most 10 of a product
Scenario Outline: <has> in the cart, adding <add>
Given the cart has <has> of the product
When I add <add> more
Then the cart has <after> of the product
Examples:
| has | add | after |
| 9 | 1 | 10 |
| 10 | 1 | 10 |
| 5 | 6 | 5 |
Rule: You add at least 1 item
Background:
Given the cart has 5 of the product
Scenario Outline: Adding <add>
When I add <add> more
Then adding is refused
And the cart has 5 of the product
Examples:
| add |
| 0 |
| -1 |
The upper boundary is seen from both sides: 9 + 1 is accepted, 10 + 1 is refused. The case 5 + 6 catches the system that counts only the items being added. After every refusal you also check how many items are left: otherwise nobody sees that the cart was emptied. The lower boundary also has two sides: 0 items and a negative quantity are different bugs.
More precisely, if you are curious
The Gherkin Reference (Cucumber):
- "Rule" has been in Gherkin since version 6. Its purpose is to represent one business rule that should be implemented;
- "Scenario Outline" has a synonym, "Scenario Template". There can be several Examples under one outline, each with its own name, for example "Around the boundary" and "Far from the boundary";
- there is one background per feature or per rule. The reference advises keeping it short: if it is more than 4 lines long, some of the details probably belong in higher-level steps;
- besides a data table, a step can also carry a longer text in
"""(a doc string), for example the text of an email.
Choosing the rows in Examples is test design: equivalence classes and boundary values. They have their own module later. For now the rule is: one row from each class and one from each side of every boundary.
Test