---
title: Scenario Outlines, Tags and Background | TestingBot
description: 'Three Gherkin features help a feature file grow without becoming repetitive:
  **Scenario Outlines** run one scenario with several rows of data, **Background**…'
source_url:
  html: https://testingbot.com/resources/courses/cucumber-bdd/outlines-tags-background
  md: https://testingbot.com/resources/courses/cucumber-bdd/outlines-tags-background.md
---

Course

[BDD with Cucumber: Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)

Chapter 7 of 12

1. [1 Cucumber BDD Tutorial: From Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)
2. [2 BDD Testing Starts Before the Code: Three Amigos](https://testingbot.com/resources/courses/cucumber-bdd/bdd-collaboration)
3. [3 Writing Good Gherkin: Declarative Scenarios](https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin)
4. [4 Cucumber with Java and Selenium: First Scenario](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium)
5. [5 Step Definitions, Cucumber Expressions, Parameter Types](https://testingbot.com/resources/courses/cucumber-bdd/step-definitions)
6. [6 Hooks and Sharing State with PicoContainer](https://testingbot.com/resources/courses/cucumber-bdd/hooks-and-shared-state)
7. [7 Scenario Outlines, Tags and Background](https://testingbot.com/resources/courses/cucumber-bdd/outlines-tags-background)
8. [8 Cucumber-JS with Playwright](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-js-playwright)
9. [9 Parallel Runs, Reports and CI on TestingBot](https://testingbot.com/resources/courses/cucumber-bdd/parallel-reports-ci)
10. [10 Other BDD Frameworks: Behave and Reqnroll](https://testingbot.com/resources/courses/cucumber-bdd/behave-and-reqnroll)
11. [11 BDD Anti-Patterns and How to Fix Them](https://testingbot.com/resources/courses/cucumber-bdd/bdd-anti-patterns)
12. [12 Knowledge check](https://testingbot.com/resources/courses/cucumber-bdd/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 7 of 12 Intermediate 6 min read 2 quick checks Updated Nov 2026 

# Scenario Outlines, Tags and Background
On this page
1. [The finished feature file](https://testingbot.com#the-finished-feature-file)
2. [Scenario Outline](https://testingbot.com#scenario-outline)
3. [Background](https://testingbot.com#background)
4. [Tags](https://testingbot.com#tags)
5. [Run it](https://testingbot.com#run-it)

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[#](https://testingbot.com#the-finished-feature-file)

This is `sign_in.feature` as the rest of the course runs it:

```gherkin
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[#](https://testingbot.com#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[#](https://testingbot.com#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?

 Keep it, and run the rows in parallel to save time Keep two or three rows that show the rule, and test the full list in a unit test of the validator Split it into 40 separate scenarios

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[#](https://testingbot.com#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.** `Given` steps 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 `Rule` with 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[#](https://testingbot.com#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.

```gherkin
@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:

```bash
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[#](https://testingbot.com#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?

 `not @wip or not @slow` `@wip and @slow` `not @wip and not @slow` `!@wip !@slow`

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[#](https://testingbot.com#run-it)

```bash
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](https://testingbot.com/resources/courses/cucumber-bdd/certification) builds on.

[Previous · Chapter 6 Hooks and Sharing State with PicoContainer](https://testingbot.com/resources/courses/cucumber-bdd/hooks-and-shared-state) [Next · Chapter 8 Cucumber-JS with Playwright](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-js-playwright)

On this page

1. [The finished feature file](https://testingbot.com#the-finished-feature-file)
2. [Scenario Outline](https://testingbot.com#scenario-outline)
3. [Background](https://testingbot.com#background)
4. [Tags](https://testingbot.com#tags)
5. [Run it](https://testingbot.com#run-it)

Certification

Earn the free, resume-worthy TestingBot Cucumber BDD Certification for this course.

[How it works](https://testingbot.com/resources/courses/cucumber-bdd/certification)
