Merge pull request #728 from jsa34/add-rule

Author: youtux

CHANGES.rst

@@ -7,6 +7,7 @@ Unreleased
 - 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.
+- Rule keyword can be used in feature files (see `Rule <https://cucumber.io/docs/gherkin/reference/#rule>`)
 - Multiple example tables supported
 - Added filtering by tags against example tables
 

README.rst

@@ -513,6 +513,38 @@ 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
 ----------------------------------------------

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_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)

src/pytest_bdd/parser.py

@@ -4,7 +4,7 @@
 import re
 import textwrap
 from collections import OrderedDict
-from collections.abc import Iterable, Mapping, Sequence
+from collections.abc import Generator, Iterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -13,6 +13,7 @@
 from .gherkin_parser import DataTable
 from .gherkin_parser import Feature as GherkinFeature
 from .gherkin_parser import GherkinDocument
+from .gherkin_parser import Rule as GherkinRule
 from .gherkin_parser import Scenario as GherkinScenario
 from .gherkin_parser import Step as GherkinStep
 from .gherkin_parser import Tag as GherkinTag
@@ -113,6 +114,15 @@ def __bool__(self) -> bool:
         return bool(self.examples)
 
 
+@dataclass(eq=False)
+class Rule:
+    keyword: str
+    name: str
+    description: str
+    tags: set[str]
+    background: Background | None = None
+
+
 @dataclass(eq=False)
 class ScenarioTemplate:
     """Represents a scenario template within a feature.
@@ -127,6 +137,7 @@ class ScenarioTemplate:
         tags (set[str]): A set of tags associated with the scenario.
         _steps (List[Step]): The list of steps in the scenario (internal use only).
         examples (Optional[Examples]): The examples used for parameterization in the scenario.
+        rule (Optional[Rule]): The rule to which the scenario may belong (None = no rule).
     """
 
     feature: Feature
@@ -138,6 +149,7 @@ class ScenarioTemplate:
     tags: set[str] = field(default_factory=set)
     _steps: list[Step] = field(init=False, default_factory=list)
     examples: list[Examples] = field(default_factory=list[Examples])
+    rule: Rule | None = None
 
     def add_step(self, step: Step) -> None:
         """Add a step to the scenario.
@@ -148,14 +160,25 @@ def add_step(self, step: Step) -> None:
         step.scenario = self
         self._steps.append(step)
 
+    @property
+    def all_background_steps(self) -> list[Step]:
+        steps = []
+        # Add background steps from the feature
+        if self.feature.background:
+            steps.extend(self.feature.background.steps)
+        if self.rule is not None and self.rule.background is not None:
+            # Add background steps from the rule
+            steps.extend(self.rule.background.steps)
+        return steps
+
     @property
     def steps(self) -> list[Step]:
         """Get all steps for the scenario, including background steps.
 
         Returns:
             List[Step]: A list of steps, including any background steps from the feature.
         """
-        return (self.feature.background.steps if self.feature.background else []) + self._steps
+        return self.all_background_steps + self._steps
 
     def render(self, context: Mapping[str, Any]) -> Scenario:
         """Render the scenario with the given context.
@@ -166,7 +189,6 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
         Returns:
             Scenario: A Scenario object with steps rendered based on the context.
         """
-        background_steps = self.feature.background.steps if self.feature.background else []
         scenario_steps = [
             Step(
                 name=step.render(context),
@@ -179,7 +201,7 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
             )
             for step in self._steps
         ]
-        steps = background_steps + scenario_steps
+        steps = self.all_background_steps + scenario_steps
         return Scenario(
             feature=self.feature,
             keyword=self.keyword,
@@ -188,6 +210,7 @@ def render(self, context: Mapping[str, Any]) -> Scenario:
             steps=steps,
             tags=self.tags,
             description=self.description,
+            rule=self.rule,
         )
 
 
@@ -212,6 +235,7 @@ class Scenario:
     steps: list[Step]
     description: str | None = None
     tags: set[str] = field(default_factory=set)
+    rule: Rule | None = None
 
 
 @dataclass(eq=False)
@@ -307,12 +331,10 @@ class Background:
     """Represents the background steps for a feature.
 
     Attributes:
-        feature (Feature): The feature to which this background belongs.
         line_number (int): The line number where the background starts in the file.
         steps (List[Step]): The list of steps in the background.
     """
 
-    feature: Feature
     line_number: int
     steps: list[Step] = field(init=False, default_factory=list)
 
@@ -379,12 +401,15 @@ def parse_steps(self, steps_data: list[GherkinStep]) -> list[Step]:
             )
         return steps
 
-    def parse_scenario(self, scenario_data: GherkinScenario, feature: Feature) -> ScenarioTemplate:
+    def parse_scenario(
+        self, scenario_data: GherkinScenario, feature: Feature, rule: Rule | None = None
+    ) -> ScenarioTemplate:
         """Parse a scenario data dictionary into a ScenarioTemplate object.
 
         Args:
             scenario_data (dict): The dictionary containing scenario data.
             feature (Feature): The feature to which this scenario belongs.
+            rule (Optional[Rule]): The rule to which this scenario may belong. (None = no rule)
 
         Returns:
             ScenarioTemplate: A ScenarioTemplate object representing the parsed scenario.
@@ -398,6 +423,7 @@ def parse_scenario(self, scenario_data: GherkinScenario, feature: Feature) -> Sc
             templated=templated,
             tags=get_tag_names(scenario_data.tags),
             description=textwrap.dedent(scenario_data.description),
+            rule=rule,
         )
         for step in self.parse_steps(scenario_data.steps):
             scenario.add_step(step)
@@ -420,9 +446,8 @@ def parse_scenario(self, scenario_data: GherkinScenario, feature: Feature) -> Sc
 
         return scenario
 
-    def parse_background(self, background_data: GherkinBackground, feature: Feature) -> Background:
+    def parse_background(self, background_data: GherkinBackground) -> Background:
         background = Background(
-            feature=feature,
             line_number=background_data.location.line,
         )
         background.steps = self.parse_steps(background_data.steps)
@@ -439,6 +464,7 @@ def _parse_feature_file(self) -> GherkinDocument:
         return get_gherkin_document(self.abs_filename, self.encoding)
 
     def parse(self) -> Feature:
+        """Parse the feature file and return a Feature object with its backgrounds, rules, and scenarios."""
         gherkin_doc: GherkinDocument = self._parse_feature_file()
         feature_data: GherkinFeature = gherkin_doc.feature
         feature = Feature(
@@ -456,9 +482,47 @@ def parse(self) -> Feature:
 
         for child in feature_data.children:
             if child.background:
-                feature.background = self.parse_background(child.background, feature)
+                feature.background = self.parse_background(child.background)
+            elif child.rule:
+                self._parse_and_add_rule(child.rule, feature)
             elif child.scenario:
-                scenario = self.parse_scenario(child.scenario, feature)
-                feature.scenarios[scenario.name] = scenario
+                self._parse_and_add_scenario(child.scenario, feature)
 
         return feature
+
+    def _parse_and_add_rule(self, rule_data: GherkinRule, feature: Feature) -> None:
+        """Parse a rule, including its background and scenarios, and add to the feature."""
+        background = self._extract_rule_background(rule_data)
+
+        rule = Rule(
+            keyword=rule_data.keyword,
+            name=rule_data.name,
+            description=rule_data.description,
+            tags=get_tag_names(rule_data.tags),
+            background=background,
+        )
+
+        for scenario in self._extract_rule_scenarios(rule_data, feature, rule):
+            feature.scenarios[scenario.name] = scenario
+
+    def _extract_rule_background(self, rule_data: GherkinRule) -> Background | None:
+        """Extract the first background from rule children if it exists."""
+        for child in rule_data.children:
+            if child.background:
+                return self.parse_background(child.background)
+        return None
+
+    def _extract_rule_scenarios(
+        self, rule_data: GherkinRule, feature: Feature, rule: Rule
+    ) -> Generator[ScenarioTemplate]:
+        """Yield each parsed scenario under a rule."""
+        for child in rule_data.children:
+            if child.scenario:
+                yield self.parse_scenario(child.scenario, feature, rule)
+
+    def _parse_and_add_scenario(
+        self, scenario_data: GherkinScenario, feature: Feature, rule: Rule | None = None
+    ) -> None:
+        """Parse an individual scenario and add it to the feature's scenarios."""
+        scenario = self.parse_scenario(scenario_data, feature, rule)
+        feature.scenarios[scenario.name] = scenario