A Cucumber doc string carrying a YAML payload broke after the feature file was reindented - how does Cucumber decide which leading whitespace it strips?

## How Cucumber delimits a doc string A doc string is a multi-line text argument attached to the step directly above it. It opens with a line containing only `"""` (triple backticks are accepted as an alternative delimiter) and closes with a matching line. The text between the delimiters is passed to the step definition as its final argument — a `String` in Cucumber-JVM, the last argument of the step function in cucumber-js, `context.text` in Behave, a string parameter in SpecFlow/Reqnroll. Only one doc string may be attached to a step, and it must be the last thing on that step, since it runs to its closing delimiter. To include a literal triple-quote inside the content, escape each quote with a backslash; Gherkin unescapes it before handing the text over. ## The dedent rule: the opening delimiter is the ruler Here is the mechanic the question turns on. **The indentation of the opening delimiter decides how much leading whitespace is removed from every content line.** Concretely: from each line of the content, Cucumber removes *up to* as many leading whitespace characters as the opening `"""` is indented by. A line indented less than the delimiter simply loses whatever leading whitespace it has; no visible character is ever eaten. ```gherkin Then the kitchen manifest is: """yaml date: 2026-05-14 meals: vegetarian: 118 """ ``` The delimiter sits at column 2, so two spaces come off each line. `date:` arrives at column 0 and `vegetarian:` at column 2 — the payload keeps its **relative** shape, which is exactly what makes an indented block readable in the feature file and still correct as YAML. Three corollaries follow, and each is a common wrong answer: - It is **not** "strip all leading whitespace" — that would flatten every nested structure. - It is **not** "strip the common prefix of the content lines" — the least-indented content line has no say; only the delimiter does. - The **closing** delimiter's indentation does not enter the calculation, and trailing whitespace on content lines is preserved. ## Why a reindent breaks a whitespace-sensitive payload | Payload | Sensitive to a shifted body? | What you see when it shifts | |---|---|---| | JSON | no | nothing; whitespace between tokens is insignificant | | YAML | yes | nesting changes, keys move under the wrong parent, or a parse error | | Markdown | yes | four extra spaces silently turn a paragraph into a code block | | Plain text compared as a string | yes | an assertion diff of invisible characters | The dangerous edit is any change that moves the **body relative to the delimiter** — reindenting the content lines while the delimiter stays put, moving the delimiter while the body stays put, or a formatter that normalises indentation inside the block. Move the whole block together and nothing changes, which is why the break feels random: an edit that looks like pure formatting alters the argument the step receives. On a school-meal ordering service whose suite two teams both edit, this shows up as a manifest scenario that passed for weeks and fails after a reformatting commit that touched nothing else. The diff is whitespace-only, the step definition is untouched, and the assertion compares two strings that look identical in the terminal. ## Diagnosing it, and stopping it recurring 1. **Confirm it is whitespace.** Print the received text with a visible marker per line, or compare lengths. A diff tool that ignores whitespace will hide exactly the thing that broke. 2. **Measure the delimiter.** Check the column of the opening `"""` against the column of the first content line in both the old and the new revision. That single comparison identifies the change. 3. **Stop comparing raw strings.** Parse the doc string in the step definition and assert on the resulting structure. A YAML or JSON payload compared as a string turns every cosmetic edit into a test failure; parsed and compared as data, indentation stops mattering. 4. **Use the content type.** A word may follow the opening delimiter — `"""yaml`, `"""json`. It records what the content is, and Cucumber-JVM can convert the doc string into a typed object by registering a `@DocStringType` for that content type. The payoff for this problem is that a corrupted payload then fails while being converted, with a parse message, instead of failing as an opaque string mismatch three assertions later. 5. **Keep bulk fixtures out of feature files.** A feature file is specification a non-engineer reads. A forty-line payload is not that; reference it by an identifier in the step and load it from a fixture file. This also shrinks the surface a formatter can disturb. 6. **Pin the formatter.** If an editor or repository-wide formatter touches `.feature` files, either configure it to leave them alone or agree on it across both teams — a suite where half the contributors reformat on save will keep producing this failure.