Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท BDD Concepts and Gherkin

Background, Rules and Organizing Scenarios

Use Background to share setup steps, Rule to group scenarios by business rule, and good file organization to keep feature files short, focused and easy to navigate.

Once a feature has more than a handful of scenarios, repetition appears: the same Given lines at the top of each one, scenarios belonging to different business rules mixed together, files that scroll for pages. Gherkin has two keywords for this, Background and Rule, and a few conventions for organizing folders. Used well they shorten files; used carelessly they hide the setup a reader needs.

Background: shared setup

A Background: block holds steps that run before every scenario in the feature (or in the enclosing Rule). It is written once, above the first scenario.

GHERKIN
Feature: Shopping cart

  Background:
    Given a shop that sells books for 12 dollars each
    And an empty cart

  Scenario: Adding one book
    When the customer adds 1 book
    Then the cart total is 12 dollars

  Scenario: Adding three books
    When the customer adds 3 books
    Then the cart total is 36 dollars

For Cucumber, each scenario behaves as if the Background steps were pasted at its start. They run as part of the scenario, in the same fresh state, and they show up in reports. If a Background step fails, the scenario fails.

Rules for a good Background

  • Keep it short: three or four lines at most. A reader should hold it in their head while reading every scenario below.
  • Only Given steps. Actions and assertions in a Background are a smell; the Background sets the stage.
  • Only what every scenario needs. If one scenario in five does not need a step, move it into the scenarios that do.
  • Do not hide the interesting data. The key facts that make a scenario's outcome understandable belong in the scenario itself. A scenario that says "Then the total is 36 dollars" is unreadable if the price is defined 40 lines above.
  • One Background per feature (or one per Rule).

A common failure is the "everything Background": twenty lines of setup nobody reads, so scenarios lose their meaning. If your Background needs scrolling, the feature probably covers too many things or the steps are too low-level.

A stand-in that applies a Background

The simplest implementation is exactly what the paragraph said: prepend the Background steps to every scenario. The engine below does this and prints the combined steps, marking which came from the Background.

Java Stand-in: Background steps prepended to each scenario

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Rule: grouping by business rule

Gherkin 6 introduced Rule: to express something example mapping already taught: scenarios illustrate rules. A Rule block sits between the Feature and its scenarios and groups the examples of one rule. It can have its own Background.

GHERKIN
Feature: Shipping cost

  Rule: Orders of 50 dollars or more ship for free

    Example: A large order ships free
      Given an order worth 75 dollars
      When the shipping cost is calculated
      Then the shipping cost is 0 dollars

    Example: An order of exactly 50 dollars ships free
      Given an order worth 50 dollars
      When the shipping cost is calculated
      Then the shipping cost is 0 dollars

  Rule: Smaller orders pay a flat 5 dollars

    Background:
      Given the standard shipping tariff

    Example: A small order pays shipping
      Given an order worth 20 dollars
      When the shipping cost is calculated
      Then the shipping cost is 5 dollars

Example: is a synonym for Scenario: and reads nicely under a Rule. A Background inside a Rule runs after the feature-level Background and applies only to that rule's scenarios.

Benefits of Rule:

  • The structure of the map survives. Blue cards become Rule: lines, green cards become Example: lines.
  • Reports and IDEs can show the grouping.
  • Backgrounds get narrower. A setup that only one rule needs goes into that rule.

Note that Rule has no effect on execution order or isolation; it is documentation structure that the engine also records in reports.

Counting rules and examples

The stand-in below parses a feature with Rule: blocks and prints an outline of rules with their examples. The same logic powers the outline view in IDE plugins.

Java Stand-in: outline of rules and examples

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The last rule has no examples, which is the signal that discovery was incomplete.

Organizing files and folders

Cucumber does not care how files are named or nested, but people do. Conventions that scale:

  • One feature per file, named after the capability in snake_case or kebab-case: free-shipping.feature.
  • Group folders by business area, not by technique: features/checkout/, features/accounts/, not features/ui/ and features/api/.
  • Keep files short. A feature file over a few hundred lines usually mixes several capabilities.
  • Mirror the glue. features/checkout/ pairs with steps/checkout/ so a reader can find the code for a sentence.
  • Use tags for cross-cutting concerns (such as @slow or @wip) rather than folders.

When not to use Background

Prefer a single Given step over a Background when the setup is one line, or a descriptive Given in each scenario when the numbers matter to the outcome. Duplication in feature files is not as bad as in code, because each scenario should be understandable without scrolling. This idea reappears in the next lesson on declarative scenarios.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When do Background steps run?

    Each scenario starts with the Background steps, in its own fresh state.
  2. 2. Which content belongs in a Background?

    Backgrounds set the stage with a few shared Given steps; scenario-specific key data stays in the scenario.
  3. 3. What is the purpose of the Rule keyword?

    Rule mirrors the blue card of example mapping and groups its examples.
  4. 4. How does Example relate to Scenario?

    They are interchangeable keywords; Example reads well under a Rule.

Summary

  • Background: prepends a few shared Given steps to every scenario; keep it short and relevant.
  • Rule: groups examples that illustrate one business rule and may have its own Background.
  • Example: is a synonym of Scenario:.
  • Organize features by business capability, keep files short and mirror the folder structure in the glue.
  • Prefer clarity over deduplication: a scenario should be understandable on its own.

Next: Declarative Scenarios: Say What, Not How