Response to feedback

README.rst

@@ -514,8 +514,8 @@ Example:
         assert cucumbers["start"] - cucumbers["eat"] == left
 
 
-Datatable Argument 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,
@@ -606,8 +606,8 @@ Full example:
         assert users_have_correct_permissions(users, expected_permissions)
 
 
-Docstring Argument and Accessing the Docstring
+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`.
@@ -635,48 +635,54 @@ Full example:
     Feature: Docstring
 
       Scenario: Step with docstrings
-        Given a step has a docstring
+        Given some steps will have docstrings
+
+        Then a step has a docstring
         """
-        This is a given docstring
+        This is a docstring
         on two lines
         """
 
-        When a step provides a docstring with lower indentation
+        And 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
+        And this step has a greater indentation
         """
-            This is a then docstring
+            This is a docstring
         """
 
         And this step has no docstring
 
 .. code-block:: python
 
-        from pytest_bdd import given, when, then
+        from pytest_bdd import given, then
 
-        @given("a step has a docstring")
+        @given("some steps will have docstrings")
+        def _():
+            pass
+
+        @then("a step has a docstring")
         def _(docstring):
             assert docstring == "This is a given docstring\non two lines"
 
-        @when("a step provides a docstring with lower indentation")
+        @then("a step provides a docstring with lower indentation")
         def _(docstring):
-            print(docstring)
+            assert docstring == "This is a when docstring"
 
         @then("this step has a greater indentation")
         def _(docstring):
-            print(docstring)
+            assert docstring == "This is a when docstring"
 
         @then("this step has no docstring")
         def _():
             pass
 
 
-.. NOTE::   The docstring argument can only be used for steps that have an associated docstring.
+.. note::   The ``docstring`` argument can only be used for steps that have an associated docstring.
             Otherwise, an error will be thrown.
 
 Organizing your scenarios

tests/steps/test_docstring.py

@@ -34,9 +34,8 @@ def test_steps_with_docstrings(pytester):
     pytester.makeconftest(
         textwrap.dedent(
             r"""
-        from pytest_bdd import given, when, then, parsers
+        from pytest_bdd import given, when, then
         from pytest_bdd.utils import dump_obj
-        import re
 
 
         @given("a step has a docstring")
@@ -80,9 +79,7 @@ def test_steps_with_docstrings(pytester):
     result.assert_outcomes(passed=1)
 
     docstrings = collect_dumped_objects(result)
-    assert docstrings[0] == "This is a given docstring"
+    assert docstrings == ["This is a given docstring", "This is a when docstring", "This is a then docstring"]
-    assert docstrings[1] == "This is a when docstring"
-    assert docstrings[2] == "This is a then docstring"
 
 
 def test_steps_with_missing_docstring(pytester):
@@ -106,8 +103,7 @@ def test_steps_with_missing_docstring(pytester):
     pytester.makeconftest(
         textwrap.dedent(
             """\
-        from pytest_bdd import given, when, then, parsers
+        from pytest_bdd import given, when, then
-        from re import DOTALL
 
 
         @given("this step has a docstring")
@@ -142,3 +138,64 @@ def test_steps_with_missing_docstring(pytester):
     result = pytester.runpytest("-s")
     result.assert_outcomes(failed=1)
     result.stdout.fnmatch_lines(["*fixture 'docstring' not found*"])
+
+
+def test_steps_with_docstring_missing_argument_in_step_def(pytester):
+    pytester.makefile(
+        ".feature",
+        missing_docstring_arg=textwrap.dedent(
+            '''\
+            Feature: Missing docstring
+
+              Scenario: Docstring arg is missing for a step definition
+                Given this step has a docstring
+                """
+                This is a given docstring
+                """
+
+                When this step has a docstring but no docstring argument
+                """
+                This is a when docstring
+                """
+
+                Then the test passes
+            '''
+        ),
+    )
+    pytester.makeconftest(
+        textwrap.dedent(
+            """\
+        from pytest_bdd import given, when, then
+
+
+        @given("this step has a docstring")
+        def _(docstring):
+            print(docstring)
+
+
+        @when("this step has a docstring but no docstring argument")
+        def _():
+            pass
+
+
+        @then("the test passes")
+        def _():
+            pass
+
+    """
+        )
+    )
+
+    pytester.makepyfile(
+        textwrap.dedent(
+            """\
+        from pytest_bdd import scenario
+
+        @scenario("missing_docstring_arg.feature", "Docstring arg is missing for a step definition")
+        def test_docstring():
+            pass
+        """
+        )
+    )
+    result = pytester.runpytest("-s")
+    result.assert_outcomes(passed=1)