Guide
Gherkin Background: when it helps, and when it hides the scenario
By Miftode Vasilica, maker of Gherkin Studio ·
Background: holds the steps that run before every scenario in a feature. It is the right place for one or two Given steps that every scenario shares and no reader needs to think about. It is the wrong place for anything a reader must know to understand the Then. This page covers the rules the parser enforces, and a ten-second test for whether a Background is helping.
"Why 96?"
Refinement, a shared screen. The scenario everyone is looking at:
Scenario: Invoice total
When I open the invoice for March
Then the total is 96.00
The product owner asks why 96. The March order was 120. Somebody scrolls up. Sixty lines above, in the Background, there is a customer with a 20% discount.
Nothing is wrong with the test. But the scenario, the part people actually read, no longer says what it checks. The number that explains it lives somewhere else.
What a Background is
Feature: Invoices
Background:
Given I am signed in as an accountant
Scenario: Invoice total with a discount
Given a customer with a 20% discount ordered for 120.00 in March
When I open the invoice for March
Then the total is 96.00
Scenario: Invoice total without a discount
Given a customer ordered for 120.00 in March
When I open the invoice for March
Then the total is 120.00
The Background step runs before each of the two scenarios, as if it were their first line. In a Scenario Outline it runs before every row. Cucumber runs it after any Before hooks in the code.
Here the discount has moved into the scenario that depends on it. Being signed in stays in the Background: every scenario needs it, and no total depends on it.
The rules the parser enforces
We ran each of these through the official Cucumber parser.
One Background per feature, before the first scenario. A Background after a scenario is an error on the Background: line:
expected: #EOF, #TableRow, #DocStringSeparator, #StepLine, #TagLine, #ExamplesLine, #ScenarioLine, #RuleLine, #Comment, #Empty, got 'Background:'
Gherkin Studio shows it as: Unexpected text "Background:". Expected end of file, a table row (| … |), a doc string ("""), a step (Given/When/Then/And/But), a tag, Examples:, Scenario: or Rule:. In short: at this point anything was allowed except a Background. A second Background gives the same kind of message, on the second one.
No tags on a Background. A tag above Background: is an error, and a noisy one. The parser reports the Background line and then every line after it. Delete the tag and all of them go away.
A Background can have a name and a description. Background: Signed in as an accountant is valid. It costs nothing and tells the reader what the steps are for.
Each Rule can have its own Background. If the feature also has one, the feature's steps run first, then the Rule's:
Feature: Invoices
Background:
Given I am signed in as an accountant
Rule: Discounts apply to the whole order
Background:
Given a customer with a 20% discount
Example: One order in the month
Given the customer ordered for 120.00 in March
When I open the invoice for March
Then the total is 96.00
What the parser does not stop
WhenandThenin a Background. They parse. A Background that performs the action or checks a result is a scenario in disguise.- A Background with no scenarios under it. Valid, and nothing runs.
- An empty Background. Valid, and it does nothing.
The ten-second test
Cover the Background with your hand. Read each scenario on its own.
- If every scenario still makes sense, the Background is doing its job.
- If one of them makes you ask "why this number?" or "who is this user?", the answer is under your hand. Move that step down into the scenario.
Three more signs it has grown too far:
- It is longer than the scenarios. Cucumber's own reference suggests rethinking a Background of more than four lines.
- It has scrolled off the screen. Then nobody is reading it.
- Only some scenarios need it. A step that half the scenarios ignore belongs to the other half. Split the feature, or use a Rule with its own Background.
What to use instead
- One step that names the state.
Given I am signed in as an accountantreplaces four lines about creating a user, a role, a password and a session. The detail goes into the step's code, where a reader does not have to carry it. - A
Beforehook, for things no reader cares about: starting a browser, cleaning a database. If it is not part of the story, it should not be in the text. - A Rule with its own Background, when a group of scenarios shares a setup that the others do not.
In Gherkin Studio
- With Git sync, each story is one file,
KEY-123.feature. A Background there covers the scenarios of that one story, so it rarely has room to scroll out of sight. - Steps written in a Background are suggested to the rest of the project like any other step.
- In test results, a Background is never counted as a scenario. A story with a Background and three scenarios shows three.
Short answers
Can a feature have two Backgrounds?
No. One per feature, and one per Rule.
Does the Background run before every row of a Scenario Outline?
Yes. Each row is a full scenario.
Can I skip the Background for one scenario?
No. If one scenario does not need it, the step is not background. Move it into the scenarios that do.
Background or a Before hook?
Background when the reader should see it. A hook when they should not have to.
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 how to write scenarios in a Jira story and steps your team can reuse.