Scenario Outlines, Tags and Background
On this page
Three Gherkin features help a feature file grow without becoming repetitive: Scenario Outlines run one scenario with several rows of data, Background holds the context every scenario shares, and tags let you choose which scenarios run. Each is easy to overuse, so this chapter covers when to reach for them as well as how.
The finished feature file#
This is sign_in.feature as the rest of the course runs it:
Feature: Signing in to the secure area
Members sign in with a username and password to reach the secure area.
Wrong credentials are rejected with a message that says which part was wrong.
Background:
Given Tom has an account
@smoke
Scenario: Tom signs in with his own password
When Tom signs in with his password
Then he is in the secure area
Scenario Outline: Wrong credentials are rejected
When someone signs in as "<username>" with password "<password>"
Then the sign-in is rejected because the <field> is invalid
Examples:
| username | password | field |
| tomsmith | not-his-password | password |
| tomjones | SuperSecretPassword! | username |
It produces three scenarios: one plain scenario and two from the outline.
Scenario Outline#
A Scenario Outline (synonym: Scenario Template) is a scenario with <placeholders>. Each row of the Examples table below it becomes a separate scenario, with the placeholders replaced by that row's values. The rows above run as:
When someone signs in as "tomsmith" with password "not-his-password"
Then the sign-in is rejected because the password is invalid
When someone signs in as "tomjones" with password "SuperSecretPassword!"
Then the sign-in is rejected because the username is invalid
Placeholders are replaced before step matching, so the step definitions from chapter 4 do not know or care that they came from an outline. Each row passes or fails on its own, and a failing row does not stop the others.
Placeholders also work in the outline's title. Scenario Outline: A wrong <field> is rejected runs as "A wrong password is rejected" and "A wrong username is rejected", which makes reports and the TestingBot dashboard much easier to scan than two scenarios with the same name.
When to use an outline#
Use one when several examples illustrate the same rule and differ only in data: the two rejection messages above, price bands, validation rules. The table then is the specification: a product owner can read it and add a row.
Do not use one to loop over test data that nobody needs to read. Twenty rows of slightly different email addresses belong in a unit test of the validator, where they run in milliseconds instead of twenty browser sessions. And if rows need different steps, they are different behaviours: write separate scenarios.
An outline has 40 example rows checking email formats through the sign-up form in a browser. What is the better design?
Each row is a full browser scenario. The rule needs a few illustrative examples for readers; exhaustive input checks belong at the cheapest level that can run them.
Background#
A Background holds Given steps that run before every scenario in the feature (or in the Rule, if it is placed inside one). It runs after the @Before hooks, so the browser already exists.
Here, every scenario starts from "Tom has an account", so it moves out of the scenarios. Guidelines that keep a Background helpful:
-
Only context.
Givensteps only; no actions, no assertions. - Short. Two or three steps. A reader has to keep the Background in mind while reading each scenario below it; a long one hides important context off-screen.
-
True for every scenario. If one scenario does not need it, the Background is lying about that scenario. Move the step back into the scenarios that need it, or split the feature (or use a
Rulewith its own Background). - Not a setup script. "Given the database is seeded with fixtures 1 to 12" is setup, not behaviour. Do that in a hook.
Tags#
A tag is a word starting with @ above a Feature, Rule, Scenario, Scenario Outline or Examples block. Tags are inherited: a tag on the feature applies to every scenario in it, and a tag on an Examples block applies only to its rows.
@negative
Examples:
| username | password | field |
| tomsmith | not-his-password | password |
| tomjones | SuperSecretPassword! | username |
Choose which scenarios run with a tag expression, passed as a system property:
mvn test -Dcucumber.filter.tags="@smoke"
mvn test -Dcucumber.filter.tags="@negative"
mvn test -Dcucumber.filter.tags="not @wip"
mvn test -Dcucumber.filter.tags="@smoke or (@negative and not @slow)"
Expressions support and, or, not and parentheses. With the JUnit Platform engine, Surefire counts the scenarios that the filter excluded as skipped: @smoke on the sign-in feature alone reports Tests run: 3, Skipped: 2.
Tags are also how hooks target scenarios: @Before("@admin") runs only for scenarios tagged @admin, for example to sign in as an administrator through an API first.
A small, deliberate tag vocabulary#
Tags work when a team agrees on a handful of them and what they mean:
| Tag | Meaning |
|---|---|
@smoke |
The few scenarios that must pass before anything else is worth running |
@wip |
Work in progress, excluded from CI with not @wip
|
@slow |
Excluded from the pull-request run, included nightly |
@JIRA-123 style |
Links a scenario to a ticket, for traceability |
Avoid tags that duplicate what the folder structure already says, and tags that encode browsers (@chrome): which browser runs a scenario is a property of the run, not of the behaviour. Chapter 8 runs the same scenarios on several browsers by changing a system property instead.
Which tag expression runs everything except work in progress and slow scenarios?
A scenario must be neither @wip nor @slow, so both conditions must hold: and. With or, a scenario tagged only @slow still runs because it is "not @wip".
Run it#
mvn test
All three sign-in scenarios run, plus the sign-out scenario from chapter 5, each with its own browser. On TestingBot each one is a separate session named after the scenario, which is the setup the practical task of the certification builds on.