The Syntax

Learning Objectives

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

Recognize the copy-paste problem that parameterization solves
Read and write <angle-bracket> placeholder tokens inside a step
Explain why a placeholder is a substitution token, not a programming variable

The Problem: Scenarios That Only Differ by One Number

Look at this rule for a discount code: it only applies to orders over $50. A tester eager to cover it might write three scenarios like this:

Scenario: Discount applies to an order over the threshold
  Given a cart total of $75
  When the customer applies code "SAVE10"
  Then the discount is accepted

Scenario: Discount applies exactly at the threshold
  Given a cart total of $50
  When the customer applies code "SAVE10"
  Then the discount is accepted

Scenario: Discount is rejected below the threshold
  Given a cart total of $49
  When the customer applies code "SAVE10"
  Then the discount is rejected

Every line is identical except for one number and one outcome. This is not thoroughness — it's the same scenario typed three times with a single digit swapped. Anyone maintaining this file has to edit three blocks every time the wording of a step changes, and it's easy for one copy to quietly fall out of sync with the others.

The Fix: A Placeholder Token

Gherkin lets you write the shared logic exactly once, replacing the values that change with a token in <angle brackets>:

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

<total> and <outcome> are not variables you assign in code — they are placeholders that the Gherkin runner substitutes with a concrete value pulled from a table row before the scenario ever executes. By the time the step actually runs, <total> has already been replaced with $75, $50, or $49 — the runner never "evaluates" the placeholder at runtime the way a program evaluates a variable.

Placeholders Can Appear Anywhere in a Step

A placeholder isn't limited to the end of a line or to numbers. It can sit anywhere text would normally go, and a single step can use more than one:

Then the discount is <outcome> for a "<currency>" cart

The only rule at this stage: the name inside the angle brackets must exactly match the header of the column supplying its value — you'll see exactly how that pairing works in the next lesson.

Why Not Just Use a Variable Name?

Calling <total> a "variable" invites the wrong mental model. A programming variable can be reassigned, computed, or mutated during execution. A Gherkin placeholder is a static, one-time text substitution that happens before the scenario is interpreted at all — closer to a mail-merge field than to a variable in a for loop. Thinking of it as a variable leads people to expect logic (like <total> * 2) inside the placeholder, which Gherkin does not support.

Pro Tip: If you catch yourself wanting to do arithmetic or conditionals inside a <placeholder>, that's a signal the calculation belongs in the step definition code, not in the feature file.

Key Takeaways