executable-stories-pytest 0.1.1__tar.gz → 0.2.0__tar.gz

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: executable-stories-pytest
-Version: 0.1.1
+Version: 0.2.0
 Summary: pytest plugin for executable-stories BDD documentation
 Author: Jag Reehal
 License-Expression: Apache-2.0

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "executable-stories-pytest"
-version = "0.1.1"
+version = "0.2.0"
 description = "pytest plugin for executable-stories BDD documentation"
 requires-python = ">=3.10"
 license = "Apache-2.0"

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/src/executable_stories/_plugin.py

@@ -172,6 +172,13 @@ def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[None]) ->
     if report.when != "call":
         return
 
+    # A red test shows how far its story got without opening the report. A
+    # section, not longrepr, so the recorded error message stays as it was.
+    if report.failed:
+        trail = story._step_trail()
+        if trail:
+            report.sections.append(("Story steps", trail))
+
     start_ms = _test_start_times.pop(item.nodeid, 0.0)
     now_ms = time.time() * 1000
     duration_ms = now_ms - start_ms if start_ms else 0.0

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/src/executable_stories/_story_api.py

@@ -49,6 +49,8 @@ class _StoryContext:
         "timer_counter",
         "otel_spans",
         "planned",
+        "started_at_ms",
+        "failed_step",
     )
 
     def __init__(
@@ -76,6 +78,9 @@ class _StoryContext:
         self.timer_counter: int = 0
         self.otel_spans: list[dict[str, Any]] | None = None
         self.planned: bool = False
+        self.started_at_ms: float = time.time() * 1000
+        # The wrapped step whose body raised, if one did.
+        self.failed_step: dict[str, Any] | None = None
 
 
 class Story:
@@ -246,8 +251,29 @@ class Story:
             result["docs"] = list(ctx.docs)
         if ctx.otel_spans:
             result["otelSpans"] = ctx.otel_spans
+        # A planned scenario never ran, so it has no start time.
+        if not ctx.planned:
+            result["startedAtMs"] = ctx.started_at_ms
         return result
 
+    def _step_trail(self) -> str | None:
+        """The story's steps as a checklist for a failed test's report.
+
+        The failing step is the wrapped step whose body raised, else the last
+        step: a marker states a claim and the assertion that broke follows it.
+        When the last step is a wrapped body that finished, the failure came
+        after it.
+        """
+        ctx = self._ctx
+        if ctx is None or not ctx.steps:
+            return None
+        last = ctx.steps[-1]
+        failed = ctx.failed_step or (None if last.get("wrapped") else last)
+        lines = [f"  {'✗' if s is failed else '✓'} {s['keyword']} {s['text']}" for s in ctx.steps]
+        if failed is None:
+            lines.append("  ✗ (failed after the last step)")
+        return "\n".join(lines)
+
     def _get_attachments(self) -> list[dict[str, Any]]:
         """Return the attachments list for the current test."""
         ctx = self._ctx
@@ -279,13 +305,15 @@ class Story:
         ctx = self._ctx
         if ctx is None:
             raise RuntimeError(f"story.{keyword.lower()}() called before story.init()")
+        # A new step means the test caught an earlier wrapped step's exception.
+        ctx.failed_step = None
         # Auto-And: repeated primary keywords render as "And"
         if keyword in ("Given", "When", "Then"):
             if keyword in ctx.seen_primary_keywords:
                 keyword = "And"
             else:
                 ctx.seen_primary_keywords.add(keyword)
-        step: dict[str, Any] = {"keyword": keyword, "text": text}
+        step: dict[str, Any] = {"keyword": keyword, "text": text, "startedAtMs": time.time() * 1000}
         step["id"] = f"step-{ctx.step_counter}"
         ctx.step_counter += 1
         if mode is not None:
@@ -370,6 +398,11 @@ class Story:
         try:
             result = body()
             return result
+        except BaseException:
+            # A nested step that raised first keeps the mark.
+            if ctx.failed_step is None:
+                ctx.failed_step = step
+            raise
         finally:
             step["durationMs"] = (time.perf_counter() - start) * 1000.0
 

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/src/executable_stories/_types.py

@@ -189,6 +189,7 @@ class StoryStep(TypedDict):
     # An absent key means unobserved, which is not the same as zero.
     assertions: NotRequired[int]
     durationMs: NotRequired[float]
+    startedAtMs: NotRequired[float]
     docs: NotRequired[list[DocEntry]]
 
 
@@ -205,6 +206,7 @@ class StoryMeta(TypedDict):
     suitePath: NotRequired[list[str]]
     docs: NotRequired[list[DocEntry]]
     sourceOrder: NotRequired[int]
+    startedAtMs: NotRequired[float]
 
 
 # ── RawTestCase ────────────────────────────────────────────────────

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/src/executable_stories_pytest.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: executable-stories-pytest
-Version: 0.1.1
+Version: 0.2.0
 Summary: pytest plugin for executable-stories BDD documentation
 Author: Jag Reehal
 License-Expression: Apache-2.0

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/tests/test_plugin.py

@@ -273,3 +273,74 @@ def test_ordinary_story():
         raw_run = json.loads((pytester.path / ".executable-stories" / "raw-run.json").read_text())
         statuses = sorted(tc["status"] for tc in raw_run["testCases"])
         assert statuses == ["pass", "todo"]
+
+
+class TestFailureStepTrail:
+    """A failing story test lists its steps, so a red run shows how far it got."""
+
+    def test_lists_steps_and_marks_the_failing_one(self, pytester):
+        pytester.makepyfile(
+            test_trail="""
+from executable_stories import story
+
+def test_marker():
+    story.init("Marker")
+    story.given("a balance of 50")
+    story.then("the balance is 150")
+    assert 50 + 100 == 151
+
+def test_wrapped():
+    story.init("Wrapped")
+    story.fn("Given", "setup", lambda: None)
+    def boom():
+        raise RuntimeError("kaput")
+    story.fn("When", "it breaks", boom)
+    story.then("never reached")
+
+def test_after_wrapped():
+    story.init("After")
+    story.fn("Given", "setup", lambda: None)
+    raise RuntimeError("later")
+
+def test_caught():
+    story.init("Caught")
+    def rejected():
+        raise ValueError("rejected")
+    try:
+        story.fn("Given", "a rejected input", rejected)
+    except ValueError:
+        pass
+    story.then("the total is 3")
+    assert 1 + 2 == 4
+
+def test_nested():
+    story.init("Nested")
+    def declined():
+        raise RuntimeError("declined")
+    story.fn("When", "the order is placed", lambda: story.fn("And", "payment is taken", declined))
+"""
+        )
+        result = pytester.runpytest_subprocess(*_DISABLE_PLUGINS)
+        result.assert_outcomes(failed=5)
+        result.stdout.fnmatch_lines(
+            [
+                "*Story steps*",
+                "  ✓ Given a balance of 50",
+                "  ✗ Then the balance is 150",
+                "*Story steps*",
+                "  ✓ Given setup",
+                "  ✗ When it breaks",
+                "*Story steps*",
+                "  ✓ Given setup",
+                "  ✗ (failed after the last step)",
+                "*Story steps*",
+                "  ✓ Given a rejected input",
+                "  ✗ Then the total is 3",
+                "*Story steps*",
+                "  ✓ When the order is placed",
+                "  ✗ And payment is taken",
+            ]
+        )
+        # The trail is a report section, not part of the recorded error.
+        raw = (pytester.path / ".executable-stories" / "raw-run.json").read_text()
+        assert "Story steps" not in raw

{executable_stories_pytest-0.1.1 → executable_stories_pytest-0.2.0}/tests/test_story_api.py

@@ -647,6 +647,18 @@ class TestTicketNormalization:
 
 
 class TestStepTiming:
+    def test_started_at_ms_on_scenario_and_steps(self, fresh_story: Story):
+        fresh_story.init("Start times")
+        fresh_story.given("a step")
+        fresh_story.fn("When", "a wrapped step", lambda: None)
+        meta = fresh_story._get_meta()
+        assert meta is not None
+        scenario_start = meta["startedAtMs"]
+        first, second = (s["startedAtMs"] for s in meta["steps"])
+        assert scenario_start > 1_000_000_000_000  # epoch ms, not seconds or zero
+        assert first >= scenario_start
+        assert second >= first
+
     def test_start_timer_end_timer_sets_duration_ms(self, fresh_story: Story):
         fresh_story.init("Timing test")
         fresh_story.given("a step")