executable-stories-pytest 0.1.0__py3-none-any.whl

executable_stories/__init__.py

@@ -0,0 +1,5 @@
+"""pytest plugin for executable-stories BDD documentation."""
+
+from executable_stories._story_api import story
+
+__all__ = ["story"]

executable_stories/_collector.py

@@ -0,0 +1,37 @@
+"""Thread-safe test case collector.
+
+Accumulates RawTestCase dicts as tests complete, then hands them off
+to the JSON writer at session end.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+
+class _Collector:
+    """Thread-safe registry for completed test case results."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._cases: list[dict[str, Any]] = []
+
+    def record(self, test_case: dict[str, Any]) -> None:
+        """Append a completed RawTestCase dict."""
+        with self._lock:
+            self._cases.append(test_case)
+
+    def get_all(self) -> list[dict[str, Any]]:
+        """Return all collected test cases."""
+        with self._lock:
+            return list(self._cases)
+
+    def clear(self) -> None:
+        """Reset the collector."""
+        with self._lock:
+            self._cases.clear()
+
+
+# Module-level singleton
+_collector = _Collector()

executable_stories/_json_writer.py

@@ -0,0 +1,21 @@
+"""Simple JSON serialization for RawRun output."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+
+def write_raw_run(raw_run: dict[str, Any], output_path: str) -> None:
+    """Write a RawRun dict to a JSON file.
+
+    Creates parent directories if they don't exist.
+    """
+    parent = os.path.dirname(output_path)
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(raw_run, f, indent=2)
+        f.write("\n")

executable_stories/_plugin.py

@@ -0,0 +1,221 @@
+"""pytest plugin that hooks into test lifecycle to capture BDD story data.
+
+Registered via the ``pytest11`` entry point in pyproject.toml.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import traceback
+from typing import Any
+
+import pytest
+
+from executable_stories._collector import _collector
+from executable_stories._json_writer import write_raw_run
+from executable_stories._story_api import story
+
+# ── CI detection ──────────────────────────────────────────────────
+
+
+def _detect_ci() -> dict[str, Any] | None:
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        ci: dict[str, Any] = {"name": "github"}
+        build_num = os.environ.get("GITHUB_RUN_NUMBER")
+        if build_num:
+            ci["buildNumber"] = build_num
+        server = os.environ.get("GITHUB_SERVER_URL")
+        repo = os.environ.get("GITHUB_REPOSITORY")
+        run_id = os.environ.get("GITHUB_RUN_ID")
+        if server and repo and run_id:
+            ci["url"] = f"{server}/{repo}/actions/runs/{run_id}"
+        return ci
+    if os.environ.get("CIRCLECI") == "true":
+        ci = {"name": "circleci"}
+        build_num = os.environ.get("CIRCLE_BUILD_NUM")
+        if build_num:
+            ci["buildNumber"] = build_num
+        url = os.environ.get("CIRCLE_BUILD_URL")
+        if url:
+            ci["url"] = url
+        return ci
+    if os.environ.get("JENKINS_URL"):
+        ci = {"name": "jenkins"}
+        build_num = os.environ.get("BUILD_NUMBER")
+        if build_num:
+            ci["buildNumber"] = build_num
+        url = os.environ.get("BUILD_URL")
+        if url:
+            ci["url"] = url
+        return ci
+    if os.environ.get("TRAVIS") == "true":
+        ci = {"name": "travis"}
+        build_num = os.environ.get("TRAVIS_BUILD_NUMBER")
+        if build_num:
+            ci["buildNumber"] = build_num
+        url = os.environ.get("TRAVIS_BUILD_WEB_URL")
+        if url:
+            ci["url"] = url
+        return ci
+    if os.environ.get("GITLAB_CI") == "true":
+        ci = {"name": "gitlab"}
+        build_num = os.environ.get("CI_PIPELINE_IID")
+        if build_num:
+            ci["buildNumber"] = build_num
+        url = os.environ.get("CI_PIPELINE_URL")
+        if url:
+            ci["url"] = url
+        return ci
+    if os.environ.get("CI") == "true":
+        return {"name": "ci"}
+    return None
+
+
+# ── Session-level timestamps ───────────────────────────────────────
+
+_started_at_ms: float = 0.0
+
+
+def pytest_sessionstart(session: pytest.Session) -> None:
+    global _started_at_ms
+    _started_at_ms = time.time() * 1000
+    _collector.clear()
+
+
+# ── Per-test hooks ─────────────────────────────────────────────────
+
+# We store per-test start times keyed by node id.
+_test_start_times: dict[str, float] = {}
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_call(item: pytest.Item) -> Any:
+    """Wrap test execution to set up / tear down the story context."""
+    _test_start_times[item.nodeid] = time.time() * 1000
+    yield
+    # Story context is cleared after report is built (in makereport)
+
+
+_STATUS_MAP = {
+    "passed": "pass",
+    "failed": "fail",
+    "skipped": "skip",
+}
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[None]) -> Any:
+    """Capture test result on the 'call' phase and record it."""
+    outcome = yield
+    report: pytest.TestReport = outcome.get_result()
+
+    if report.when != "call":
+        return
+
+    # Build the test case dict
+    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
+
+    # Status mapping
+    if hasattr(report, "wasxfail"):
+        status = "skip"
+    else:
+        status = _STATUS_MAP.get(report.outcome, "unknown")
+
+    # Retry info from pytest-rerunfailures (if available)
+    rerun = getattr(item, "execution_count", None)
+    retry = (rerun - 1) if rerun is not None and rerun > 0 else 0
+    reruns_count = getattr(item.session.config, "_rerun_count", None)
+    retries = reruns_count if reruns_count is not None else 0
+
+    test_case: dict[str, Any] = {
+        "status": status,
+        "externalId": item.nodeid,
+        "title": item.name,
+        "durationMs": round(duration_ms, 2),
+        "retry": retry,
+        "retries": retries,
+    }
+
+    # Source file info
+    try:
+        fspath = str(item.fspath)
+        if fspath:
+            test_case["sourceFile"] = fspath
+        if item.location and item.location[1] is not None:
+            test_case["sourceLine"] = item.location[1] + 1  # 0-based to 1-based
+    except Exception:
+        pass
+
+    # Error info
+    if report.failed and report.longrepr:
+        error: dict[str, str] = {}
+        if isinstance(report.longrepr, tuple):
+            error["message"] = str(report.longrepr[2])
+            error["stack"] = f"{report.longrepr[0]}:{report.longrepr[1]}"
+        else:
+            repr_str = str(report.longrepr)
+            error["message"] = repr_str
+            error["stack"] = repr_str
+        test_case["error"] = error
+
+    # Story metadata
+    story_meta = story._get_meta()
+    if story_meta is not None:
+        test_case["story"] = story_meta
+        # Build stepEvents from steps with durationMs
+        step_events: list[dict[str, Any]] = []
+        if "steps" in story_meta:
+            for i, step in enumerate(story_meta["steps"]):
+                if "durationMs" in step:
+                    step_events.append(
+                        {
+                            "index": i,
+                            "title": step["text"],
+                            "durationMs": step["durationMs"],
+                        }
+                    )
+        if step_events:
+            test_case["stepEvents"] = step_events
+
+    # Attachments
+    attachments = story._get_attachments()
+    if attachments:
+        test_case["attachments"] = attachments
+
+    _collector.record(test_case)
+
+    # Clear story context for next test
+    story._clear()
+
+
+# ── Session finish — write output ──────────────────────────────────
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    test_cases = _collector.get_all()
+    if not test_cases:
+        return
+
+    finished_at_ms = time.time() * 1000
+
+    raw_run: dict[str, Any] = {
+        "schemaVersion": 1,
+        "testCases": test_cases,
+        "projectRoot": str(session.config.rootdir),  # type: ignore[attr-defined]
+        "startedAtMs": round(_started_at_ms, 2),
+        "finishedAtMs": round(finished_at_ms, 2),
+    }
+
+    ci = _detect_ci()
+    if ci is not None:
+        raw_run["ci"] = ci
+
+    output_path = os.environ.get(
+        "EXECUTABLE_STORIES_OUTPUT",
+        os.path.join(str(session.config.rootdir), ".executable-stories", "raw-run.json"),  # type: ignore[attr-defined]
+    )
+
+    write_raw_run(raw_run, output_path)

executable_stories/_story_api.py

@@ -0,0 +1,554 @@
+"""Thread-safe BDD story API.
+
+Usage in tests::
+
+    from executable_stories import story
+
+    def test_login():
+        story.init("User logs in with valid credentials", tags=["auth", "smoke"])
+        story.given("a registered user")
+        story.when("they submit valid credentials")
+        story.then("they see the dashboard")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from typing import Any, Callable, TypeVar
+
+_T = TypeVar("_T")
+
+
+class _StoryContext:
+    """Per-test story context stored in thread-local storage."""
+
+    __slots__ = (
+        "scenario",
+        "steps",
+        "tags",
+        "tickets",
+        "meta",
+        "suite_path",
+        "docs",
+        "seen_primary_keywords",
+        "step_counter",
+        "attachments",
+        "_current_step",
+        "active_timers",
+        "timer_counter",
+        "otel_spans",
+    )
+
+    def __init__(
+        self,
+        scenario: str,
+        *,
+        tags: list[str] | None = None,
+        tickets: list[dict[str, Any]] | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        self.scenario = scenario
+        self.steps: list[dict[str, Any]] = []
+        self.tags = tags or []
+        self.tickets: list[dict[str, Any]] = tickets or []
+        self.meta = meta or {}
+        self.suite_path: list[str] = []
+        self.docs: list[dict[str, Any]] = []
+        self.seen_primary_keywords: set[str] = set()
+        self.step_counter: int = 0
+        self.attachments: list[dict[str, Any]] = []
+        self._current_step: dict[str, Any] | None = None
+        self.active_timers: dict[int, dict[str, Any]] = {}
+        self.timer_counter: int = 0
+        self.otel_spans: list[dict[str, Any]] | None = None
+
+
+class Story:
+    """Thread-safe BDD story builder.
+
+    Each test thread gets its own context via ``threading.local()``.
+    """
+
+    def __init__(self) -> None:
+        self._local = threading.local()
+
+    # ── context management ─────────────────────────────────────────
+
+    @property
+    def _ctx(self) -> _StoryContext | None:
+        return getattr(self._local, "ctx", None)
+
+    @staticmethod
+    def _normalize_tickets(ticket: Any) -> list[dict[str, Any]] | None:
+        """Normalize ticket input to list of ``{"id": ...}`` dicts."""
+        if ticket is None:
+            return None
+        if not isinstance(ticket, list):
+            ticket = [ticket]
+        return [{"id": t} if isinstance(t, str) else t for t in ticket]
+
+    def init(
+        self,
+        scenario: str,
+        *,
+        tags: list[str] | None = None,
+        ticket: str | list[str] | dict | list[dict | str] | None = None,
+        meta: dict[str, Any] | None = None,
+        trace_url_template: str | None = None,
+    ) -> None:
+        """Start a new story context for the current test."""
+        tickets = self._normalize_tickets(ticket)
+        self._local.ctx = _StoryContext(scenario, tags=tags, tickets=tickets, meta=meta)
+
+        # OTel bridge: detect active span, flow data bidirectionally
+        ctx = self._local.ctx
+        try:
+            from opentelemetry import trace as otel_trace  # type: ignore[import-not-found]
+
+            span = otel_trace.get_current_span()
+            span_ctx = span.get_span_context()
+            if span_ctx and span_ctx.trace_id and span_ctx.trace_id != 0:
+                trace_id = format(span_ctx.trace_id, "032x")
+                span_id = format(span_ctx.span_id, "016x")
+
+                # OTel -> Story: capture traceId in structured meta
+                ctx.meta["otel"] = {"traceId": trace_id, "spanId": span_id}
+
+                # OTel -> Story: inject human-readable doc entries
+                ctx.docs.append({"kind": "kv", "label": "Trace ID", "value": trace_id, "phase": "runtime"})
+
+                template = trace_url_template or os.environ.get("OTEL_TRACE_URL_TEMPLATE")
+                if template:
+                    url = template.replace("{traceId}", trace_id)
+                    ctx.docs.append({"kind": "link", "label": "View Trace", "url": url, "phase": "runtime"})
+
+                # Story -> OTel: enrich active span with story attributes
+                span.set_attribute("story.scenario", scenario)
+                if tags:
+                    span.set_attribute("story.tags", tags)
+                if ticket:
+                    ticket_list = [ticket] if isinstance(ticket, str) else ticket
+                    span.set_attribute("story.tickets", ticket_list)
+        except ImportError:
+            pass  # opentelemetry not installed
+        except Exception:
+            pass  # OTel not available or no active span
+
+    def _get_meta(self) -> dict[str, Any] | None:
+        """Return the StoryMeta dict for the current test, or None."""
+        ctx = self._ctx
+        if ctx is None:
+            return None
+
+        result: dict[str, Any] = {"scenario": ctx.scenario}
+        if ctx.steps:
+            result["steps"] = list(ctx.steps)
+        if ctx.tags:
+            result["tags"] = list(ctx.tags)
+        if ctx.tickets:
+            result["tickets"] = list(ctx.tickets)
+        if ctx.meta:
+            result["meta"] = dict(ctx.meta)
+        if ctx.suite_path:
+            result["suitePath"] = list(ctx.suite_path)
+        if ctx.docs:
+            result["docs"] = list(ctx.docs)
+        if ctx.otel_spans:
+            result["otelSpans"] = ctx.otel_spans
+        return result
+
+    def _get_attachments(self) -> list[dict[str, Any]]:
+        """Return the attachments list for the current test."""
+        ctx = self._ctx
+        if ctx is None:
+            return []
+        return list(ctx.attachments)
+
+    def _require_context(self) -> _StoryContext:
+        """Return the current context or raise."""
+        ctx = self._ctx
+        if ctx is None:
+            raise RuntimeError("story method called before story.init()")
+        return ctx
+
+    def _clear(self) -> None:
+        """Clear the current test's story context."""
+        self._local.ctx = None
+
+    # ── BDD steps ──────────────────────────────────────────────────
+
+    def _add_step(
+        self,
+        keyword: str,
+        text: str,
+        *,
+        mode: str | None = None,
+        docs: list[dict[str, Any]] | None = None,
+    ) -> None:
+        ctx = self._ctx
+        if ctx is None:
+            raise RuntimeError(f"story.{keyword.lower()}() called before story.init()")
+        # 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["id"] = f"step-{ctx.step_counter}"
+        ctx.step_counter += 1
+        if mode is not None:
+            step["mode"] = mode
+        if docs:
+            step["docs"] = list(docs)
+        ctx.steps.append(step)
+        ctx._current_step = step
+
+    def given(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        self._add_step("Given", text, mode=mode, docs=docs)
+
+    def when(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        self._add_step("When", text, mode=mode, docs=docs)
+
+    def then(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        self._add_step("Then", text, mode=mode, docs=docs)
+
+    def and_(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        self._add_step("And", text, mode=mode, docs=docs)
+
+    def but(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        self._add_step("But", text, mode=mode, docs=docs)
+
+    # ── AAA pattern aliases ────────────────────────────────────────
+
+    def arrange(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add an Arrange step (alias for Given)."""
+        self._add_step("Given", text, mode=mode, docs=docs)
+
+    def act(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add an Act step (alias for When)."""
+        self._add_step("When", text, mode=mode, docs=docs)
+
+    def assert_(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add an Assert step (alias for Then). Uses assert_ because assert is reserved."""
+        self._add_step("Then", text, mode=mode, docs=docs)
+
+    # ── Additional aliases ─────────────────────────────────────────
+
+    def setup(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add a Setup step (alias for Given)."""
+        self._add_step("Given", text, mode=mode, docs=docs)
+
+    def context(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add a Context step (alias for Given)."""
+        self._add_step("Given", text, mode=mode, docs=docs)
+
+    def execute(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add an Execute step (alias for When)."""
+        self._add_step("When", text, mode=mode, docs=docs)
+
+    def action(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add an Action step (alias for When)."""
+        self._add_step("When", text, mode=mode, docs=docs)
+
+    def verify(self, text: str, *, docs: list[dict[str, Any]] | None = None, mode: str | None = None) -> None:
+        """Add a Verify step (alias for Then)."""
+        self._add_step("Then", text, mode=mode, docs=docs)
+
+    # ── Wrapped step execution ────────────────────────────────────
+
+    def fn(self, keyword: str, text: str, body: Callable[[], _T]) -> _T:
+        """Wrap a callable as a BDD step with automatic timing.
+
+        Creates a step marked as ``wrapped=True``, executes *body*,
+        records ``durationMs``, and re-raises any exception.
+        """
+        self._add_step(keyword, text)
+        ctx = self._require_context()
+        step = ctx._current_step
+        assert step is not None
+        step["wrapped"] = True
+
+        start = time.perf_counter()
+        try:
+            result = body()
+            return result
+        finally:
+            step["durationMs"] = (time.perf_counter() - start) * 1000.0
+
+    def expect(self, text: str, body: Callable[[], _T]) -> _T:
+        """Shorthand for ``fn("Then", text, body)``."""
+        return self.fn("Then", text, body)
+
+    # ── Step timing ────────────────────────────────────────────────
+
+    def start_timer(self) -> int:
+        """Start a high-resolution timer tied to the current step.
+        Returns a token to pass to end_timer().
+        """
+        ctx = self._require_context()
+        token = ctx.timer_counter
+        ctx.timer_counter += 1
+
+        entry: dict[str, Any] = {
+            "start": time.perf_counter(),
+            "consumed": False,
+        }
+        if ctx._current_step is not None:
+            entry["step_index"] = len(ctx.steps) - 1
+            entry["step_id"] = ctx._current_step.get("id")
+
+        ctx.active_timers[token] = entry
+        return token
+
+    def end_timer(self, token: int) -> None:
+        """Stop the timer and record durationMs on the step that was active
+        when start_timer() was called. Double-end is a no-op.
+        """
+        ctx = self._require_context()
+        entry = ctx.active_timers.get(token)
+        if entry is None or entry["consumed"]:
+            return
+        entry["consumed"] = True
+
+        duration_ms = (time.perf_counter() - entry["start"]) * 1000.0
+
+        step = None
+        step_id = entry.get("step_id")
+        if step_id is not None:
+            for s in ctx.steps:
+                if s.get("id") == step_id:
+                    step = s
+                    break
+        if step is None:
+            step_index = entry.get("step_index")
+            if step_index is not None and step_index < len(ctx.steps):
+                step = ctx.steps[step_index]
+
+        if step is not None:
+            step["durationMs"] = duration_ms
+
+    # ── attachments ───────────────────────────────────────────────
+
+    def attach(
+        self,
+        name: str,
+        media_type: str,
+        *,
+        path: str | None = None,
+        body: str | None = None,
+        encoding: str | None = None,
+        charset: str | None = None,
+        file_name: str | None = None,
+    ) -> "Story":
+        """Attach a file or inline content to the current test."""
+        ctx = self._require_context()
+        a: dict[str, Any] = {"name": name, "mediaType": media_type}
+        if path is not None:
+            a["path"] = path
+        if body is not None:
+            a["body"] = body
+        if encoding is not None:
+            a["encoding"] = encoding
+        if charset is not None:
+            a["charset"] = charset
+        if file_name is not None:
+            a["fileName"] = file_name
+        if ctx._current_step is not None:
+            steps = ctx.steps
+            idx = len(steps) - 1
+            a["stepIndex"] = idx
+            a["stepId"] = ctx._current_step.get("id")
+        ctx.attachments.append(a)
+        return self
+
+    def attach_spans(self, spans: list[dict[str, Any]]) -> "Story":
+        """Attach OTel spans for trace waterfall rendering in HTML reports."""
+        ctx = self._require_context()
+        ctx.otel_spans = spans
+        return self
+
+    # ── doc helpers ────────────────────────────────────────────────
+
+    def _attach_doc(self, entry: dict[str, Any]) -> None:
+        """Attach a doc entry to the current step or story-level docs."""
+        ctx = self._ctx
+        if ctx is None:
+            raise RuntimeError("Doc method called before story.init()")
+        if ctx.steps:
+            # Attach to last step
+            last = ctx.steps[-1]
+            if "docs" not in last:
+                last["docs"] = []
+            last["docs"].append(entry)
+        else:
+            # Attach to story-level docs
+            ctx.docs.append(entry)
+
+    def _current_step_docs(self) -> list[dict[str, Any]]:
+        """Return the docs list of the current (last) step."""
+        ctx = self._require_context()
+        last = ctx.steps[-1]
+        if "docs" not in last:
+            last["docs"] = []
+        return last["docs"]
+
+    def _story_docs(self) -> list[dict[str, Any]]:
+        """Return the story-level docs list."""
+        return self._require_context().docs
+
+    def _dedup_children(self, children: list[dict[str, Any]]) -> None:
+        """Remove children from all flat containers so they only appear nested."""
+        child_ids = {id(c) for c in children}
+        ctx = self._require_context()
+        ctx.docs[:] = [d for d in ctx.docs if id(d) not in child_ids]
+        for step in ctx.steps:
+            docs = step.get("docs")
+            if docs is not None:
+                step["docs"] = [d for d in docs if id(d) not in child_ids]
+
+    def _apply_children(self, entry: dict[str, Any], children: list[dict[str, Any]] | None) -> None:
+        """If children are provided, attach them and deduplicate."""
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+
+    def note(self, text: str, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a free-text note."""
+        entry: dict[str, Any] = {"kind": "note", "text": text, "phase": "runtime"}
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def tag(self, name_or_names: str | list[str], *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add tag(s) as a doc entry."""
+        names = [name_or_names] if isinstance(name_or_names, str) else list(name_or_names)
+        entry: dict[str, Any] = {"kind": "tag", "names": names, "phase": "runtime"}
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def kv(self, label: str, value: Any, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a key-value pair."""
+        entry: dict[str, Any] = {"kind": "kv", "label": label, "value": value, "phase": "runtime"}
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def json(self, label: str, value: Any, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a JSON code block (serialized with indent=2)."""
+        entry: dict[str, Any] = {
+            "kind": "code",
+            "label": label,
+            "content": json.dumps(value, indent=2),
+            "lang": "json",
+            "phase": "runtime",
+        }
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def code(self, label: str, content: str, *, lang: str | None = None, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a code block."""
+        entry: dict[str, Any] = {
+            "kind": "code",
+            "label": label,
+            "content": content,
+            "phase": "runtime",
+        }
+        if lang is not None:
+            entry["lang"] = lang
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def table(self, label: str, columns: list[str], rows: list[list[str]], *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a table."""
+        entry: dict[str, Any] = {
+            "kind": "table",
+            "label": label,
+            "columns": columns,
+            "rows": rows,
+            "phase": "runtime",
+        }
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def link(self, label: str, url: str, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a hyperlink."""
+        entry: dict[str, Any] = {"kind": "link", "label": label, "url": url, "phase": "runtime"}
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def section(self, title: str, markdown: str, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a titled markdown section."""
+        entry: dict[str, Any] = {
+            "kind": "section",
+            "title": title,
+            "markdown": markdown,
+            "phase": "runtime",
+        }
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def mermaid(self, code: str, *, title: str | None = None, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a Mermaid diagram."""
+        entry: dict[str, Any] = {"kind": "mermaid", "code": code, "phase": "runtime"}
+        if title is not None:
+            entry["title"] = title
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def screenshot(self, path: str, *, alt: str | None = None, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a screenshot reference."""
+        entry: dict[str, Any] = {"kind": "screenshot", "path": path, "phase": "runtime"}
+        if alt is not None:
+            entry["alt"] = alt
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+    def custom(self, type: str, data: Any, *, children: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Add a custom doc entry."""
+        entry: dict[str, Any] = {
+            "kind": "custom",
+            "type": type,
+            "data": data,
+            "phase": "runtime",
+        }
+        if children:
+            entry["children"] = children
+            self._dedup_children(children)
+        self._attach_doc(entry)
+        return entry
+
+
+# Module-level singleton
+story = Story()

executable_stories/_types.py

@@ -0,0 +1,206 @@
+"""Type definitions matching the raw-run.schema.json schema.
+
+These are plain TypedDicts used for documentation and type-checking.
+At runtime everything is just dicts serialized to JSON.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NotRequired, TypedDict
+
+# ── DocEntry variants ──────────────────────────────────────────────
+
+
+class NoteDoc(TypedDict):
+    kind: str  # "note"
+    text: str
+    phase: str  # "static" | "runtime"
+    children: NotRequired[list["DocEntry"]]
+
+
+class TagDoc(TypedDict):
+    kind: str  # "tag"
+    names: list[str]
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+class KvDoc(TypedDict):
+    kind: str  # "kv"
+    label: str
+    value: Any
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+class CodeDoc(TypedDict):
+    kind: str  # "code"
+    label: str
+    content: str
+    phase: str
+    lang: NotRequired[str]
+    children: NotRequired[list["DocEntry"]]
+
+
+class TableDoc(TypedDict):
+    kind: str  # "table"
+    label: str
+    columns: list[str]
+    rows: list[list[str]]
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+class LinkDoc(TypedDict):
+    kind: str  # "link"
+    label: str
+    url: str
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+class SectionDoc(TypedDict):
+    kind: str  # "section"
+    title: str
+    markdown: str
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+class MermaidDoc(TypedDict):
+    kind: str  # "mermaid"
+    code: str
+    phase: str
+    title: NotRequired[str]
+    children: NotRequired[list["DocEntry"]]
+
+
+class ScreenshotDoc(TypedDict):
+    kind: str  # "screenshot"
+    path: str
+    phase: str
+    alt: NotRequired[str]
+    children: NotRequired[list["DocEntry"]]
+
+
+class CustomDoc(TypedDict):
+    kind: str  # "custom"
+    type: str
+    data: Any
+    phase: str
+    children: NotRequired[list["DocEntry"]]
+
+
+# Union of all doc entry types
+DocEntry = NoteDoc | TagDoc | KvDoc | CodeDoc | TableDoc | LinkDoc | SectionDoc | MermaidDoc | ScreenshotDoc | CustomDoc
+
+
+# ── Ticket ────────────────────────────────────────────────────────
+
+
+class TicketDoc(TypedDict):
+    id: str
+    url: NotRequired[str]
+
+
+# ── Attachment ────────────────────────────────────────────────────
+
+
+class Attachment(TypedDict, total=False):
+    name: str
+    mediaType: str
+    path: str
+    body: str
+    encoding: str  # "BASE64" | "IDENTITY"
+    charset: str
+    fileName: str
+    byteLength: int
+    stepIndex: int
+    stepId: str
+
+
+# ── RawStepEvent ──────────────────────────────────────────────────
+
+
+class RawStepEvent(TypedDict, total=False):
+    index: int
+    title: str
+    status: str
+    durationMs: float
+
+
+# ── StoryStep ──────────────────────────────────────────────────────
+
+
+class StoryStep(TypedDict):
+    keyword: str  # "Given" | "When" | "Then" | "And" | "But"
+    text: str
+    id: NotRequired[str]
+    mode: NotRequired[str]
+    wrapped: NotRequired[bool]
+    durationMs: NotRequired[float]
+    docs: NotRequired[list[DocEntry]]
+
+
+# ── StoryMeta ──────────────────────────────────────────────────────
+
+
+class StoryMeta(TypedDict):
+    scenario: str
+    steps: NotRequired[list[StoryStep]]
+    tags: NotRequired[list[str]]
+    tickets: NotRequired[list[TicketDoc]]
+    meta: NotRequired[dict[str, Any]]
+    suitePath: NotRequired[list[str]]
+    docs: NotRequired[list[DocEntry]]
+    sourceOrder: NotRequired[int]
+
+
+# ── RawTestCase ────────────────────────────────────────────────────
+
+
+class ErrorInfo(TypedDict, total=False):
+    message: str
+    stack: str
+
+
+class RawTestCase(TypedDict):
+    status: str  # "pass" | "fail" | "skip" | ...
+    externalId: NotRequired[str]
+    title: NotRequired[str]
+    titlePath: NotRequired[list[str]]
+    story: NotRequired[StoryMeta]
+    sourceFile: NotRequired[str]
+    sourceLine: NotRequired[int]
+    durationMs: NotRequired[float]
+    error: NotRequired[ErrorInfo]
+    meta: NotRequired[dict[str, Any]]
+    retry: NotRequired[int]
+    retries: NotRequired[int]
+    attachments: NotRequired[list[Attachment]]
+    stepEvents: NotRequired[list[RawStepEvent]]
+    projectName: NotRequired[str]
+
+
+# ── RawCIInfo ──────────────────────────────────────────────────────
+
+
+class RawCIInfo(TypedDict):
+    name: str
+    url: NotRequired[str]
+    buildNumber: NotRequired[str]
+
+
+# ── RawRun ─────────────────────────────────────────────────────────
+
+
+class RawRun(TypedDict):
+    schemaVersion: int  # must be 1
+    testCases: list[RawTestCase]
+    projectRoot: str
+    startedAtMs: NotRequired[float]
+    finishedAtMs: NotRequired[float]
+    packageVersion: NotRequired[str]
+    gitSha: NotRequired[str]
+    ci: NotRequired[RawCIInfo]
+    meta: NotRequired[dict[str, Any]]

executable_stories_pytest-0.1.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: executable-stories-pytest
+Version: 0.1.0
+Summary: pytest plugin for executable-stories BDD documentation
+Author: Jag Reehal
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jagreehal/executable-stories
+Project-URL: Repository, https://github.com/jagreehal/executable-stories.git
+Project-URL: Documentation, https://github.com/jagreehal/executable-stories#readme
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+
+# executable-stories-pytest
+
+pytest plugin for executable-stories.
+
+Adds BDD-style story helpers and structured story metadata so pytest tests can generate executable documentation.

executable_stories_pytest-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+executable_stories/__init__.py,sha256=X-m5x5nt_kkzd8IGJZ52e6lfr6aDArhbXci9K0fLWLM,132
+executable_stories/_collector.py,sha256=JCl4crRHdAx1qqqW6ia7ABWi2yG4NN91IPZgB-VWVOs,932
+executable_stories/_json_writer.py,sha256=l0wlGiijxTtEzdQ4N0oQJZI4uEHer-aIAUNlFQ-wgws,528
+executable_stories/_plugin.py,sha256=f-QhkcyndouaymIiM38GOg63HRrvVN9U7lXnIiZZAyA,7190
+executable_stories/_story_api.py,sha256=jOSf4-9MJGumVGhlKrX6hbEsD7tXY3V0D99Fxp3wGMw,21381
+executable_stories/_types.py,sha256=iIoBdZ63eT6TIkimO7o_PXMzVSBBsope5L4gGL5ulAw,5648
+executable_stories_pytest-0.1.0.dist-info/METADATA,sha256=nQLaU3J04FiaKUgN1wGAxJqYBk5Ho3wqimVZl_aP_oY,882
+executable_stories_pytest-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+executable_stories_pytest-0.1.0.dist-info/entry_points.txt,sha256=NXzZqAD31EI6q3ovbbWQE7VOzsok09tPpmd-QPgSTiE,59
+executable_stories_pytest-0.1.0.dist-info/top_level.txt,sha256=0CmAUpeJrtl-ykfogdr3L373JMtP92uU1P7-GIlbF7I,19
+executable_stories_pytest-0.1.0.dist-info/RECORD,,

executable_stories_pytest-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

executable_stories_pytest-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+executable_stories = executable_stories._plugin

executable_stories_pytest-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+executable_stories