Merge pull request #712 from jsa34/datatables

Datatables

Author: youtux

CHANGES.rst

@@ -6,6 +6,7 @@ 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.
 
 8.0.0b1
 ----------

README.rst

@@ -433,20 +433,21 @@ Multiline steps
 
 As Gherkin, pytest-bdd supports multiline steps
 (a.k.a. `Doc Strings <https://cucumber.io/docs/gherkin/reference/#doc-strings>`_).
-But in much cleaner and powerful way:
 
 .. 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 it's first line is indented relatively
-to the first line. The step name is then simply extended by adding further lines with newlines.
+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
@@ -560,6 +561,98 @@ Example:
         assert cucumbers["start"] - cucumbers["eat"] == left
 
 
+Step Definitions and Accessing the Datatable
+--------------------------------------------
+
+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,
+enabling you to manage and manipulate this data conveniently.
+
+When you use the ``datatable`` argument in a step definition, it will return the table as a list of lists,
+where each inner list represents a row from the table.
+
+For example, the Gherkin table:
+
+.. code-block:: gherkin
+
+    | name  | email            |
+    | John  | john@example.com |
+
+Will be returned by the ``datatable`` argument as:
+
+.. code-block:: python
+
+    [
+        ["name", "email"],
+        ["John", "john@example.com"]
+    ]
+
+.. NOTE:: When using the datatable argument, it is essential to ensure that the step to which it is applied
+          actually has an associated data table. If the step does not have an associated data table,
+          attempting to use the datatable argument will raise an error.
+          Make sure that your Gherkin steps correctly reference the data table when defined.
+
+Full example:
+
+.. code-block:: gherkin
+
+    Feature: Manage user accounts
+
+      Scenario: Creating a new user with roles and permissions
+        Given the following user details:
+          | name  | email             | age |
+          | John  | john@example.com  | 30  |
+          | Alice | alice@example.com | 25  |
+
+        When each user is assigned the following roles:
+          | Admin       | Full access to the system |
+          | Contributor | Can add content           |
+
+        And the page is saved
+
+        Then the user should have the following permissions:
+          | permission     | allowed |
+          | view dashboard | true    |
+          | edit content   | true    |
+          | delete content | false   |
+
+.. code-block:: python
+
+    from pytest_bdd import given, when, then
+
+
+    @given("the following user details:", target_fixture="users")
+    def _(datatable):
+        users = []
+        for row in datatable[1:]:
+            users.append(row)
+
+        print(users)
+        return users
+
+
+    @when("each user is assigned the following roles:")
+    def _(datatable, users):
+        roles = datatable
+        for user in users:
+            for role_row in datatable:
+                assign_role(user, role_row)
+
+
+    @when("the page is saved")
+    def _():
+        save_page()
+
+
+    @then("the user should have the following permissions:")
+    def _(datatable, users):
+        expected_permissions = []
+        for row in datatable[1:]:
+            expected_permissions.append(row)
+
+        assert users_have_correct_permissions(users, expected_permissions)
+
+
 Organizing your scenarios
 -------------------------
 
@@ -1065,7 +1158,7 @@ which might be helpful building useful reporting, visualization, etc. on top of
   (even if one of steps has failed)
 
 * `pytest_bdd_before_step(request, feature, scenario, step, step_func)` - Called before step function
-  is executed and it's arguments evaluated
+  is executed and its arguments evaluated
 
 * `pytest_bdd_before_step_call(request, feature, scenario, step, step_func, step_func_args)` - Called before step
   function is executed with evaluated arguments

src/pytest_bdd/gherkin_parser.py

@@ -4,6 +4,7 @@
 import re
 import textwrap
 import typing
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -101,21 +102,36 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 
 
 @dataclass
-class DataTable:
+class ExamplesTable:
     location: Location
     name: str | None = None
-    tableHeader: Row | None = None
-    tableBody: list[Row] | None = field(default_factory=list)
+    table_header: Row | None = None
+    table_body: list[Row] | None = field(default_factory=list)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
             location=Location.from_dict(data["location"]),
             name=data.get("name"),
-            tableHeader=Row.from_dict(data["tableHeader"]) if data.get("tableHeader") else None,
-            tableBody=[Row.from_dict(row) for row in data.get("tableBody", [])],
+            table_header=Row.from_dict(data["tableHeader"]) if data.get("tableHeader") else None,
+            table_body=[Row.from_dict(row) for row in data.get("tableBody", [])],
+        )
+
+
+@dataclass
+class DataTable:
+    location: Location
+    rows: list[Row]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Self:
+        return cls(
+            location=Location.from_dict(data["location"]), rows=[Row.from_dict(row) for row in data.get("rows", [])]
         )
 
+    def raw(self) -> Sequence[Sequence[object]]:
+        return [[cell.value for cell in row.cells] for row in self.rows]
+
 
 @dataclass
 class DocString:
@@ -135,23 +151,23 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 @dataclass
 class Step:
     id: str
-    keyword: str
-    keywordType: str
     location: Location
+    keyword: str
+    keyword_type: str
     text: str
-    dataTable: DataTable | None = None
-    docString: DocString | None = None
+    datatable: DataTable | None = None
+    docstring: DocString | None = None
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
             id=data["id"],
-            keyword=data["keyword"].strip(),
-            keywordType=data["keywordType"],
             location=Location.from_dict(data["location"]),
+            keyword=data["keyword"].strip(),
+            keyword_type=data["keywordType"],
             text=data["text"],
-            dataTable=DataTable.from_dict(data["dataTable"]) if data.get("dataTable") else None,
-            docString=DocString.from_dict(data["docString"]) if data.get("docString") else None,
+            datatable=DataTable.from_dict(data["dataTable"]) if data.get("dataTable") else None,
+            docstring=DocString.from_dict(data["docString"]) if data.get("docString") else None,
         )
 
 
@@ -169,33 +185,33 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 @dataclass
 class Scenario:
     id: str
-    keyword: str
     location: Location
+    keyword: str
     name: str
     description: str
     steps: list[Step]
     tags: list[Tag]
-    examples: list[DataTable] = field(default_factory=list)
+    examples: list[ExamplesTable] = field(default_factory=list)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
             id=data["id"],
-            keyword=data["keyword"],
             location=Location.from_dict(data["location"]),
+            keyword=data["keyword"],
             name=data["name"],
             description=data["description"],
             steps=[Step.from_dict(step) for step in data["steps"]],
             tags=[Tag.from_dict(tag) for tag in data["tags"]],
-            examples=[DataTable.from_dict(example) for example in data["examples"]],
+            examples=[ExamplesTable.from_dict(example) for example in data["examples"]],
         )
 
 
 @dataclass
 class Rule:
     id: str
-    keyword: str
     location: Location
+    keyword: str
     name: str
     description: str
     tags: list[Tag]
@@ -205,8 +221,8 @@ class Rule:
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
             id=data["id"],
-            keyword=data["keyword"],
             location=Location.from_dict(data["location"]),
+            keyword=data["keyword"],
             name=data["name"],
             description=data["description"],
             tags=[Tag.from_dict(tag) for tag in data["tags"]],
@@ -217,8 +233,8 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 @dataclass
 class Background:
     id: str
-    keyword: str
     location: Location
+    keyword: str
     name: str
     description: str
     steps: list[Step]
@@ -227,8 +243,8 @@ class Background:
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
             id=data["id"],
-            keyword=data["keyword"],
             location=Location.from_dict(data["location"]),
+            keyword=data["keyword"],
             name=data["name"],
             description=data["description"],
             steps=[Step.from_dict(step) for step in data["steps"]],
@@ -252,8 +268,8 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 
 @dataclass
 class Feature:
-    keyword: str
     location: Location
+    keyword: str
     tags: list[Tag]
     name: str
     description: str
@@ -262,8 +278,8 @@ class Feature:
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Self:
         return cls(
-            keyword=data["keyword"],
             location=Location.from_dict(data["location"]),
+            keyword=data["keyword"],
             tags=[Tag.from_dict(tag) for tag in data["tags"]],
             name=data["name"],
             description=data["description"],

src/pytest_bdd/parser.py

@@ -9,6 +9,7 @@
 
 from .exceptions import StepError
 from .gherkin_parser import Background as GherkinBackground
+from .gherkin_parser import DataTable, ExamplesTable
 from .gherkin_parser import Feature as GherkinFeature
 from .gherkin_parser import GherkinDocument
 from .gherkin_parser import Scenario as GherkinScenario
@@ -170,6 +171,7 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
                 indent=step.indent,
                 line_number=step.line_number,
                 keyword=step.keyword,
+                datatable=step.datatable,
             )
             for step in self._steps
         ]
@@ -225,11 +227,14 @@ class Step:
     line_number: int
     indent: int
     keyword: str
+    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) -> None:
+    def __init__(
+        self, name: str, type: str, indent: int, line_number: int, keyword: str, datatable: DataTable | None = None
+    ) -> None:
         """Initialize a step.
 
         Args:
@@ -244,6 +249,7 @@ def __init__(self, name: str, type: str, indent: int, line_number: int, keyword:
         self.indent = indent
         self.line_number = line_number
         self.keyword = keyword
+        self.datatable = datatable
 
     def __str__(self) -> str:
         """Return a string representation of the step.
@@ -342,8 +348,8 @@ def parse_steps(self, steps_data: list[GherkinStep]) -> list[Step]:
 
         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}"
+            if _gherkin_step.docstring:
+                step_name = f"{step_name}\n{_gherkin_step.docstring.content}"
             return step_name
 
         if not steps_data:
@@ -372,6 +378,7 @@ def get_step_content(_gherkin_step: GherkinStep) -> str:
                     indent=step.location.column - 1,
                     line_number=step.location.line,
                     keyword=step.keyword.title(),
+                    datatable=step.datatable,
                 )
             )
         return steps
@@ -403,11 +410,11 @@ def parse_scenario(self, scenario_data: GherkinScenario, feature: Feature) -> Sc
                 line_number=example_data.location.line,
                 name=example_data.name,
             )
-            if example_data.tableHeader is not None:
-                param_names = [cell.value for cell in example_data.tableHeader.cells]
+            if example_data.table_header is not None:
+                param_names = [cell.value for cell in example_data.table_header.cells]
                 examples.set_param_names(param_names)
-                if example_data.tableBody is not None:
-                    for row in example_data.tableBody:
+                if example_data.table_body is not None:
+                    for row in example_data.table_body:
                         values = [cell.value or "" for cell in row.cells]
                         examples.add_example(values)
                     scenario.examples = examples