Add rule feature

CHANGES.rst

@@ -6,6 +6,7 @@ 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).
+- Rule keyword can be used in feature files (see `Rule <https://cucumber.io/docs/gherkin/reference/#rule>`)
 
 8.0.0b2
 ----------

README.rst

@@ -513,6 +513,43 @@ 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
+
+In Gherkin, `Scenario` and `Example` are interchangeable.
+You can use either keyword to define individual test cases.
+For example, the previous rule could have been written with the `Scenario` keyword instead of `Example`,
+and the behaviour would remain the same.
+
 
 Datatables
 ----------

src/pytest_bdd/generation.py

@@ -11,6 +11,7 @@
 
 from .compat import getfixturedefs
 from .feature import get_features
+from .parser import Feature, Rule
 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,7 @@
     from _pytest.main import Session
     from _pytest.python import Function
 
-    from .parser import Feature, ScenarioTemplate, Step
+    from .parser import ScenarioTemplate, Step
 
 template_lookup = TemplateLookup(directories=[os.path.join(os.path.dirname(__file__), "templates")])
 
@@ -88,8 +89,10 @@
     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 +103,34 @@
         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,
-            )
+            feature_or_rule = step.background.parent
+            if isinstance(feature_or_rule, Feature):
+                tw.line(
+                    (
+                        f"Step {step} is not defined in the background of the feature "
+                        f'"{feature_or_rule.name}" in the file '
+                        f"{feature_or_rule.filename}:{step.line_number}"
+                    ),
+                    red=True,
+                )
+            elif isinstance(feature_or_rule, Rule):
+                _feature: Feature = feature_or_rule.feature
+                tw.line(
+                    (
+                        f"Step {step} is not defined in the background of the rule "
+                        f'"{feature_or_rule.name}" in the file '
+                        f"{_feature.filename}:{step.line_number}"
+                    ),
+                    red=True,
+                )
 
     if step:
         tw.sep("-", red=True)

src/pytest_bdd/gherkin_terminal_reporter.py

@@ -12,6 +12,14 @@
     from _pytest.reports import TestReport
 
 
+INDENT_UNIT = "  "
+
+
+def get_indent(level: int) -> str:
+    """Get the indentation for a given level."""
+    return INDENT_UNIT * level
+
+
 def add_options(parser: Parser) -> None:
     group = parser.getgroup("terminal reporting", "reporting", after="general")
     group._addoption(
@@ -56,42 +64,77 @@
             # probably passed setup/teardown
             return None
 
-        if isinstance(word, tuple):
-            word, word_markup = word
-        elif rep.passed:
-            word_markup = {"green": True}
-        elif rep.failed:
-            word_markup = {"red": True}
-        elif rep.skipped:
-            word_markup = {"yellow": True}
-        feature_markup = {"blue": True}
-        scenario_markup = word_markup
+        # Determine color markup based on test outcome
+        word_markup = self._get_markup_for_result(report)
 
         if self.verbosity <= 0 or not hasattr(report, "scenario"):
             return super().pytest_runtest_logreport(rep)
 
+        feature_markup = {"blue": True}
+        scenario_markup = word_markup
+
+        self.ensure_newline()
+
         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)
-            self._tw.write(report.scenario["name"], **scenario_markup)
-            self._tw.write(" ")
-            self._tw.write(word, **word_markup)
-            self._tw.write("\n")
+            self._print_summary_report(report, word, feature_markup, scenario_markup, word_markup)
         elif 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)
-            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("\n\n")
-
-        self.stats.setdefault(cat, []).append(rep)
+            self._print_detailed_report(report, word, feature_markup, scenario_markup, word_markup)
+
+        self.stats.setdefault(cat, []).append(report)
         return None
+
+    @staticmethod
+    def _get_markup_for_result(report: TestReport) -> dict[str, bool]:
+        """Get color markup based on test result."""
+        if report.passed:
+            return {"green": True}
+        elif report.failed:
+            return {"red": True}
+        elif report.skipped:
+            return {"yellow": True}
+        return {}
+
+    def _print_summary_report(
+        self, report: TestReport, word: str, feature_markup: dict, scenario_markup: dict, word_markup: dict
+    ) -> None:
+        """Print a summary-style Gherkin report for a test."""
+        base_indent = self._get_indent_for_scenario(report)
+
+        self._tw.write(f"{report.scenario['feature']['keyword']}: ", **feature_markup)
+        self._tw.write(report.scenario["feature"]["name"], **feature_markup)
+        self._tw.write("\n")
+
+        if "rule" in report.scenario:
+            self._tw.write(f"{base_indent}{report.scenario['rule']['keyword']}: {report.scenario['rule']['name']}\n")
+
+        self._tw.write(f"{base_indent}{get_indent(1)}{report.scenario['keyword']}: ", **scenario_markup)
+        self._tw.write(report.scenario["name"], **scenario_markup)
+        self._tw.write(f" {word}\n", **word_markup)
+
+    def _print_detailed_report(
+        self, report: TestReport, word: str, feature_markup: dict, scenario_markup: dict, word_markup: dict
+    ) -> None:
+        """Print a detailed Gherkin report for a test."""
+        base_indent = self._get_indent_for_scenario(report)
+
+        self._tw.write(f"{report.scenario['feature']['keyword']}: ", **feature_markup)
+        self._tw.write(report.scenario["feature"]["name"], **feature_markup)
+        self._tw.write("\n")
+
+        if "rule" in report.scenario:
+            self._tw.write(f"{base_indent}{report.scenario['rule']['keyword']}: {report.scenario['rule']['name']}\n")
+
+        self._tw.write(f"{base_indent}{get_indent(1)}{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"{base_indent}{get_indent(2)}{step['keyword']} {step['name']}\n", **scenario_markup)
+
+        self._tw.write(f"{word}\n", **word_markup)
+        self._tw.write("\n")
+
+    @staticmethod
+    def _get_indent_for_scenario(report: TestReport) -> str:
+        """Get the correct indentation based on whether a rule exists."""
+        return get_indent(2) if "rule" in report.scenario else get_indent(1)