Learning Objectives
By the end of this lesson you will be able to:
- Write the correct syntax for a Gherkin Data Table
- Rewrite a wall-of-And scenario as a single step with an attached Data Table
- Explain, at a conceptual level, how a step definition receives a Data Table's rows
- Judge when a Data Table is the right tool and when it's overkill
The Syntax
A Data Table is a grid of pipe-delimited rows placed directly beneath a step — no keyword, no blank line between the step and the table. Each row is a | at the start, one or more cells separated by |, and a closing |.
Given the following user profile:
| field | value |
| username | jane.doe |
| email | jane.doe@email.com |
| role | administrator |
That's it. No special keyword introduces the table — Gherkin recognizes it purely by the fact that pipe-delimited lines immediately follow a step.
Rewriting the Wall of And
Recall the ten-field registration scenario from the previous lesson. With a Data Table, it collapses to this:
Scenario: A visitor registers a new account
Given the user is on the registration page
And the user fills in the registration form with:
| field | value |
| first name | Jane |
| last name | Doe |
| email | jane.doe@example.com |
| password | Sup3rSecret! |
| phone | +1-555-0100 |
| address | 42 Baker Street |
| city | London |
| postal code | NW1 6XE |
| country | United Kingdom |
| marketing consent| yes |
When the user submits the registration form
Then the account is created successfully
One step. Ten rows. Zero repeated And-per-field lines. The trigger (When the user submits...) is no longer buried — it's the very next line after the table ends, exactly where a reader expects to find it.
How the Step Definition Receives It
You don't need to write automation code to benefit from this lesson, but it helps to know what happens conceptually on the other side. The automation layer parses the table into a structured object — typically a list of key-value pairs, or a full row-per-record table when there are multiple rows with shared columns. The step definition receives this as one argument instead of ten, and can look up "email" or "postal code" by name instead of juggling ten separate step parameters.
This is the payoff: the table carries the structure, so neither the Gherkin file nor the step definition has to reconstruct "these ten values belong together" by convention or naming.
Two Table Shapes
A Data Table can also represent several records at once, using its first row as column headers:
Given the following existing users:
| username | role | active |
| jane.doe | administrator | true |
| john.roe | viewer | false |
Both shapes — a single vertical field | value list, or a horizontal header row + data rows grid — are the same underlying mechanism. Choose whichever layout matches your data: vertical for one object's many fields, horizontal for many objects sharing the same fields.
When a Data Table Is Overkill
Not every step benefits from a table. If a step only needs one value, a Data Table adds ceremony without adding clarity:
# Overkill — a table for a single value
Given the user's role:
| role |
| administrator |
# Better — just say it
Given the user has the "administrator" role
The rule of thumb: reach for a Data Table when you have several related fields or several rows that share the same shape. For a single scalar value, an inline parameter in the step text is clearer and shorter.
Pro Tip: If your Data Table only ever has one column and one row, that's a sign the value belongs directly in the step's sentence, not in a table.
Key Takeaways
- A Data Table is a pipe-delimited grid attached directly beneath a step, with no introductory keyword
- It replaces a chain of one-And-per-field steps with a single step carrying structured data
- The step definition receives the table as a structured object (key-value pairs or rows of records), not as separate parameters
- Data Tables come in two shapes: a vertical field/value list, or a horizontal multi-row grid with column headers
- A Data Table for a single value is overkill — put that value inline in the step instead