BDD Feature Files: Scenario Outline, Examples & Background Explained

A feature file is where BDD starts: a plain-language description of how the application should behave, written in Gherkin and saved with a .feature extension. Cucumber reads it, matches each step to Java code, and runs it as an automated test. This guide explains every part of a feature file — Scenario, Scenario Outline, Examples, Background, Data Tables and tags — with a complete working example.

Advertisement

What Is a Feature File?

  • Purpose: describe business behavior in a readable format that doubles as acceptance criteria and as automated tests.
  • Contains: a Feature description, an optional Background, Scenarios or Scenario Outlines, and steps written with Given / When / Then.
  • Who writes it: product owners, business analysts and QA together — often during refinement or sprint planning — and QA automates it by mapping steps to step definitions.
  • Tools: Cucumber with Selenium WebDriver or REST Assured, Java, Maven, JUnit or TestNG, and Jenkins.

Analogy: a feature file is like a recipe written in simple English — anyone can read it, and the step definitions are the cook who actually carries out each step.

A Complete Feature File

@login
Feature: Login
  As a registered customer
  I want to log in to my account
  So that I can see my orders

  Background:
    Given the user is on the login page

  @smoke
  Scenario: Successful login with valid credentials
    When the user logs in with "asha@example.com" and "Secret@123"
    Then the dashboard should be displayed
    And the welcome message should contain "Asha"

  @regression
  Scenario Outline: Login fails with invalid credentials
    When the user logs in with "<email>" and "<password>"
    Then the error message "<message>" should be displayed

    Examples:
      | email             | password    | message                   |
      | asha@example.com  | wrong       | Invalid email or password |
      | unknown@test.com  | Secret@123  | Invalid email or password |
      |                   | Secret@123  | Email is required         |

The Keywords

Keyword Meaning
Feature The functionality under test, plus an optional free-text description (often a user story).
Background Common preconditions that run before every scenario in the file.
Scenario One concrete example of behavior — one test case.
Scenario Outline A template that runs once per row of its Examples table.
Examples The data table for a Scenario Outline.
Given The context or precondition.
When The action or event.
Then The expected outcome.
And / But Continue the previous step type, for readability.
Rule Groups scenarios under one business rule (Gherkin 6+).
@tag Labels for filtering and hooks, e.g. @smoke.
# A comment line.

Keep the full syntax handy in the Cucumber & Gherkin Cheat Sheet.

Feature, Scenario and Scenario Outline

  • Feature — what functionality is tested, at a high level, usually mapping to a business requirement (Login, Payment).
  • Scenario — one specific test case under that feature, written with Given–When–Then.
  • Scenario Outline — the same test logic run with multiple data sets via an Examples table, which removes duplicate scenarios.

Analogy: Feature = a movie · Scenario = one scene · Scenario Outline = the same scene shot with different actors.

Scenario vs Scenario Outline

  Scenario Scenario Outline
Data sets One Many — one run per Examples row
Placeholders None <name> placeholders in steps
Typical use A single happy path Validation rules, boundaries, many invalid inputs
Reporting One result One result per row

A common pattern: a Scenario for valid login, and a Scenario Outline with Examples for all the invalid-login variations.

The Examples Keyword

Examples supplies the data for a Scenario Outline. Cucumber replaces each <placeholder> with the value from the matching column, and each row runs the scenario once — that's data-driven testing in BDD.

You can have more than one Examples table, and tag each separately — useful for running a small smoke set and a larger regression set from the same outline:

  Scenario Outline: Coupon validation
    When the user applies coupon "<code>"
    Then the discount should be "<discount>"

    @smoke
    Examples: Valid coupons
      | code   | discount |
      | SAVE10 | 10%      |

    @regression
    Examples: Expired and invalid coupons
      | code    | discount |
      | OLD2023 | 0%       |
      | FAKE    | 0%       |

Background: What, When, and the One-Per-Feature Rule

Background defines preconditions that run before each scenario in the file — including each row of a Scenario Outline. It removes repeated Given steps.

  • When to use it: when every scenario in the file shares the same starting point.
  • Best practice: keep it short and limited to preconditions — no actions under test and no assertions. If a reader has to scroll up to understand a scenario, the Background is doing too much.
  • Only one per feature file (or one per Rule). For setup that applies to some scenarios only, split the feature file or use a tagged hook such as @Before("@needsCart").

Background vs hooks: Background is visible business context that readers should see; hooks (@Before, @After) are technical setup such as starting the browser — keep those out of the feature file.

Data Tables vs Examples

They look similar but do different jobs. Examples runs the whole scenario once per row. A Data Table passes a table to a single step:

  Scenario: Register a new customer
    When the user registers with:
      | name  | Asha             |
      | email | asha@example.com |
      | city  | Pune             |
    Then the account should be created

In the step definition it arrives as a DataTable you can convert to a Map or a list.

Grouping With Rule

Newer Gherkin lets you group scenarios under the business rule they illustrate, each with its own optional Background:

Feature: Account lockout

  Rule: An account locks after 3 failed attempts
    Scenario: Locked after the third failure
      Given the user has failed to log in 2 times
      When the user enters a wrong password again
      Then the account should be locked

How Steps Map to Step Definitions

Each step is matched to a Java method by its text. With Cucumber Expressions, {string} captures quoted text and passes it as a parameter:

public class LoginSteps {

    @When("the user logs in with {string} and {string}")
    public void theUserLogsInWith(String email, String password) {
        loginPage.login(email, password);
    }

    @Then("the error message {string} should be displayed")
    public void theErrorMessageShouldBeDisplayed(String expected) {
        Assert.assertEquals(loginPage.errorText(), expected);
    }
}

More in BDD Step Definitions & Cucumber Expressions.

Reusing Steps Across Feature Files

Yes — step definitions are global. If two feature files use the same step text, Cucumber runs the same method, as long as the class is on the glue path. Keep common steps (login, navigation) in a shared package. Two methods matching the same text cause an AmbiguousStepException.

Writing Good Gherkin

  • Declarative, not imperative: "When the user logs in with valid credentials" beats "When I type in the email box and click the blue button".
  • One behavior per scenario, ideally 3–7 steps.
  • Business language — no CSS selectors, URLs or technical waits in feature files.
  • Consistent step wording so steps are reused instead of duplicated.
  • Meaningful titles that read like a specification.

Real-world pitfalls and fixes: BDD Challenges in Real Projects.

From Real Projects

BDD and TDD are part of the frameworks I've worked with. What makes BDD valuable is the conversation: scenarios written in plain language that testers, developers and product people all understand, which is also the idea behind Testsigma's plain-English test creation. Keep each scenario focused on one behavior and let the step definitions call your existing page and business-library code. Use a Scenario Outline only when the steps are identical and only the data changes; otherwise write separate scenarios.

📖 Related tutorials

📚 Official documentation: Cucumber documentation · ISTQB Glossary of testing terms

FAQs

What is a feature file?

A .feature file written in Gherkin that describes business scenarios in plain language. It serves as acceptance criteria and is mapped to step definitions for automation.

What does a feature file contain?

A Feature with an optional description, an optional Background, one or more Scenarios or Scenario Outlines, and Given/When/Then (plus And/But) steps. It can also contain tags, Rules, Data Tables and comments.

What is the difference between Scenario and Scenario Outline?

A Scenario runs once with one data set. A Scenario Outline runs the same steps once per row of its Examples table, using placeholders.

What is the Examples keyword?

The data table for a Scenario Outline — each row runs the scenario once, replacing placeholders with that row's values.

Can a feature file have multiple Backgrounds?

No — one Background per feature file (or one per Rule). Use separate feature files or tagged hooks for conditional setup.

What is the difference between a Data Table and Examples?

Examples repeats the whole scenario for each row. A Data Table passes a table of data to a single step.

Can steps be reused across feature files?

Yes. Step definitions are matched by step text, so identical text in any feature file runs the same method.