Guide
Data tables and doc strings in Gherkin: the rules nobody writes down
By Miftode Vasilica, maker of Gherkin Studio ·
A data table hands a step a list or a grid. A doc string hands it a block of text. Both belong to the step directly above them, and both have a few rules that are easy to break without getting an error. This page lists the rules, with what the official Cucumber parser does in each case. We ran every example.
The column that was never there
A tester copies a table of users out of a wiki page into a scenario. The wiki export has no pipe at the end of the lines:
Given these users exist
| name | role | active
| Ana | admin | yes
| Dan | viewer | no
The parser accepts it. No error, no warning. And the table it hands to the step has two columns, not three: everything after the last pipe on a line is dropped. The step creates Ana and Dan, and never hears about active.
The test passed for a month.
Data tables
Scenario: Only admins see the billing page
Given these users exist
| name | role | active |
| Ana | admin | yes |
| Dan | viewer | no |
When Dan opens the billing page
Then he sees "You do not have access"
What the parser checks
- Every row must have the same number of cells. If one does not, you get
inconsistent cell count within the table, with the line number of the short row.
What it does not check
- A missing pipe at the end. As above. If one row lacks it you get the cell-count error. If every row lacks it, you get nothing.
- A header. Gherkin has no notion of a header in a data table. The first row is a row like any other. Whether it holds names or data is decided by the code behind the step.
- A table with no step above it. A row of pipes straight under
Scenario:is read as description text. It is not a table and nothing receives it.
What does not matter
- How far the rows are indented.
- Blank lines and comment lines between rows. The rows above and below still form one table.
- Spaces around the cell text.
|Ana|and| Ana |are the same cell.
Special characters in a cell
| You want | You write |
|---|---|
| A pipe | \| |
| A new line | \n |
| A backslash | \\ |
| An empty cell | | | |
Any other backslash stays as it is.
Doc strings
A doc string is for one piece of text that needs its line breaks: the body of an email, a JSON payload, an error message.
Scenario: Reset email
When I ask for a password reset
Then I receive an email with this text
"""
Hello Ana,
Your reset link works for one hour.
"""
The fence. Three double quotes, or three backticks. The closing fence must be the same kind as the opening one. So a text that itself contains three double quotes can go inside a backtick fence, or you can write the quotes as \"\"\".
Indentation. The text starts at the column of the opening fence. Spaces to the left of that column are removed, spaces to the right of it are kept. You can indent the whole block to line up with the step without adding spaces to the text.
A label after the fence. """json marks the content type. The parser passes the label along and does not check that the text really is JSON.
The one error. A doc string that is never closed gives:
unexpected end of file, expected: #DocStringSeparator, #Other
The line number is the end of the file, not the line where the block opened. Everything after the opening fence was read as text, including any scenarios further down. Count the """ lines in the file. An odd number means one is missing.
Table or doc string?
- Several things of the same shape: a table. Three users, five prices, two dates.
- One piece of text where the line breaks matter: a doc string.
- One value: neither. Put it in the step, in quotes:
Then I see "This link has expired".
A table with one column and one row is a value wearing a costume.
In Gherkin Studio
Format tables lines up the pipes of every table in the story. Before:
Examples:
| plan | users | price per user |
| Free | 10 | 0 |
| Standard | 100 | 2.00 |
After:
Examples:
| plan | users | price per user |
| Free | 10 | 0 |
| Standard | 100 | 2.00 |
What it does and does not do:
- Numbers are right-aligned, text is left-aligned.
- The contents of a cell are never changed, escapes included.
- Emoji and Chinese, Japanese or Korean characters are counted as two columns wide, so the pipes still line up.
- Doc strings are left exactly as you typed them, even when they contain pipes.
- A table with a problem is left alone. If a row has no closing pipe, or the rows have different numbers of cells, the button does not touch that table. So if you press Format tables and one table does not move, count its pipes. That is the wiki table from the start of this page, caught in a second.
- Rows separated by a blank line or a comment are lined up as separate groups.
Short answers
Can one step have two tables?
No. All the rows under a step are one table, even with blank lines between them.
Can a cell contain a line break?
Yes, write \n.
Do placeholders work inside tables and doc strings?
Yes. In a Scenario Outline, <name> inside a cell or inside a doc string is replaced like anywhere else.
Does the parser check my JSON in a doc string?
No. To the parser it is text.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. It is on the Atlassian Marketplace, with a 30-day free trial. See Scenario Outline and Examples tables and what each parser error means.