diff --git a/README.rst b/README.rst index 4b5ce9f..3525bea 100644 --- a/README.rst +++ b/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 diff --git a/tests/steps/test_docstring.py b/tests/steps/test_docstring.py index 333815e..f091796 100644 --- a/tests/steps/test_docstring.py +++ b/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[1] == "This is a when docstring" - assert docstrings[2] == "This is a then docstring" + assert docstrings == ["This is a given docstring", "This is a when docstring", "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 re import DOTALL + from pytest_bdd import given, when, then @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)