docs: expand pytest-bdd example with failing, outline, data carriers, checkout scenarios

Author: gibiw

examples/single/pytest-bdd/README.md

@@ -1,20 +1,60 @@
 # qase-pytest + pytest-bdd example
 
-Reproduces the customer feedback scenario: a single Gherkin login
-scenario with three steps, each containing a nested manual step via
-`qase.step(...)`.
+A runnable demo of the native pytest-bdd integration in qase-pytest.
+Exercises every feature of the integration so you can see how each kind
+of Gherkin construct is reported in Qase.
 
-## Run
+## What the example covers
+
+| Feature file | Scenario(s) | Demonstrates |
+| --- | --- | --- |
+| `login.feature` | Successful login | Basic Given/When/Then with nested `qase.step()` calls — sub-steps appear as children of the Gherkin step. |
+| `failing.feature` | A failing assertion in the middle step | A failing Then step. The failed step is marked `failed`; pytest-bdd does not run later steps, but the integration records them as `skipped`. |
+| `calculator.feature` | Scenario Outline with 3 example rows | Scenario Outline / Examples — produces three parameterized Qase results for the same scenario. |
+| `data_carriers.feature` | Step with a data table and a docstring | DataTable rendered as a markdown table, DocString rendered as a fenced code block — both end up in the step `data` payload. |
+| `checkout.feature` | Two scenarios sharing a Background | Background steps run before each scenario and are reported on every scenario's result. Multi-scenario feature with distinct `@qase.id=`, `@qase.suite=` tags per scenario. |
+
+## Recognized scenario tags
+
+Tags must be placed on the `Scenario` line (not the `Feature` line) so
+they reach `scenario.tags`:
+
+- `@qase.id=NN` — link to a test case
+- `@qase.suite=A.B.C` — override suite chain (dot for nesting)
+- `@qase.severity=critical` / `@qase.priority=high` / `@qase.layer=e2e`
+- `@qase.ignore` — drop the scenario from the report
+- `@qase.muted` — don't let the scenario fail the run
+
+## Run locally (report mode)
 
 ```bash
 pip install -r requirements.txt
 pytest -v
 ```
 
-Inspect the produced JSON under `build/qase-report/results/` — the
-result has the scenario name as title, the feature/suite hierarchy from
-the tag, three top-level Gherkin steps, and one sub-step under each.
+5 scenarios execute (one failing on purpose). Inspect the produced JSON
+under `build/qase-report/results/`:
+
+- Each result has the scenario name as `title`
+- Each result has a suite chain matching the `@qase.suite` tag
+- Each result has a list of `steps` mirroring the Gherkin steps in order
+- Nested `qase.step(...)` calls (inside step functions) appear as
+  children of the corresponding Gherkin step
+- Failed step has `execution.status: "failed"`; trailing unrun steps
+  are marked `"skipped"`
+- Scenario Outline produces one Qase result per Examples row
+
+## Run against Qase TestOps
+
+Set `mode` to `testops` in `qase.config.json`, and provide credentials
+via env:
+
+```bash
+export QASE_TESTOPS_API_TOKEN=...
+export QASE_TESTOPS_PROJECT=PROJ_CODE
+pytest -v
+```
 
-To send to Qase TestOps instead, set `mode` to `testops` in
-`qase.config.json` and provide `QASE_TESTOPS_API_TOKEN` and
-`QASE_TESTOPS_PROJECT` via env.
+The TestOps API mode preserves native Gherkin step structure (keyword
++ name + data) and renders steps with their Given/When/Then keywords
+in the Qase UI.

examples/single/pytest-bdd/features/calculator.feature

@@ -0,0 +1,12 @@
+Feature: Adding numbers
+
+  @qase.id=11 @qase.suite=Math.Outline
+  Scenario Outline: Adding two numbers
+    Given I have <a> and <b>
+    Then their sum is <c>
+
+    Examples:
+      | a | b | c  |
+      | 1 | 2 | 3  |
+      | 5 | 7 | 12 |
+      | 0 | 0 | 0  |

examples/single/pytest-bdd/features/checkout.feature

@@ -0,0 +1,16 @@
+Feature: Checkout
+
+  Background:
+    Given the user is signed in
+    And the cart contains 2 items
+
+  @qase.id=13 @qase.suite=Checkout.Success
+  Scenario: Successful checkout
+    When the user clicks "Place order"
+    Then the order is created
+
+  @qase.id=14 @qase.suite=Checkout.PaymentDeclined
+  Scenario: Declined payment
+    Given the saved card is expired
+    When the user clicks "Place order"
+    Then the payment fails with "card_expired"

examples/single/pytest-bdd/features/data_carriers.feature

@@ -0,0 +1,13 @@
+Feature: Data carriers
+
+  @qase.id=12 @qase.suite=API.Payloads
+  Scenario: Step with a data table and a docstring
+    Given the following users:
+      | name  | role  |
+      | Alice | admin |
+      | Bob   | user  |
+    When I send the payload:
+      """
+      {"username": "alice", "active": true}
+      """
+    Then the request succeeds

examples/single/pytest-bdd/features/failing.feature

@@ -0,0 +1,7 @@
+Feature: Math
+
+  @qase.id=10 @qase.suite=Math.Failure @qase.severity=major
+  Scenario: A failing assertion in the middle step
+    Given a calculator
+    When I add 2 and 2
+    Then the result should be 5

examples/single/pytest-bdd/tests/test_calculator.py

@@ -0,0 +1,13 @@
+from pytest_bdd import scenarios, given, then, parsers
+
+scenarios("../features/calculator.feature")
+
+
+@given(parsers.parse("I have {a:d} and {b:d}"), target_fixture="numbers")
+def numbers(a, b):
+    return a, b
+
+
+@then(parsers.parse("their sum is {c:d}"))
+def check_sum(numbers, c):
+    assert sum(numbers) == c

examples/single/pytest-bdd/tests/test_checkout.py

@@ -0,0 +1,33 @@
+from pytest_bdd import scenarios, given, when, then, parsers
+
+scenarios("../features/checkout.feature")
+
+
+@given("the user is signed in")
+def signed_in():
+    pass
+
+
+@given("the cart contains 2 items")
+def cart_two_items():
+    pass
+
+
+@given("the saved card is expired")
+def expired_card():
+    pass
+
+
+@when(parsers.parse('the user clicks "{label}"'))
+def click(label):
+    assert label == "Place order"
+
+
+@then("the order is created")
+def order_created():
+    assert True
+
+
+@then(parsers.parse('the payment fails with "{reason}"'))
+def payment_failure(reason):
+    assert reason == "card_expired"

examples/single/pytest-bdd/tests/test_data_carriers.py

@@ -0,0 +1,21 @@
+from pytest_bdd import scenarios, given, when, then
+
+scenarios("../features/data_carriers.feature")
+
+
+@given("the following users:")
+def users(datatable=None):
+    # pytest-bdd injects the data table into the step function when a
+    # parameter named `datatable` is present; ignore it here — the
+    # purpose of this example is to see the table land in the Qase report.
+    pass
+
+
+@when("I send the payload:")
+def payload(docstring=None):
+    pass
+
+
+@then("the request succeeds")
+def request_ok():
+    assert True

examples/single/pytest-bdd/tests/test_failing.py

@@ -0,0 +1,18 @@
+from pytest_bdd import scenarios, given, when, then
+
+scenarios("../features/failing.feature")
+
+
+@given("a calculator")
+def a_calc():
+    pass
+
+
+@when("I add 2 and 2")
+def add():
+    pass
+
+
+@then("the result should be 5")
+def assert_five():
+    assert 2 + 2 == 5