Merge pull request #743 from pytest-dev/render-docstrings-and-datatables-with-example-params

Render docstrings and datatable cells with example table entries

Author: youtux

CHANGES.rst

@@ -24,6 +24,7 @@ Removed
 Fixed
 +++++
 * Fixed an issue with the upcoming pytest release related to the use of ``@pytest.mark.usefixtures`` with an empty list.
+* Render template variables in docstrings and datatable cells with example table entries, as we already do for steps definitions.
 
 Security
 ++++++++

README.rst

@@ -513,6 +513,58 @@ Example:
     def should_have_left_cucumbers(cucumbers, left):
         assert cucumbers["start"] - cucumbers["eat"] == left
 
+
+Example parameters from example tables can not only be used in steps, but also embedded directly within docstrings and datatables, allowing for dynamic substitution.
+This provides added flexibility for scenarios that require complex setups or validations.
+
+Example:
+
+.. code-block:: gherkin
+
+    # content of docstring_and_datatable_with_params.feature
+
+    Feature: Docstring and Datatable with example parameters
+        Scenario Outline: Using parameters in docstrings and datatables
+            Given the following configuration:
+                """
+                username: <username>
+                password: <password>
+                """
+            When the user logs in
+            Then the response should contain:
+                | field     | value      |
+                | username  | <username> |
+                | logged_in | true       |
+
+            Examples:
+            | username  | password  |
+            | user1     | pass123   |
+            | user2     | 123secure |
+
+.. code-block:: python
+
+    from pytest_bdd import scenarios, given, when, then
+    import json
+
+    # Load scenarios from the feature file
+    scenarios("docstring_and_datatable_with_params.feature")
+
+
+    @given("the following configuration:")
+    def given_user_config(docstring):
+        print(docstring)
+
+
+    @when("the user logs in")
+    def user_logs_in(logged_in):
+        logged_in = True
+
+
+    @then("the response should contain:")
+    def response_should_contain(datatable):
+        assert datatable[1][1] in ["user1", "user2"]
+
+
 Rules
 -----
 

src/pytest_bdd/parser.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 import os.path
 import re
 import textwrap
@@ -20,7 +21,28 @@
 from .gherkin_parser import get_gherkin_document
 from .types import STEP_TYPE_BY_PARSER_KEYWORD
 
-STEP_PARAM_RE = re.compile(r"<(.+?)>")
+PARAM_RE = re.compile(r"<(.+?)>")
+
+
+def render_string(input_string: str, render_context: Mapping[str, object]) -> str:
+    """
+    Render the string with the given context,
+    but avoid replacing text inside angle brackets if context is missing.
+
+    Args:
+        input_string (str): The string for which to render/replace params.
+        render_context (Mapping[str, object]): The context for rendering the string.
+
+    Returns:
+        str: The rendered string with parameters replaced only if they exist in the context.
+    """
+
+    def replacer(m: re.Match) -> str:
+        varname = m.group(1)
+        # If the context contains the variable, replace it. Otherwise, leave it unchanged.
+        return str(render_context.get(varname, f"<{varname}>"))
+
+    return PARAM_RE.sub(replacer, input_string)
 
 
 def get_tag_names(tag_data: list[GherkinTag]) -> set[str]:
@@ -189,25 +211,25 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
         Returns:
             Scenario: A Scenario object with steps rendered based on the context.
         """
+        base_steps = self.all_background_steps + self._steps
         scenario_steps = [
             Step(
-                name=step.render(context),
+                name=render_string(step.name, context),
                 type=step.type,
                 indent=step.indent,
                 line_number=step.line_number,
                 keyword=step.keyword,
-                datatable=step.datatable,
-                docstring=step.docstring,
+                datatable=step.render_datatable(step.datatable, context) if step.datatable else None,
+                docstring=render_string(step.docstring, context) if step.docstring else None,
             )
-            for step in self._steps
+            for step in base_steps
         ]
-        steps = self.all_background_steps + scenario_steps
         return Scenario(
             feature=self.feature,
             keyword=self.keyword,
-            name=self.name,
+            name=render_string(self.name, context),
             line_number=self.line_number,
-            steps=steps,
+            steps=scenario_steps,
             tags=self.tags,
             description=self.description,
             rule=self.rule,
@@ -299,31 +321,24 @@ def __str__(self) -> str:
         """
         return f'{self.type.capitalize()} "{self.name}"'
 
-    @property
-    def params(self) -> tuple[str, ...]:
-        """Get the parameters in the step name.
-
-        Returns:
-            Tuple[str, ...]: A tuple of parameter names found in the step name.
+    @staticmethod
+    def render_datatable(datatable: DataTable, context: Mapping[str, object]) -> DataTable:
         """
-        return tuple(frozenset(STEP_PARAM_RE.findall(self.name)))
-
-    def render(self, context: Mapping[str, Any]) -> str:
-        """Render the step name with the given context, but avoid replacing text inside angle brackets if context is missing.
+        Render the datatable with the given context,
+        but avoid replacing text inside angle brackets if context is missing.
 
         Args:
-            context (Mapping[str, Any]): The context for rendering the step name.
+            datatable (DataTable): The datatable to render.
+            context (Mapping[str, Any]): The context for rendering the datatable.
 
         Returns:
-            str: The rendered step name with parameters replaced only if they exist in the context.
+            datatable (DataTable): The rendered datatable with parameters replaced only if they exist in the context.
         """
-
-        def replacer(m: re.Match) -> str:
-            varname = m.group(1)
-            # If the context contains the variable, replace it. Otherwise, leave it unchanged.
-            return str(context.get(varname, f"<{varname}>"))
-
-        return STEP_PARAM_RE.sub(replacer, self.name)
+        rendered_datatable = copy.deepcopy(datatable)
+        for row in rendered_datatable.rows:
+            for cell in row.cells:
+                cell.value = render_string(cell.value, context)
+        return rendered_datatable
 
 
 @dataclass(eq=False)

tests/feature/test_scenario.py

@@ -199,6 +199,93 @@ def _():
     result.assert_outcomes(passed=2)
 
 
+def test_example_params(pytester):
+    """Test example params are rendered where necessary:
+    * Step names
+    * Docstring
+    * Datatables
+    """
+    pytester.makefile(
+        ".feature",
+        example_params='''
+        Feature: Example params
+            Background:
+                Given I have a background <background>
+                And my background has:
+                """
+                Background <background>
+                """
+
+                Scenario Outline: Outlined scenario
+                    Given I have a templated <foo>
+                    When I have a templated datatable
+                        | <data>  |
+                        | example |
+                    And I have a templated docstring
+                    """
+                    This is a <doc>
+                    """
+                    Then pass
+
+                Examples:
+                    | background | foo | data  | doc    |
+                    | parameter  | bar | table | string |
+        ''',
+    )
+    pytester.makepyfile(
+        """
+        from pytest_bdd import scenarios, given, when, then, parsers
+        from pytest_bdd.utils import dump_obj
+
+        scenarios("example_params.feature")
+
+
+        @given(parsers.parse("I have a background {background}"))
+        def _(background):
+            return dump_obj(("background", background))
+
+
+        @given(parsers.parse("I have a templated {foo}"))
+        def _(foo):
+            return "foo"
+
+
+        @given("my background has:")
+        def _(docstring):
+            return dump_obj(("background_docstring", docstring))
+
+
+        @given("I have a rule table:")
+        def _(datatable):
+            return dump_obj(("rule", datatable))
+
+
+        @when("I have a templated datatable")
+        def _(datatable):
+            return dump_obj(("datatable", datatable))
+
+
+        @when("I have a templated docstring")
+        def _(docstring):
+            return dump_obj(("docstring", docstring))
+
+
+        @then("pass")
+        def _():
+            pass
+        """
+    )
+    result = pytester.runpytest("-s")
+    result.assert_outcomes(passed=1)
+
+    assert collect_dumped_objects(result) == [
+        ("background", "parameter"),
+        ("background_docstring", "Background parameter"),
+        ("datatable", [["table"], ["example"]]),
+        ("docstring", "This is a string"),
+    ]
+
+
 def test_multilanguage_support(pytester):
     """Test multilanguage support."""
     pytester.makefile(