Multiline Text (Docstrings)

Sometimes a step needs a block of free text: an email body, an SQL statement, a JSON payload, or a markdown document. Gherkin supports docstrings delimited by triple quotes (or triple backticks). Everything between the delimiters is available to the step function as context.text, preserving line breaks exactly as written.

Writing a Docstring

Scenario: Sending a support mail
  Given the support inbox is empty
  When I send this mail:
    """
    Subject: Question about cucumbers
    Hello,
    How many cucumbers do I have left?
    Kind regards
    """
  Then the support inbox contains 1 mail

Reading context.text

from behave import given, when, then

@given("the support inbox is empty")
def step_impl(context):
    context.support_inbox = []

@when("I send this mail:")
def step_impl(context):
    context.last_mail = context.text
    context.support_inbox.append(context.last_mail)

@then("the support inbox contains 1 mail")
def step_impl(context):
    assert len(context.support_inbox) == 1
    assert "cucumbers" in context.last_mail

Indentation Rules

The content of a docstring keeps its indentation relative to the opening delimiter. In the example above the body lines start at the same column as the triple quote, so context.text contains the lines without a leading offset. If you indent the body further, that extra whitespace becomes part of the text, which matters when you parse it or assert on exact content.

Typical Use Cases

Docstrings shine for anything where the payload itself is the test data: HTTP request bodies, CSV pasted inline, configuration files, or natural-language input for a chatbot. The feature file stays readable, and the step implementation receives the payload as a single string it can store, parse, or forward.

Summary

Wrap multiline payloads in triple quotes after a step; behave hands the block to your step function as context.text. Watch indentation, because it is preserved verbatim.