Remove references to multiline strings

Add docstring

Author: jsa34

CHANGES.rst

@@ -6,7 +6,8 @@ Unreleased
 - Update documentation to clarify that `--gherkin-terminal-reporter` needs to be used with `-v` or `-vv`.
 - Drop compatibility with pytest < 7.0.0.
 - Continuation of steps using asterisks instead of And/But supported.
-- Added `datatable` argument for steps that contain a datatable.
+- Added `datatable` argument for steps that contain a datatable (see Data Tables section at https://cucumber.io/docs/gherkin/reference/)
+- Added `docstring` argument for steps that contain a docstring (see Doc Strings section at https://cucumber.io/docs/gherkin/reference/).
 
 8.0.0b1
 ----------

README.rst

@@ -561,7 +561,7 @@ Example:
         assert cucumbers["start"] - cucumbers["eat"] == left
 
 
-Step Definitions and Accessing the Datatable
+Datatable Argument and Accessing the Datatable
 --------------------------------------------
 
 The ``datatable`` argument allows you to utilise data tables defined in your Gherkin scenarios
@@ -653,6 +653,78 @@ Full example:
         assert users_have_correct_permissions(users, expected_permissions)
 
 
+Docstring Argument and Accessing the Docstring
+---------------------------------------------
+
+The `docstring` argument allows you to access the Gherkin docstring defined in your steps as a multiline string.
+The content of the docstring is passed as a single string, with each line separated by `\n`.
+Leading indentation are stripped.
+
+For example, the Gherkin docstring:
+
+.. code-block:: gherkin
+    """
+    This is a sample docstring.
+    It spans multiple lines.
+    """
+
+
+Will be returned as:
+
+.. code-block:: python
+    "This is a sample docstring.\nIt spans multiple lines."
+
+
+Full example:
+
+.. code-block:: gherkin
+
+    Feature: Docstring
+
+      Scenario: Step with docstrings
+        Given a step has a docstring
+        """
+        This is a given docstring
+        """
+
+        When a step provides a docstring with lower indentation
+        """
+    This is a when docstring
+        """
+
+        And this step has no docstring
+
+        Then this step has a greater indentation
+        """
+            This is a then docstring
+        """
+
+        And this step has no docstring
+
+.. code-block:: python
+
+        from pytest_bdd import given, when, then
+
+        @given("a step has a docstring")
+        def _(docstring):
+            print(docstring)
+
+        @when("a step provides a docstring with lower indentation")
+        def _(docstring):
+            print(docstring)
+
+        @then("this step has a greater indentation")
+        def _(docstring):
+            print(docstring)
+
+        @then("this step has no docstring")
+        def _():
+            pass
+
+
+.. NOTE::   The docstring argument can only be used for steps that have an associated docstring.
+            Otherwise, an error will be thrown.
+
 Organizing your scenarios
 -------------------------
 

src/pytest_bdd/parser.py

@@ -9,14 +9,14 @@
 
 from .exceptions import StepError
 from .gherkin_parser import Background as GherkinBackground
-from .gherkin_parser import DataTable, ExamplesTable
+from .gherkin_parser import DataTable
 from .gherkin_parser import Feature as GherkinFeature
 from .gherkin_parser import GherkinDocument
 from .gherkin_parser import Scenario as GherkinScenario
 from .gherkin_parser import Step as GherkinStep
 from .gherkin_parser import Tag as GherkinTag
 from .gherkin_parser import get_gherkin_document
-from .types import GIVEN, STEP_TYPES, THEN, WHEN
+from .types import STEP_TYPES
 
 STEP_PARAM_RE = re.compile(r"<(.+?)>")
 COMMENT_RE = re.compile(r"(^|(?<=\s))#")
@@ -172,6 +172,7 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
                 line_number=step.line_number,
                 keyword=step.keyword,
                 datatable=step.datatable,
+                docstring=step.docstring,
             )
             for step in self._steps
         ]
@@ -227,13 +228,21 @@ class Step:
     line_number: int
     indent: int
     keyword: str
+    docstring: str | None = None
     datatable: DataTable | None = None
     failed: bool = field(init=False, default=False)
     scenario: ScenarioTemplate | None = field(init=False, default=None)
     background: Background | None = field(init=False, default=None)
 
     def __init__(
-        self, name: str, type: str, indent: int, line_number: int, keyword: str, datatable: DataTable | None = None
+        self,
+        name: str,
+        type: str,
+        indent: int,
+        line_number: int,
+        keyword: str,
+        datatable: DataTable | None = None,
+        docstring: str | None = None,
     ) -> None:
         """Initialize a step.
 
@@ -250,6 +259,7 @@ def __init__(
         self.line_number = line_number
         self.keyword = keyword
         self.datatable = datatable
+        self.docstring = docstring
 
     def __str__(self) -> str:
         """Return a string representation of the step.
@@ -346,12 +356,6 @@ def parse_steps(self, steps_data: list[GherkinStep]) -> list[Step]:
             List[Step]: A list of Step objects.
         """
 
-        def get_step_content(_gherkin_step: GherkinStep) -> str:
-            step_name = strip_comments(_gherkin_step.text)
-            if _gherkin_step.docstring:
-                step_name = f"{step_name}\n{_gherkin_step.docstring.content}"
-            return step_name
-
         if not steps_data:
             return []
 
@@ -360,25 +364,25 @@ def get_step_content(_gherkin_step: GherkinStep) -> str:
             raise StepError(
                 message=f"First step in a scenario or background must start with 'Given', 'When' or 'Then', but got {first_step.keyword}.",
                 line=first_step.location.line,
-                line_content=get_step_content(first_step),
+                line_content=first_step.text,
                 filename=self.abs_filename,
             )
 
         steps = []
         current_type = first_step.keyword.lower()
         for step in steps_data:
-            name = get_step_content(step)
             keyword = step.keyword.lower()
             if keyword in STEP_TYPES:
                 current_type = keyword
             steps.append(
                 Step(
-                    name=name,
+                    name=strip_comments(step.text),
                     type=current_type,
                     indent=step.location.column - 1,
                     line_number=step.location.line,
                     keyword=step.keyword.title(),
                     datatable=step.datatable,
+                    docstring=step.docstring.content if step.docstring else None,
                 )
             )
         return steps

src/pytest_bdd/scenario.py

@@ -201,6 +201,9 @@ def _execute_step_function(
         if step.datatable is not None:
             kwargs["datatable"] = step.datatable.raw()
 
+        if step.docstring is not None:
+            kwargs["docstring"] = step.docstring
+
         for arg, value in parsed_args.items():
             if arg in converters:
                 value = converters[arg](value)

tests/datatable/test_datatable.py

@@ -111,7 +111,7 @@ def test_steps_with_missing_datatables(pytester):
                   | John  | [email protected]  | 30  |
                   | Alice | [email protected] | 25  |
 
-                When this step has no data table but tries to use the datatable fixture
+                When this step has no data table but tries to use the datatable argument
                 Then an error is thrown
             """
         ),
@@ -127,7 +127,7 @@ def _(datatable):
             print(datatable)
 
 
-        @when("this step has no data table but tries to use the datatable fixture")
+        @when("this step has no data table but tries to use the datatable argument")
         def _(datatable):
             print(datatable)
 

tests/feature/test_background.py

@@ -7,7 +7,7 @@
 
     Background:
         Given foo has a value "bar"
-        And a background step with multiple lines:
+        And a background step with docstring:
         """
             one
             two
@@ -35,9 +35,9 @@ def foo():
     return {}
 
 
-@given(parsers.re(r"a background step with multiple lines:\n(?P<data>.+)", flags=re.DOTALL))
-def _(foo, data):
-    assert data == "one\ntwo"
+@given("a background step with docstring:")
+def _(foo, docstring):
+    assert docstring == "one\ntwo"
 
 
 @given('foo has a value "bar"')