Merge pull request #717 from jsa34/docstrings

Docstrings

Author: youtux

CHANGES.rst

@@ -10,7 +10,9 @@ 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 <https://cucumber.io/docs/gherkin/reference/#data-tables>`).
+- Added `docstring` argument for steps that contain a docstring (see `Doc Strings <https://cucumber.io/docs/gherkin/reference/#doc-strings>`).
+- Multiline strings no longer match name based on multiple lines - only on the actual step text on the step line.
 
 8.0.0b1
 ----------

README.rst

@@ -428,53 +428,6 @@ A common use case is when we have to assert the outcome of an HTTP request:
             Then the request should be successful
 
 
-Multiline steps
----------------
-
-As Gherkin, pytest-bdd supports multiline steps
-(a.k.a. `Doc Strings <https://cucumber.io/docs/gherkin/reference/#doc-strings>`_).
-
-.. code-block:: gherkin
-
-    Feature: Multiline steps
-        Scenario: Multiline step using sub indentation
-            Given I have a step with:
-                """
-                Some
-                Extra
-                Lines
-                """
-            Then the text should be parsed with correct indentation
-
-A step is considered as a multiline one, if the **next** line(s) after its first line is encapsulated by
-triple quotes. The step name is then simply extended by adding further lines inside the triple quotes.
-In the example above, the Given step name will be:
-
-.. code-block:: python
-
-    'I have a step with:\nSome\nExtra\nLines'
-
-You can of course register a step using the full name (including the newlines), but it seems more practical to use
-step arguments and capture lines after first line (or some subset of them) into the argument:
-
-.. code-block:: python
-
-    from pytest_bdd import given, then, scenario, parsers
-
-
-    scenarios("multiline.feature")
-
-
-    @given(parsers.parse("I have a step with:\n{content}"), target_fixture="text")
-    def given_text(content):
-        return content
-
-
-    @then("the text should be parsed with correct indentation")
-    def text_should_be_correct(text):
-        assert text == "Some\nExtra\nLines"
-
-
 Scenarios shortcut
 ------------------
 
@@ -561,8 +514,8 @@ Example:
         assert cucumbers["start"] - cucumbers["eat"] == left
 
 
-Step Definitions and Accessing the Datatable
---------------------------------------------
+Datatables
+----------
 
 The ``datatable`` argument allows you to utilise data tables defined in your Gherkin scenarios
 directly within your test functions. This is particularly useful for scenarios that require tabular data as input,
@@ -653,6 +606,89 @@ Full example:
         assert users_have_correct_permissions(users, expected_permissions)
 
 
+Docstrings
+----------
+
+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 some steps will have docstrings
+
+        Then a step has a docstring
+        """
+        This is a docstring
+        on two lines
+        """
+
+        And a step provides a docstring with lower indentation
+        """
+    This is a docstring
+        """
+
+        And this step has no docstring
+
+        And this step has a greater indentation
+        """
+            This is a docstring
+        """
+
+        And this step has no docstring
+
+.. code-block:: python
+
+        from pytest_bdd import given, then
+
+
+        @given("some steps will have docstrings")
+        def _():
+            pass
+
+        @then("a step has a docstring")
+        def _(docstring):
+            assert docstring == "This is a docstring\non two lines"
+
+        @then("a step provides a docstring with lower indentation")
+        def _(docstring):
+            assert docstring == "This is a docstring"
+
+        @then("this step has a greater indentation")
+        def _(docstring):
+            assert docstring == "This is a 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

@@ -173,6 +173,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
         ]
@@ -228,13 +229,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.
 
@@ -251,6 +260,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.
@@ -347,12 +357,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 []
 
@@ -361,25 +365,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

@@ -199,15 +199,19 @@ def _execute_step_function(
             f"Unexpected `NoneType` returned from " f"parse_arguments(...) in parser: {context.parser!r}"
         )
 
-        if step.datatable is not None:
-            kwargs["datatable"] = step.datatable.raw()
-
         for arg, value in parsed_args.items():
             if arg in converters:
                 value = converters[arg](value)
             kwargs[arg] = value
 
+        if step.datatable is not None:
+            kwargs["datatable"] = step.datatable.raw()
+
+        if step.docstring is not None:
+            kwargs["docstring"] = step.docstring
+
         kwargs = {arg: kwargs[arg] if arg in kwargs else request.getfixturevalue(arg) for arg in args}
+
         kw["step_func_args"] = kwargs
 
         request.config.hook.pytest_bdd_before_step_call(**kw)

tests/datatable/test_datatable.py

@@ -97,10 +97,10 @@ def test_datatable():
     ]
 
 
-def test_steps_with_missing_datatables(pytester):
+def test_datatable_argument_in_step_impl_is_optional(pytester):
     pytester.makefile(
         ".feature",
-        missing_datatable=textwrap.dedent(
+        optional_arg_datatable=textwrap.dedent(
             """\
             Feature: Missing data table
 
@@ -110,7 +110,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
             """
         ),
@@ -126,7 +126,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)
 
@@ -139,17 +139,74 @@ def _(datatable):
         )
     )
 
+    pytester.makepyfile(
+        textwrap.dedent(
+            """\
+        from pytest_bdd import scenarios
+
+        scenarios("optional_arg_datatable.feature")
+        """
+        )
+    )
+    result = pytester.runpytest("-s")
+    result.assert_outcomes(failed=1)
+    result.stdout.fnmatch_lines(["*fixture 'datatable' not found*"])
+
+
+def test_steps_with_datatable_missing_argument_in_step(pytester):
+    pytester.makefile(
+        ".feature",
+        missing_datatable_arg=textwrap.dedent(
+            """\
+            Feature: Missing datatable
+
+              Scenario: Datatable arg is missing for a step definition
+                Given this step has a datatable
+                    | name  | email             | age |
+                    | John  | [email protected]  | 30  |
+
+                When this step has a datatable but no datatable argument
+                    | name  | email             | age |
+                    | John  | [email protected]  | 30  |
+
+                Then the test passes
+            """
+        ),
+    )
+    pytester.makeconftest(
+        textwrap.dedent(
+            """\
+        from pytest_bdd import given, when, then
+
+
+        @given("this step has a datatable")
+        def _(datatable):
+            print(datatable)
+
+
+        @when("this step has a datatable but no datatable argument")
+        def _():
+            pass
+
+
+        @then("the test passes")
+        def _():
+            pass
+
+    """
+        )
+    )
+
     pytester.makepyfile(
         textwrap.dedent(
             """\
         from pytest_bdd import scenario
 
-        @scenario("missing_datatable.feature", "Data table is missing for a step")
+        @scenario("missing_datatable_arg.feature", "Datatable arg is missing for a step definition")
         def test_datatable():
             pass
         """
         )
     )
     result = pytester.runpytest("-s")
-    result.assert_outcomes(failed=1)
-    result.stdout.fnmatch_lines(["*fixture 'datatable' not found*"])
+    result.assert_outcomes(passed=1)