Learning Objectives
By the end of this lesson you will be able to:
- Write the correct syntax for a Gherkin Doc String
- Identify content that belongs in a Doc String rather than a Data Table or an inline parameter
- Explain the structural difference between a Doc String (unstructured prose) and a Data Table (structured fields)
The Syntax
A Doc String is a block of free-form text wrapped in a pair of """ markers, placed directly beneath a step:
Given the support ticket has the following description:
"""
The export button on the analytics dashboard does nothing when clicked.
No error message appears, no network request fires, and the console
shows no JavaScript errors either. Reproduced on both Chrome and Firefox,
only when the date range filter is set to a custom range.
"""
Everything between the two """ lines is passed through as one multi-line string, whitespace and line breaks included. There's no grid, no cells, no columns — just text, exactly as written.
What Belongs in a Doc String
Doc Strings exist for content that is inherently prose or an unstructured blob, not a set of named fields:
- A bug report's free-text description or a support ticket's body
- A block of legal or compliance text — terms and conditions, a privacy clause
- The body of an email or notification being tested
- A raw JSON or XML payload being sent to an API, when you want to show it verbatim rather than break it into fields
Given the following email is queued for delivery:
"""
Subject: Your order has shipped
Hi Jane,
Your order #48213 has shipped and is on its way. Estimated delivery
is Thursday. Track it any time from your account dashboard.
"""
Trying to force this into a Data Table would mean inventing fake "field" and "value" rows for what is actually one continuous piece of writing — you'd lose the paragraph breaks, the tone, and the readability that make it recognizable as an email in the first place.
Doc String vs. Data Table
The two structures solve different shapes of the same underlying problem — "this step needs more than one line of data" — but they solve it for opposite kinds of content:
| Data Table | Doc String | |
|---|---|---|
| Shape of data | Structured: named fields, or rows sharing columns | Unstructured: free-form prose or a text blob |
| Example | A ten-field registration form | A bug report's description paragraph |
| What you'd lose by using the wrong one | Forcing prose into a table invents fake fields that don't exist | Forcing fields into a Doc String throws away the field names, so automation has to re-parse the blob |
A quick test: if you can label your data with column headers and it still makes sense, it's a Data Table. If labeling it would feel arbitrary — because it's really just one continuous piece of writing — it's a Doc String.
Doc Strings and Inline Parameters
Don't reach for a Doc String when a single short value would do. A one-line string still belongs directly in the step:
# Overkill — one short line doesn't need a Doc String
Given the ticket has the following description:
"""
Login button is broken
"""
# Better — just say it
Given a ticket with the description "Login button is broken"
Doc Strings earn their keep when the text spans multiple lines or is long enough that embedding it in the step's sentence would be unreadable.
Pro Tip: Ask "would I ever want to reference this as separate labeled fields?" If yes, it's Data Table material. If the answer is "no, it's just one piece of writing," it's Doc String material.
Key Takeaways
- A Doc String is a
"""-delimited block of free text attached directly beneath a step - It preserves line breaks and whitespace exactly, unlike a Data Table's structured cells
- Use it for prose and blobs — bug descriptions, legal text, email bodies, raw payloads
- Data Tables suit structured, named-field data; Doc Strings suit unstructured, continuous text
- A single short line doesn't need a Doc String — put it inline in the step instead