Add tags support for Examples sections

- Example tags could be used for test selection
- Example tags could not be used for invoking pytest_bdd_apply_tag hook for now
- Add explicit support for multiple Examples sections
- "Examples: Vertical" replaced with "Examples Transposed:" for more convenient naming
- Examples sections names are parsed (not used now)

Author: Konstantin Goloveshko

CHANGES.rst

@@ -6,6 +6,7 @@ Unreleased
 - Drop compatibility for python 2 and officially support only python >= 3.6.
 - Fix error when using `--cucumber-json-expanded` in combination with `example_converters` (marcbrossaissogeti).
 - Fix `--generate-missing` not correctly recognizing steps with parsers
+- Add partial support of tags for ``Examples:`` ; Fixes minor bugs with Examples
 
 4.0.2
 -----

README.rst

@@ -496,13 +496,13 @@ pytest-bdd feature file format also supports example tables in different way:
             When I eat <eat> cucumbers
             Then I should have <left> cucumbers
 
-            Examples: Vertical
+            Examples Transposed:
             | start | 12 | 2 |
             | eat   | 5  | 1 |
             | left  | 7  | 1 |
 
 This form allows to have tables with lots of columns keeping the maximum text width predictable without significant
-readability change.
+readability change. "Examples: Vertical" examples header also could be used, but will be removed in future
 
 The code will look like:
 
@@ -601,6 +601,41 @@ This is allowed as long as parameter names do not clash:
             | carrots    |
             | tomatoes   |
 
+Feature and scenario outlines support tags and multiple example tables.
+Outline tags could be used for test suite selection but not for applying hook tag
+
+.. code-block:: gherkin
+
+    Feature: Outlined
+        Background:
+            Given I have cucumbers at <tableware>
+
+        @indoor
+        Examples: Indoor
+            |tableware|
+            |dish     |
+            |plate    |
+
+        @outdoor
+        Examples Transposed: Outdoor
+            |tableware|basket|lunchbox|
+
+        Scenario Outline: Outlined given, when, thens
+            Given there are <start> cucumbers
+            When I eat <eat> cucumbers
+            Then I should have <left> cucumbers
+
+            @breakfast
+            Examples: Vertical Breakfast
+            | start | 12 | 2 |
+            | eat   | 5  | 1 |
+            | left  | 7  | 1 |
+
+            @lunch
+            Examples: Lunch
+            |start|eat|left|
+            |3    |1  |2   |
+            |2    |2  |0   |
 
 Combine scenario outline and pytest parametrization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

pytest_bdd/parser.py

@@ -3,6 +3,11 @@
 import re
 import textwrap
 from collections import OrderedDict
+from itertools import chain
+from operator import attrgetter
+from typing import List, Type
+
+from attr import attrs, attrib, Factory
 
 from . import types, exceptions
 
@@ -11,7 +16,8 @@
 STEP_PREFIXES = [
     ("Feature: ", types.FEATURE),
     ("Scenario Outline: ", types.SCENARIO_OUTLINE),
-    ("Examples: Vertical", types.EXAMPLES_VERTICAL),
+    ("Examples: Vertical", types.EXAMPLES_VERTICAL_LEGACY),
+    ("Examples Transposed:", types.EXAMPLES_TRANSPOSED),
     ("Examples:", types.EXAMPLES),
     ("Scenario: ", types.SCENARIO),
     ("Background:", types.BACKGROUND),
@@ -142,8 +148,7 @@ def parse_feature(basedir, filename, encoding="utf-8"):
                     clean_line,
                     filename,
                 )
-
-        prev_mode = mode
+        prev_prev_mode, prev_mode = prev_mode, mode
 
         # Remove Feature, Given, When, Then, And
         keyword, parsed_line = parse_line(clean_line)
@@ -154,19 +159,35 @@ def parse_feature(basedir, filename, encoding="utf-8"):
             feature.background = Background(feature=feature, line_number=line_number)
         elif mode == types.EXAMPLES:
             mode = types.EXAMPLES_HEADERS
-            (scenario or feature).examples.line_number = line_number
-        elif mode == types.EXAMPLES_VERTICAL:
-            mode = types.EXAMPLE_LINE_VERTICAL
-            (scenario or feature).examples.line_number = line_number
+            _, example_table_name = parse_line(clean_line)
+            obj = scenario or feature
+            obj.examples.add_example_table(UsualExampleTable)
+            obj.examples.last_example_table.name = example_table_name or None
+            obj.examples.last_example_table.line_number = line_number
+            if prev_prev_mode == types.TAG:
+                obj.examples.last_example_table.tags = get_tags(prev_line)
+        elif (
+            mode == types.EXAMPLES_TRANSPOSED or mode == types.EXAMPLES_VERTICAL_LEGACY
+        ):  # Deprecated; Has to be removed in future versions
+            mode = types.EXAMPLE_LINE_TRANSPOSED
+            _, example_table_name = parse_line(clean_line)
+            obj = scenario or feature
+            obj.examples.add_example_table(TransposedExampleTable)
+            obj.examples.last_example_table.name = example_table_name or None
+            obj.examples.last_example_table.line_number = line_number
+            if prev_prev_mode == types.TAG:
+                obj.examples.last_example_table.tags = get_tags(prev_line)
         elif mode == types.EXAMPLES_HEADERS:
-            (scenario or feature).examples.set_param_names([l for l in split_line(parsed_line) if l])
+            (scenario or feature).examples.last_example_table.set_param_names([l for l in split_line(parsed_line) if l])
             mode = types.EXAMPLE_LINE
         elif mode == types.EXAMPLE_LINE:
-            (scenario or feature).examples.add_example([l for l in split_line(stripped_line)])
-        elif mode == types.EXAMPLE_LINE_VERTICAL:
+            example_table: UsualExampleTable = (scenario or feature).examples.last_example_table
+            example_table.add_example([l for l in split_line(stripped_line)])
+        elif mode == types.EXAMPLE_LINE_TRANSPOSED:
             param_line_parts = [l for l in split_line(stripped_line)]
             try:
-                (scenario or feature).examples.add_example_row(param_line_parts[0], param_line_parts[1:])
+                example_table: TransposedExampleTable = (scenario or feature).examples.last_example_table
+                example_table.add_example_row(param_line_parts[0], param_line_parts[1:])
             except exceptions.ExamplesNotValidError as exc:
                 if scenario:
                     raise exceptions.FeatureError(
@@ -267,12 +288,20 @@ def params(self):
 
     def get_example_params(self):
         """Get example parameter names."""
-        return set(self.examples.example_params + self.feature.examples.example_params)
+        return set(
+            chain(
+                *map(
+                    attrgetter("example_params"),
+                    chain(self.examples.example_tables, self.feature.examples.example_tables),
+                ),
+            )
+        )
 
     def get_params(self, builtin=False):
         """Get converted example params."""
         for examples in [self.feature.examples, self.examples]:
-            yield examples.get_params(self.example_converters, builtin=builtin)
+            for example_table in examples.example_tables:
+                yield example_table.tags, example_table.get_params(self.example_converters, builtin=builtin)
 
     def validate(self):
         """Validate the scenario.
@@ -373,17 +402,28 @@ def add_step(self, step):
         self.steps.append(step)
 
 
+@attrs
 class Examples:
+    example_tables: List["ExampleTable"] = attrib(default=Factory(list))
+
+    def add_example_table(self, builder: Type["ExampleTable"]):
+        self.example_tables.append(builder())
+
+    @property
+    def last_example_table(self) -> "ExampleTable":
+        return self.example_tables[-1]
 
+
+@attrs
+class ExampleTable(object):
     """Example table."""
 
-    def __init__(self):
-        """Initialize examples instance."""
-        self.example_params = []
-        self.examples = []
-        self.vertical_examples = []
-        self.line_number = None
-        self.name = None
+    example_params = attrib(default=Factory(list))
+    examples = attrib(default=Factory(list))
+
+    line_number = attrib(default=None)
+    name = attrib(default=None)
+    tags = attrib(default=Factory(list))
 
     def set_param_names(self, keys):
         """Set parameter names.
@@ -392,12 +432,28 @@ def set_param_names(self, keys):
         """
         self.example_params = [str(key) for key in keys]
 
-    def add_example(self, values):
-        """Add example.
+    def get_params(self, converters, builtin=False):
+        """Get scenario pytest parametrization table.
 
-        :param values: `list` of `string` parameter values.
+        :param converters: `dict` of converter functions to convert parameter values
         """
-        self.examples.append(values)
+        params = []
+
+        for example in self.examples:
+            example = list(example)
+            for index, param in enumerate(self.example_params):
+                raw_value = example[index]
+                if converters and param in converters:
+                    value = converters[param](raw_value)
+                    if not builtin or value.__class__.__module__ in {"__builtin__", "builtins"}:
+                        example[index] = value
+            params.append(example)
+        return self.example_params, params
+
+
+@attrs
+class TransposedExampleTable(ExampleTable):
+    example_param_values = attrib(default=Factory(list))
 
     def add_example_row(self, param, values):
         """Add example row.
@@ -410,39 +466,24 @@ def add_example_row(self, param, values):
                 f"""Example rows should contain unique parameters. "{param}" appeared more than once"""
             )
         self.example_params.append(param)
-        self.vertical_examples.append(values)
+        self.example_param_values.append(values)
 
     def get_params(self, converters, builtin=False):
         """Get scenario pytest parametrization table.
 
         :param converters: `dict` of converter functions to convert parameter values
         """
-        param_count = len(self.example_params)
-        if self.vertical_examples and not self.examples:
-            for value_index in range(len(self.vertical_examples[0])):
-                example = []
-                for param_index in range(param_count):
-                    example.append(self.vertical_examples[param_index][value_index])
-                self.examples.append(example)
-
-        if self.examples:
-            params = []
-            for example in self.examples:
-                example = list(example)
-                for index, param in enumerate(self.example_params):
-                    raw_value = example[index]
-                    if converters and param in converters:
-                        value = converters[param](raw_value)
-                        if not builtin or value.__class__.__module__ in {"__builtin__", "builtins"}:
-                            example[index] = value
-                params.append(example)
-            return [self.example_params, params]
-        else:
-            return []
+        self.examples = list(zip(*self.example_param_values))
+        return super().get_params(converters, builtin=builtin)
+
 
-    def __bool__(self):
-        """Bool comparison."""
-        return bool(self.vertical_examples or self.examples)
+class UsualExampleTable(ExampleTable):
+    def add_example(self, values):
+        """Add example.
+
+        :param values: `list` of `string` parameter values.
+        """
+        self.examples.append(values)
 
 
 def get_tags(line):

pytest_bdd/reporting.py

@@ -5,8 +5,11 @@
 """
 
 import time
+from itertools import chain
 
-from .utils import get_parametrize_markers_args
+from _pytest.mark import ParameterSet
+
+from .utils import get_parametrize_markers
 
 
 class StepReport:
@@ -70,21 +73,7 @@ def __init__(self, scenario, node):
         """
         self.scenario = scenario
         self.step_reports = []
-        self.param_index = None
-        parametrize_args = get_parametrize_markers_args(node)
-        if parametrize_args and scenario.examples:
-            param_names = (
-                parametrize_args[0] if isinstance(parametrize_args[0], (tuple, list)) else [parametrize_args[0]]
-            )
-            param_values = parametrize_args[1]
-            node_param_values = [node.funcargs[param_name] for param_name in param_names]
-            if node_param_values in param_values:
-                self.param_index = param_values.index(node_param_values)
-            elif tuple(node_param_values) in param_values:
-                self.param_index = param_values.index(tuple(node_param_values))
-        self.example_kwargs = {
-            example_param: str(node.funcargs[example_param]) for example_param in scenario.get_example_params()
-        }
+        self.node = node
 
     @property
     def current_step_report(self):
@@ -112,7 +101,6 @@ def serialize(self):
         scenario = self.scenario
         feature = scenario.feature
 
-        params = sum(scenario.get_params(builtin=True), []) if scenario.examples else None
         return {
             "steps": [step_report.serialize() for step_report in self.step_reports],
             "name": scenario.name,
@@ -126,17 +114,42 @@ def serialize(self):
                 "description": feature.description,
                 "tags": sorted(feature.tags),
             },
+            **self.serialize_examples(),
+        }
+
+    def get_param_index(self, param_names):
+        parametrize_args = get_parametrize_markers(self.node)
+
+        for parametrize_arg in parametrize_args:
+            arg_param_names = (
+                parametrize_arg.names if isinstance(parametrize_arg[0], (tuple, list)) else [parametrize_arg.names]
+            )
+            param_values = [list(v.values) if isinstance(v, ParameterSet) else v for v in parametrize_arg.values]
+            if param_names == arg_param_names:
+                node_param_values = [self.node.funcargs[param_name] for param_name in param_names]
+                if node_param_values in param_values:
+                    return param_values.index(node_param_values)
+                elif tuple(node_param_values) in param_values:
+                    return param_values.index(tuple(node_param_values))
+
+    def serialize_examples(self):
+        return {
             "examples": [
                 {
-                    "name": scenario.examples.name,
-                    "line_number": scenario.examples.line_number,
-                    "rows": params,
-                    "row_index": self.param_index,
+                    "name": example_table.name,
+                    "line_number": example_table.line_number,
+                    "rows": list(example_table.get_params(self.scenario.example_converters, builtin=True)),
+                    "row_index": self.get_param_index(example_table.example_params),
+                    "tags": list(example_table.tags),
                 }
-            ]
-            if scenario.examples
-            else [],
-            "example_kwargs": self.example_kwargs,
+                for example_table in chain(
+                    self.scenario.examples.example_tables, self.scenario.feature.examples.example_tables
+                )
+            ],
+            "example_kwargs": {
+                example_param: str(self.node.funcargs[example_param])
+                for example_param in self.scenario.get_example_params()
+            },
         }
 
     def fail(self):