Guide
Scenario Outline and Examples tables: what runs, and what quietly does not
By Miftode Vasilica, maker of Gherkin Studio ·
A Scenario Outline is one scenario that is written once and run once for every row of its Examples table. Use it when the steps are word for word the same and only the values change. This page shows how the rows are read, the two errors you can get, and four mistakes that give no error at all. Every example here was run through the official Cucumber parser.
Four copies of the same scenario
The story says an account locks after five wrong passwords. The tester writes a scenario for four tries, copies it, and changes the number. Then again for five and six. Then once more for the case where the right password comes after the lock.
A sprint later the rule changes to three tries. Three of the four copies get updated. The fourth still says five, still passes, and now tests a rule that no longer exists.
The four copies were one scenario with a table:
@PROJ-31
Feature: Account lockout
Scenario Outline: Sign in after <tries> wrong passwords
Given I typed a wrong password <tries> times
When I type the right password
Then I am <result>
Examples:
| tries | result |
| 4 | signed in |
| 5 | locked out |
When the rule changes, one cell changes.
How the rows are read
The first row of the table names the columns. Every row after it becomes its own scenario. In each one, <tries> and <result> are replaced by the values of that row.
The replacement happens in four places:
- the steps;
- the scenario's name, so the two rows above become "Sign in after 4 wrong passwords" and "Sign in after 5 wrong passwords";
- the cells of a data table under a step;
- the text of a doc string under a step.
Put a placeholder in the name. In a test report every row is listed under its name, and ten rows called "Sign in" tell you nothing about which one failed.
Four mistakes that give no error
These all parse. Nothing is underlined, and the result is not what you meant.
1. A placeholder that matches no column. Names are matched exactly. With a column called tries, the placeholders <Tries> and < tries > are not replaced. The step runs with the text <Tries> in it, brackets included.
2. A table with only the header row. No rows, no scenarios. The outline is valid and nothing runs. The same goes for an Examples: line with nothing under it.
3. An outline with no Examples: at all. It is treated as an ordinary scenario and runs once, with <tries> as literal text.
4. The same column name twice. The parser accepts it. Only one of the two columns is used.
The first one is the easiest to make. If a step fails with angle brackets in its text, look at the spelling of the column name before anything else.
The two errors you can get
A row with a missing cell.
inconsistent cell count within the table
The line number points at the short row. Every row needs as many cells as the header. An empty cell is fine, as long as its pipes are there: | 5 | |.
A step after the table.
expected: #EOF, #TableRow, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got 'Then I see a message'
Steps come first, the table last. After an Examples table the parser accepts another row, another Examples:, or the next scenario. Gherkin Studio shows this one as: Unexpected text "Then I see a message". Expected end of file, a table row (| … |), a tag, Examples:, Scenario: or Rule:.
More than one Examples table
An outline can have several tables. Each can have a name and its own tags:
Scenario Outline: Sign in after <tries> wrong passwords
Given I typed a wrong password <tries> times
When I type the right password
Then I am <result>
@smoke
Examples: Around the limit
| tries | result |
| 4 | signed in |
| 5 | locked out |
@slow
Examples: Far past the limit
| tries | result |
| 50 | locked out |
| 500 | locked out |
A tag on a table applies to the rows of that table only, on top of the tags of the scenario and the feature. So you can run the two rows that matter on every push, and the long table once a night.
Other spellings of the same thing
Scenario Template:is the same asScenario Outline:.Scenarios:is the same asExamples:.- A plain
Scenario:with an Examples table under it is read as an outline too.
When a table is the wrong tool
- The rows need different steps. If one row needs an extra
And, it is a different scenario. Write it separately. - The table has thirty rows. Thirty combinations of numbers are a unit test. Keep the two or three rows a product owner would argue about.
- There is one row. Then it is a scenario. The table only makes it harder to read.
In Gherkin Studio
- Format tables lines up the pipes of every Examples table and right-aligns numbers, without changing what is in the cells.
- A
<placeholder>gets its own colour in the editor. Inside quotes it takes the colour of the quoted text. - Steps of an outline are suggested to the rest of the project with their placeholders, as you wrote them.
- In test results each row counts as a scenario. In a report written by cucumber-js or pytest-bdd every row is its own entry, so the two rows above show on the story as 2/2 passing or 1/2 failing.
Short answers
Does a Background run before every row?
Yes. Each row is a full scenario, and the Background steps run before each of them.
How do I put a pipe character in a cell?
Write \|. A new line inside a cell is \n, and a backslash is \\.
Can an Examples cell be empty?
Yes. The placeholder is replaced with nothing.
Are column names case sensitive?
Yes. <Tries> and <tries> are different names.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. It is on the Atlassian Marketplace, with a 30-day free trial. See data tables and doc strings and what each parser error means.