Parameterizing Gherkin Scenarios with Cucumber Scenario Outlines and Examples Tables

The Short Answer

When several Gherkin scenarios differ only by input data, copying and pasting the scenario body creates maintenance overhead. Cucumber Scenario Outlines solve this by running one template once per row in an Examples table. The useful takeaway: use a Scenario Outline when the steps are identical and only the data changes, but keep the table small enough to read at a glance.

How Placeholder Mapping Works

In a Scenario Outline, text inside angle brackets—such as <username>—is a placeholder. Cucumber matches the placeholder name to a column header in the Examples table. Before each execution, it substitutes the placeholder with the value from the current row.

Step definitions do not reference Examples column headers directly. They match the final, substituted step text using Cucumber expressions or regular expressions. For example, a step that reads the user enters "alice" and "secret123" after substitution is matched by a step definition that captures two string parameters.

Worked Example

A typical login feature looks like this:

Feature: User authentication

  Scenario Outline: Login with valid and invalid credentials
    Given the user navigates to the login page
    When the user enters "<username>" and "<password>"
    Then the login result should be "<expectedResult>"

    Examples:
      | username | password   | expectedResult |
      | alice    | secret123  | success        |
      | bob      | wrongpass  | failure        |

The corresponding Java step definitions use Cucumber expressions to capture the substituted values:

@When("the user enters {string} and {string}")
public void enterCredentials(String username, String password) {
    // pass credentials to the application under test
}

@Then("the login result should be {string}")
public void verifyResult(String expectedResult) {
    // assert the observed outcome
}

With two data rows, Cucumber executes the scenario twice: once with alice/secret123 and once with bob/wrongpass. Each execution is reported as a separate test result.

Running the Suite and Checking Results

Run the Cucumber suite from the project root using the command appropriate for your implementation. For example, in a Maven-based Java project you might run mvn test; in a JavaScript project, npm test. Required permissions are the same as your normal test execution user. No special privileges are needed beyond read access to the feature files and write access to the reports directory.

Expected check: the test report should show one execution per Examples data row, excluding the header. If you have two rows, expect two results. If the count differs, a placeholder may not be resolving correctly.

Relevant risks: running the full suite can be slow if the Examples table is large. Use tag or line filters to run only the Scenario Outline during development.

Limits and Common Mistakes

• Header mismatch. Placeholder names must exactly match Examples column headers. A typo such as <user_name> versus a header named user name causes a runtime mapping error.
• Readability decay. Large Examples tables make the feature file hard to read. When you have more than a handful of columns or rows, move complex data into Doc Strings—multi-line string arguments in Gherkin—external fixtures, or a data provider.
• No nesting. Cucumber does not support nested Examples blocks. Hierarchical data requires separate scenarios, tags, or a Background step—a step that runs before each scenario in the feature—that loads structured data.
• Per-row reporting. Each row is a separate test. A table with 50 rows produces 50 test results, which can clutter reports and slow feedback loops.

Practical Verification

To confirm parameter binding, add a temporary assertion or log statement in the step definition that prints the received arguments. Run only the Scenario Outline using a tag or line number filter. Verify that each printed value matches the corresponding Examples row. Remove the temporary logging after confirmation.

If a placeholder is undefined, Cucumber will typically fail before or during step execution, though the exact error message varies by implementation and version. The failure will indicate that a placeholder could not be resolved or that no step definition matched the substituted text.