Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Scenario Outlines and Data

Scenario Outlines and Examples Tables

Run one scenario template against many data rows with Scenario Outline and Examples: placeholder syntax, how outlines expand, naming rows, reporting and when not to use them.

Imagine the shipping rule has six interesting order totals: 0, 49, 49.99, 50, 51 and 500. Writing six nearly identical scenarios is tedious and noisy. A Scenario Outline solves it: you write the scenario once with <placeholders> and list the data in an Examples table. Cucumber runs the scenario once per row.

The syntax

GHERKIN
Feature: Shipping cost

  Scenario Outline: Shipping depends on the order total
    Given an order worth <total> dollars
    When the shipping cost is calculated
    Then the shipping cost is <shipping> dollars

    Examples:
      | total | shipping |
      | 10    | 5        |
      | 49    | 5        |
      | 50    | 0        |
      | 51    | 0        |
      | 500   | 0        |

Parts of an outline:

  • Scenario Outline: (or Scenario Template:) replaces Scenario:.
  • Placeholders in angle brackets <total> appear in steps, and also in the scenario title, doc strings and data tables.
  • Examples: (or Scenarios:) holds a table. The first row is the header with the placeholder names; every following row is one scenario.
  • Columns are separated by |. Extra whitespace is trimmed, so align the columns for readability.

Cucumber turns each row into an ordinary scenario by substituting each <name> with the cell value. Step definitions never know about the outline: they see an order worth 10 dollars, then an order worth 49 dollars, and so on. The step definitions from earlier lessons (an order worth {int} dollars) work unchanged.

Outline in, scenarios out

Template Steps with <placeholders>
Examples A table of data rows
Run One scenario per row

Five rows become five independent scenarios.

1 / 2

A stand-in expander

Expansion is nothing but text substitution. This stand-in expands an outline into plain scenarios, exactly what Cucumber does internally (the real tool keeps track of the table row so reports can show it). Add a row to the table and rerun.

Java Stand-in: expanding an outline into scenarios

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Running an outline against logic

Now combine the expander with matching and checking. The program below runs each row through a shipping calculator and reports per row, the way Cucumber's console shows each example. One row has a deliberately wrong expectation so you can see how a failing row is reported while the rest still run.

Java Stand-in: every row is its own scenario

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Note that a failing row does not stop the others. Each row is an independent scenario with fresh state, so you see all the failing rows in one run.

Placeholders everywhere

Placeholders are substituted in:

  • step text: Given an order worth <total> dollars
  • the scenario title, so each run has a distinct name: Scenario Outline: Shipping for <total> dollars
  • doc strings and data tables inside steps (see the next lessons)

They are not substituted in the Examples header or in tags. And an outline step such as <total> alone is not a valid step (the step text must be recognizable after substitution).

A useful trick is a result column that appears in the title, so that report lines read like documentation:

GHERKIN
Scenario Outline: A <total> dollar order pays <shipping> dollars shipping

Quotes and empty cells

If a value contains spaces and the step uses , quote it in the step, not in the cell:

GHERKIN
Given the user "<name>" signs in

Examples:
  | name       |
  | Maria Lopez |

An empty cell substitutes an empty string, which suits "no value" cases: Given the coupon code "<code>" with a blank code cell gives Given the coupon code "". A literal pipe inside a cell is written \|; a backslash is \\.

Outline versus data tables

Beginners often mix up two table features:

Examples table Step data table
Location Under Examples: of an outline Directly under one step
Meaning One scenario per row Structured data given to one step
Placeholders Header names used as <x> No placeholders needed
Runs N scenarios 1 scenario

Use an outline when you want the same behavior checked with different data (the data changes the scenario). Use a data table when one scenario needs a collection as input (the data is the input of a step), for example a list of products in a cart. The data-table feature is the next lesson: data tables.

When outlines help and when they hurt

Good uses:

  • Boundary values and equivalence classes of one rule.
  • Calculations with several inputs and one output, such as tax or shipping.
  • Validation messages for different bad inputs.

Weak uses:

  • Different behaviors squeezed into one outline with flags like isAdmin=true. If the steps would read differently, write separate scenarios.
  • Giant tables of 80 rows. Nobody reads them, and the suite slows down. Move exhaustive data testing to unit tests and keep a representative sample in the outline.
  • Placeholders for everything. A scenario where every word is <something> is a spreadsheet, not an example.

Name the rule in the outline title and let the table show the variations. When a row fails, you want to know which rule broke and which data triggered it. The report prints the row's values for you.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Cucumber do with a Scenario Outline that has four data rows?

    Each row is expanded into a normal scenario with fresh state.
  2. 2. Which row of the Examples table gives the placeholder names?

    The header cells name the placeholders you write as <name> in the steps.
  3. 3. Where can you use <placeholders>?

    They are substituted in steps, the title and the multi-line arguments, but not in tags or the header.
  4. 4. A scenario needs a list of products as input to one step. What should you use?

    A data table is structured input to a step; an outline repeats the whole scenario.

Summary

  • A Scenario Outline is a template; an Examples table supplies one row per generated scenario.
  • Placeholders <name> are substituted in steps, the title and multi-line arguments.
  • Rows run independently, so one failure never hides the others.
  • Use outlines for the same behavior with varying data; avoid huge tables and mixed behaviors.
  • Step definitions do not know about outlines; they just see the substituted text.

Next: Data Tables