Merge branch 'master' into master

Author: jsa34

CHANGES.rst

@@ -1,30 +1,92 @@
 Changelog
 =========
 
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`_,
+and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
+
 Unreleased
 ----------
-- Dropped support for python 3.8. Supported python versions: 3.9, 3.10, 3.11, 3.12, 3.13.
-- Text after the `#` character is no longer stripped from the Scenario and Feature name.
-- Gherkin keyword aliases can now be used and correctly reported in json and terminal output (see `Keywords <https://cucumber.io/docs/gherkin/reference/#keywords>` for permitted list).
-- Added localization support. The language of the feature file can be specified using the `# language: <language>` directive at the beginning of the file.
+
+Added
++++++
+
+Changed
++++++++
+
+Deprecated
+++++++++++
+
+Removed
++++++++
+
+Fixed
++++++
+
+Security
+++++++++
+
+
+[8.0.0] - 2024-11-14
+----------
+
+Added
++++++
+* Gherkin keyword aliases can now be used and correctly reported in json and terminal output (see `Keywords <https://cucumber.io/docs/gherkin/reference/#keywords>`_ for permitted list).
+* Added localization support. The language of the feature file can be specified using the `# language: <language>` directive at the beginning of the file.
+* Rule keyword can be used in feature files (see `Rule <https://cucumber.io/docs/gherkin/reference/#rule>`_)
+* Added support for multiple example tables
+* Added filtering by tags against example tables
+* Since the 7.x series:
+  * Tags can now be on multiple lines (stacked)
+  * Continuation of steps using asterisks (``*``) instead of ``And``/``But`` supported.
+  * 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>`_).
+
+Changed
++++++++
+* Changelog format updated to follow `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`_.
+* Text after the ``#`` character is no longer stripped from the Scenario and Feature name.
+* Since the 7.x series:
+
+  * Use the `gherkin-official <https://pypi.org/project/gherkin-official/>`_ parser, replacing the custom parsing logic. This will make pytest-bdd more compatible with the Gherkin specification.
+  * Multiline steps must now always use triple-quotes for the additional lines.
+  * All feature files must now use the keyword ``Feature:`` to be considered valid.
+  * Tags can no longer have spaces (e.g. ``@tag one`` and ``@tag two`` are no longer valid).
+  * Text after the ``#`` character is no longer stripped from the Step name.
+  * Multiline strings no longer match name based on multiple lines - only on the actual step text on the step line.
+
+Removed
++++++++
+* Dropped support for python 3.8. Supported python versions: 3.9, 3.10, 3.11, 3.12, 3.13.
+* Since the 7.x series:
+
+  * Drop compatibility with pytest < 7.0.0.
+
+Fixed
++++++
+* Since the 7.x series:
+
+  * Updated documentation to clarify that ``--gherkin-terminal-reporter`` needs to be used with ``-v`` or ``-vv``.
 
 8.0.0b2
 ----------
-- 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 (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.
+* Updated 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 (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
 ----------
-- Use `gherkin-official` parser to replace custom parsing logic. This will make pytest-bdd more compatible with the Gherkin specification.
-- Multiline steps must now always use triple-quotes for the additional lines.
-- All feature files must now use the keyword `Feature:` to be considered valid.
-- Tags can no longer have spaces (e.g. "@tag one" and "@tag two" are no longer valid).
-- Tags can now be on multiple lines (stacked)
-- Text after the `#` character is no longer stripped from the Step name.
+* Use the `gherkin-official <https://pypi.org/project/gherkin-official/>`_ parser, replacing the custom parsing logic. This will make pytest-bdd more compatible with the Gherkin specification.
+* Multiline steps must now always use triple-quotes for the additional lines.
+* All feature files must now use the keyword ``Feature:`` to be considered valid.
+* Tags can no longer have spaces (e.g. ``@tag one`` and ``@tag two`` are no longer valid).
+* Tags can now be on multiple lines (stacked)
+* Text after the ``#`` character is no longer stripped from the Step name.
 
 7.3.0
 ----------

README.rst

@@ -513,6 +513,103 @@ Example:
     def should_have_left_cucumbers(cucumbers, left):
         assert cucumbers["start"] - cucumbers["eat"] == left
 
+Rules
+-----
+
+In Gherkin, `Rules` allow you to group related scenarios or examples under a shared context.
+This is useful when you want to define different conditions or behaviours
+for multiple examples that follow a similar structure.
+You can use either ``Scenario`` or ``Example`` to define individual cases, as they are aliases and function identically.
+
+Additionally, **tags** applied to a rule will be automatically applied to all the **examples or scenarios**
+under that rule, making it easier to organize and filter tests during execution.
+
+Example:
+
+.. code-block:: gherkin
+
+    Feature: Rules and examples
+
+        @feature_tag
+        Rule: A rule for valid cases
+
+            @rule_tag
+            Example: Valid case 1
+                Given I have a valid input
+                When I process the input
+                Then the result should be successful
+
+        Rule: A rule for invalid cases
+            Example: Invalid case
+                Given I have an invalid input
+                When I process the input
+                Then the result should be an error
+
+
+Scenario Outlines with Multiple Example Tables
+----------------------------------------------
+
+In `pytest-bdd`, you can use multiple example tables in a scenario outline to test
+different sets of input data under various conditions.
+You can define separate `Examples` blocks, each with its own table of data,
+and optionally tag them to differentiate between positive, negative, or any other conditions.
+
+Example:
+
+.. code-block:: gherkin
+
+    # content of scenario_outline.feature
+
+    Feature: Scenario outlines with multiple examples tables
+        Scenario Outline: Outlined with multiple example tables
+            Given there are <start> cucumbers
+            When I eat <eat> cucumbers
+            Then I should have <left> cucumbers
+
+            @positive
+            Examples: Positive results
+                | start | eat | left |
+                |  12   |  5  |  7   |
+                |  5    |  4  |  1   |
+
+            @negative
+            Examples: Impossible negative results
+                | start | eat | left |
+                |  3    |  9  |  -6  |
+                |  1    |  4  |  -3  |
+
+.. code-block:: python
+
+    from pytest_bdd import scenarios, given, when, then, parsers
+
+
+    scenarios("scenario_outline.feature")
+
+
+    @given(parsers.parse("there are {start:d} cucumbers"), target_fixture="cucumbers")
+    def given_cucumbers(start):
+        return {"start": start, "eat": 0}
+
+
+    @when(parsers.parse("I eat {eat:d} cucumbers"))
+    def eat_cucumbers(cucumbers, eat):
+        cucumbers["eat"] += eat
+
+
+    @then(parsers.parse("I should have {left:d} cucumbers"))
+    def should_have_left_cucumbers(cucumbers, left):
+        assert cucumbers["start"] - cucumbers["eat"] == left
+
+
+When you filter scenarios by a tag, only the examples associated with that tag will be executed.
+This allows you to run a specific subset of your test cases based on the tag.
+For example, in the following scenario outline, if you filter by the @positive tag,
+only the examples under the "Positive results" table will be executed, and the "Negative results" table will be ignored.
+
+.. code-block:: bash
+
+    pytest -k "positive"
+
 
 Datatables
 ----------

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pytest-bdd"
-version = "8.0.0b2"
+version = "8.0.0"
 description = "BDD for pytest"
 authors = ["Oleg Pidsadnyi <[email protected]>", "Anatoly Bubenkov <[email protected]>"]
 maintainers = ["Alessio Bogon <[email protected]>"]

src/pytest_bdd/generation.py

@@ -11,6 +11,7 @@
 
 from .compat import getfixturedefs
 from .feature import get_features
+from .parser import Feature, ScenarioTemplate, Step
 from .scenario import inject_fixturedefs_for_step, make_python_docstring, make_python_name, make_string_literal
 from .steps import get_step_fixture_name
 from .types import STEP_TYPES
@@ -25,7 +26,6 @@
     from _pytest.main import Session
     from _pytest.python import Function
 
-    from .parser import Feature, ScenarioTemplate, Step
 
 template_lookup = TemplateLookup(directories=[os.path.join(os.path.dirname(__file__), "templates")])
 
@@ -88,8 +88,10 @@ def print_missing_code(scenarios: list[ScenarioTemplate], steps: list[Step]) ->
     for scenario in scenarios:
         tw.line()
         tw.line(
-            'Scenario "{scenario.name}" is not bound to any test in the feature "{scenario.feature.name}"'
-            " in the file {scenario.feature.filename}:{scenario.line_number}".format(scenario=scenario),
+            (
+                f'Scenario "{scenario.name}" is not bound to any test in the feature "{scenario.feature.name}" '
+                f"in the file {scenario.feature.filename}:{scenario.line_number}"
+            ),
             red=True,
         )
 
@@ -100,18 +102,16 @@ def print_missing_code(scenarios: list[ScenarioTemplate], steps: list[Step]) ->
         tw.line()
         if step.scenario is not None:
             tw.line(
-                """Step {step} is not defined in the scenario "{step.scenario.name}" in the feature"""
-                """ "{step.scenario.feature.name}" in the file"""
-                """ {step.scenario.feature.filename}:{step.line_number}""".format(step=step),
+                (
+                    f'Step {step} is not defined in the scenario "{step.scenario.name}" '
+                    f'in the feature "{step.scenario.feature.name}" in the file '
+                    f"{step.scenario.feature.filename}:{step.line_number}"
+                ),
                 red=True,
             )
         elif step.background is not None:
-            tw.line(
-                """Step {step} is not defined in the background of the feature"""
-                """ "{step.background.feature.name}" in the file"""
-                """ {step.background.feature.filename}:{step.line_number}""".format(step=step),
-                red=True,
-            )
+            message = f"Background step {step} is not defined."
+            tw.line(message, red=True)
 
     if step:
         tw.sep("-", red=True)

src/pytest_bdd/gherkin_parser.py

@@ -104,6 +104,7 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
 @dataclass
 class ExamplesTable:
     location: Location
+    tags: list[Tag]
     name: str | None = None
     table_header: Row | None = None
     table_body: list[Row] | None = field(default_factory=list)
@@ -115,6 +116,7 @@ def from_dict(cls, data: dict[str, Any]) -> Self:
             name=data.get("name"),
             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", [])],
+            tags=[Tag.from_dict(tag) for tag in data["tags"]],
         )
 
 

src/pytest_bdd/gherkin_terminal_reporter.py

@@ -46,6 +46,7 @@ def configure(config: Config) -> None:
 class GherkinTerminalReporter(TerminalReporter):  # type: ignore
     def __init__(self, config: Config) -> None:
         super().__init__(config)
+        self.current_rule = None
 
     def pytest_runtest_logreport(self, report: TestReport) -> Any:
         rep = report
@@ -66,16 +67,27 @@ def pytest_runtest_logreport(self, report: TestReport) -> Any:
             word_markup = {"yellow": True}
         feature_markup = {"blue": True}
         scenario_markup = word_markup
+        rule_markup = {"purple": True}
 
         if self.verbosity <= 0 or not hasattr(report, "scenario"):
             return super().pytest_runtest_logreport(rep)
 
+        rule = report.scenario.get("rule")
+        indent = "    " if rule else ""
+
         if self.verbosity == 1:
             self.ensure_newline()
             self._tw.write(f"{report.scenario['feature']['keyword']}: ", **feature_markup)
             self._tw.write(report.scenario["feature"]["name"], **feature_markup)
             self._tw.write("\n")
-            self._tw.write(f"    {report.scenario['keyword']}: ", **scenario_markup)
+
+            if rule and rule["name"] != self.current_rule:
+                self._tw.write(f"  {rule['keyword']}: ", **rule_markup)
+                self._tw.write(rule["name"], **rule_markup)
+                self._tw.write("\n")
+                self.current_rule = rule["name"]
+
+            self._tw.write(f"{indent}    {report.scenario['keyword']}: ", **scenario_markup)
             self._tw.write(report.scenario["name"], **scenario_markup)
             self._tw.write(" ")
             self._tw.write(word, **word_markup)
@@ -85,12 +97,19 @@ def pytest_runtest_logreport(self, report: TestReport) -> Any:
             self._tw.write(f"{report.scenario['feature']['keyword']}: ", **feature_markup)
             self._tw.write(report.scenario["feature"]["name"], **feature_markup)
             self._tw.write("\n")
-            self._tw.write(f"    {report.scenario['keyword']}: ", **scenario_markup)
+
+            if rule and rule["name"] != self.current_rule:
+                self._tw.write(f"  {rule['keyword']}: ", **rule_markup)
+                self._tw.write(rule["name"], **rule_markup)
+                self._tw.write("\n")
+                self.current_rule = rule["name"]
+
+            self._tw.write(f"{indent}    {report.scenario['keyword']}: ", **scenario_markup)
             self._tw.write(report.scenario["name"], **scenario_markup)
             self._tw.write("\n")
             for step in report.scenario["steps"]:
-                self._tw.write(f"        {step['keyword']} {step['name']}\n", **scenario_markup)
-            self._tw.write(f"    {word}", **word_markup)
+                self._tw.write(f"{indent}        {step['keyword']} {step['name']}\n", **scenario_markup)
+            self._tw.write(f"{indent}    {word}", **word_markup)
             self._tw.write("\n\n")
 
         self.stats.setdefault(cat, []).append(rep)