Anatomy of a Scenario Outline

Learning Objectives

By the end of this lesson you will be able to:

• Identify the two parts that make a Scenario Outline complete: the outline itself and its Examples: table
• Explain how a single row in an Examples: table produces one full scenario run
• Apply the rule that every placeholder used in a step must have a matching column, and vice versa

Scenario Outline Is Not Just a Renamed Scenario

Scenario Outline: looks almost identical to Scenario: — same Given/When/Then structure underneath — but it is never run on its own. A Scenario Outline is a template. It only becomes an executable scenario once it's paired with an Examples: table supplying the data:

Scenario Outline: Discount threshold behavior
  Given a cart total of <total>
  When the customer applies code "SAVE10"
  Then the discount is <outcome>

  Examples:
    | total | outcome  |
    | $75   | accepted |
    | $50   | accepted |
    | $49   | rejected |

Without the Examples: table underneath it, a Scenario Outline has nothing to run against — there is no data to substitute into <total> and <outcome>. This is the single most important structural difference from a plain Scenario:.

One Row, One Full Scenario Run

Each row of the Examples: table is not a "variation" tacked onto a shared run — it produces its own complete, independent execution of the outline, from Given through Then. The table above therefore represents three full scenario runs, not one scenario with three data points. If a test report lists results, it lists three separate outcomes: $75 → accepted, $50 → accepted, $49 → rejected.

This matters for reporting and for debugging: a failure in row two doesn't affect row one or row three. Each row lives and dies on its own.

The Column-Placeholder Matching Rule

Every <placeholder> referenced inside the outline's steps must have a corresponding column in the Examples: table with the exact same name. The reverse also holds: a column in the table that no step ever references is dead weight — data nobody reads, sitting in the file and confusing the next person who opens it.

Scenario Outline: Discount threshold behavior
  Given a cart total of <total>
  When the customer applies code "SAVE10"
  Then the discount is <outcome>

  Examples:
    | total | outcome  | region |
    | $75   | accepted | US     |

Here, region is defined as a column but never used as <region> anywhere in the steps. It's not a syntax error — Gherkin will still run — but it's a maintenance smell: either the column should be deleted, or a step is missing that was supposed to use it.

Why the Header Row Comes First

The first row of Examples: is always the header, naming each column. Every row after it supplies one set of values, matched to those headers by position. Get the column order wrong relative to the header and the runner substitutes the wrong value into the wrong placeholder — the outline still executes, it just tests the wrong thing silently.

Pro Tip: Before adding a new Examples: row, re-read the header line first. A copy-pasted row with columns in the wrong order is a bug that produces no error message — it just quietly tests garbage.

Key Takeaways

• A Scenario Outline without a paired Examples: table has nothing to execute — the two are structurally inseparable
• Each row in Examples: produces one independent, full scenario run, not a variation of a shared one
• Every placeholder in the steps needs a matching column, and every column should be used by at least one placeholder
• The header row defines column names; all data rows are matched to it by position, not by re-reading names