tracera-pytest 0.1.0rc1__tar.gz

tracera_pytest-0.1.0rc1/.gitignore

@@ -0,0 +1 @@
+# Package-local stub so hatchling sdist does not embed the monorepo root .gitignore.

tracera_pytest-0.1.0rc1/LICENSE.md

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Tracera. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Tracera.
+
+No license to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software is granted by default. Any use of the
+Software requires a separate written agreement with Tracera.
+
+Unauthorized use, reproduction, or distribution of the Software, in whole
+or in part, is strictly prohibited and may result in civil and criminal
+penalties.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+TRACERA BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+This is a draft notice pending a full commercial license / EULA.
+Third-party open-source components included with or used by the Software
+remain subject to their respective licenses.

tracera_pytest-0.1.0rc1/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: tracera-pytest
+Version: 0.1.0rc1
+Summary: Tracera Autotest adapter for pytest
+Project-URL: Homepage, https://tracera.dev/docs/pytest
+Project-URL: Bug-Tracker, https://github.com/tracera-dev/tracera-releases/issues
+Author-email: Tracera <contact@tracera.dev>
+License: SEE LICENSE IN LICENSE.md
+License-File: LICENSE.md
+Keywords: autotest,pytest,test-reporting,testops,tracera
+Requires-Python: >=3.11
+Requires-Dist: tracera-core==0.1.0rc1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tracera-pytest
+
+Tracera Autotest adapter for pytest.
+
+**Requires Python ≥ 3.11 and pytest ≥ 8.**
+
+```bash
+pip install tracera-pytest
+```
+
+How-to: [pytest](https://tracera.dev/docs/pytest). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+The package registers as a pytest plugin automatically (no `-p` flag).
+
+```python
+import pytest
+from tracera_pytest import id as tracera_id
+from tracera_pytest import tracera
+
+
+@tracera_id(42, "e2e/login")
+def test_login():
+    tracera.step("open login", lambda: None)
+```
+
+## Bind
+
+`@tracera.id(…)` (preferred) or `tracera.test_case`. Optional name may use `{param}` / `{param_id}` from pytest parametrize. If `name` is omitted → `item.name`.
+
+## Skip
+
+Stock `pytest.skip`. The reason becomes a result `comment`.
+
+## Steps
+
+`tracera.step(title, body)`, `@tracera.step("…")`, `with tracera.step("…"):`, or `async with tracera.step("…"):` (async `def` / awaitable bodies OK; decorator `{name}` / `{0}` from args). **Function-scoped** fixtures → **Setup** / **Teardown**; suite-level fixtures are not reported.
+
+## Comments, errors, and attachments
+
+`tracera.comment` / `tracera.error` / `tracera.attachment` — see [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Parameterized
+
+`@pytest.mark.parametrize` + `@tracera.id(id, "login as {login}")`. Retries: final attempt only; `PYTEST_RETRY` on Env when retry > 0.

tracera_pytest-0.1.0rc1/README.md

@@ -0,0 +1,46 @@
+# tracera-pytest
+
+Tracera Autotest adapter for pytest.
+
+**Requires Python ≥ 3.11 and pytest ≥ 8.**
+
+```bash
+pip install tracera-pytest
+```
+
+How-to: [pytest](https://tracera.dev/docs/pytest). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+The package registers as a pytest plugin automatically (no `-p` flag).
+
+```python
+import pytest
+from tracera_pytest import id as tracera_id
+from tracera_pytest import tracera
+
+
+@tracera_id(42, "e2e/login")
+def test_login():
+    tracera.step("open login", lambda: None)
+```
+
+## Bind
+
+`@tracera.id(…)` (preferred) or `tracera.test_case`. Optional name may use `{param}` / `{param_id}` from pytest parametrize. If `name` is omitted → `item.name`.
+
+## Skip
+
+Stock `pytest.skip`. The reason becomes a result `comment`.
+
+## Steps
+
+`tracera.step(title, body)`, `@tracera.step("…")`, `with tracera.step("…"):`, or `async with tracera.step("…"):` (async `def` / awaitable bodies OK; decorator `{name}` / `{0}` from args). **Function-scoped** fixtures → **Setup** / **Teardown**; suite-level fixtures are not reported.
+
+## Comments, errors, and attachments
+
+`tracera.comment` / `tracera.error` / `tracera.attachment` — see [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Parameterized
+
+`@pytest.mark.parametrize` + `@tracera.id(id, "login as {login}")`. Retries: final attempt only; `PYTEST_RETRY` on Env when retry > 0.

tracera_pytest-0.1.0rc1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "tracera-pytest"
+version = "0.1.0rc1"
+description = "Tracera Autotest adapter for pytest"
+readme = "README.md"
+license = { text = "SEE LICENSE IN LICENSE.md" }
+authors = [{ name = "Tracera", email = "contact@tracera.dev" }]
+requires-python = ">=3.11"
+keywords = ["tracera", "autotest", "pytest", "test-reporting", "testops"]
+dependencies = [
+  "tracera-core==0.1.0rc1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.entry-points.pytest11]
+tracera = "tracera_pytest.plugin"
+
+[project.urls]
+Homepage = "https://tracera.dev/docs/pytest"
+Bug-Tracker = "https://github.com/tracera-dev/tracera-releases/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracera_pytest"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/tracera_pytest" = "tracera_pytest"
+
+# Publish surface: runtime package + docs only (no tests / harness / gitignore).
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/tracera_pytest",
+  "LICENSE.md",
+  "README.md",
+]

tracera_pytest-0.1.0rc1/src/tracera_pytest/__init__.py

@@ -0,0 +1,8 @@
+"""Tracera Autotest adapter for pytest."""
+
+from __future__ import annotations
+
+from tracera_pytest.annotations import id
+from tracera_pytest.runtime import tracera
+
+__all__ = ["tracera", "id"]

tracera_pytest-0.1.0rc1/src/tracera_pytest/annotations.py

@@ -0,0 +1,29 @@
+"""Declarative bind: ``@tracera.id(42)`` / ``@tracera.id(42, "name")``."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+import pytest
+
+from tracera.bind import make_bind
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def id(test_case_id: int, autotest_name: str | None = None) -> Callable[[F], F]:
+    """
+    Bind a pytest test to a Tracera case (preferred declarative form).
+
+    Applies ``pytest.mark.tracera(id=…, name=…)`` so early skip still reports.
+
+    Optional ``autotest_name`` may include ``{param}`` / ``{param_id}`` placeholders;
+    the plugin fills them from pytest parametrize values when the test starts.
+    """
+    bind = make_bind(test_case_id, autotest_name)
+    mark = pytest.mark.tracera(id=bind.test_case_id, name=bind.autotest_name)
+
+    def decorator(fn: F) -> F:
+        return mark(fn)
+
+    return decorator

tracera_pytest-0.1.0rc1/src/tracera_pytest/plugin.py

@@ -0,0 +1,353 @@
+"""pytest plugin: session lifecycle, bind, Setup/Test/Teardown phases."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Generator
+
+import pytest
+
+from tracera import (
+    run_with_context,
+)
+from tracera.buffer import PendingResult
+from tracera.context import (
+    create_test_context,
+    format_title,
+    record_failure,
+    record_skip,
+    set_phase,
+    snapshot_payload,
+    suspend_reporting_context,
+)
+from tracera.env_extras import build_env_vars_extra
+from tracera.materialize import payload_has_step_error
+from tracera.pending import (
+    discard_pending_blobs,
+    pending_blobs_for_payload,
+    resolve_pending_attachments,
+)
+from tracera.registry import registry_set
+from tracera.session import (
+    begin_reporting,
+    create_reporter_state,
+    duration_minutes_from_ms,
+    end_reporting,
+)
+from tracera_pytest import state as st
+
+_reporter = create_reporter_state()
+_final_reports: dict[str, dict[str, Any]] = {}
+
+
+def _fixture_scope_name(fixturedef: Any) -> str:
+    scope = getattr(fixturedef, "scope", "function")
+    value = getattr(scope, "value", scope)
+    return str(value)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "tracera(id, name=None): bind test to Tracera testCaseId (and optional autotestName)",
+    )
+
+
+@pytest.hookimpl(optionalhook=True)
+def pytest_configure_node(node: Any) -> None:
+    """xdist master: create owned run once and hand the id to each worker."""
+    if _reporter.session is None and not _reporter.soft_disabled:
+        begin_reporting(_reporter)
+    session = _reporter.session
+    if session is not None:
+        node.workerinput["tracera_test_run_id"] = session.test_run_id
+
+
+def pytest_sessionstart(session: pytest.Session) -> None:
+    st.clear_state()
+    _final_reports.clear()
+    workerinput = getattr(session.config, "workerinput", None)
+    if isinstance(workerinput, dict):
+        run_id = workerinput.get("tracera_test_run_id")
+        if run_id is not None:
+            import os
+
+            os.environ["TRACERA_TEST_RUN_ID"] = str(run_id)
+        begin_reporting(_reporter)
+        return
+    if _reporter.session is not None or _reporter.soft_disabled:
+        # Already started in pytest_configure_node (xdist master).
+        return
+    begin_reporting(_reporter)
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    if (
+        _reporter.soft_disabled
+        or not _reporter.session
+        or not _reporter.buffer
+        or not _reporter.upload_pool
+    ):
+        for row in _final_reports.values():
+            discard_pending_blobs(
+                row.get("payload") or {},
+                take_blob=lambda aid, blobs=dict(row.get("pending_blobs") or {}): (
+                    blobs.pop(aid, None) or st.take_pending_blob(aid)
+                ),
+            )
+        st.clear_pending_blobs()
+        end_reporting(_reporter)
+        return
+
+    for row in _final_reports.values():
+        ctx = row["ctx"]
+        payload = row["payload"]
+        status = row["status"]
+        duration_ms = row["duration_ms"]
+        retry = row.get("retry", 0)
+        env_vars_extra = build_env_vars_extra(
+            retry=retry,
+            retry_key="PYTEST_RETRY",
+            package_ids=["pytest"],
+            version_key="PYTEST_VERSION",
+        )
+        duration_minutes = duration_minutes_from_ms(duration_ms)
+        session_ref = _reporter.session
+        buffer = _reporter.buffer
+        upload_pool = _reporter.upload_pool
+
+        def job(
+            ctx=ctx,
+            payload=payload,
+            status=status,
+            duration_minutes=duration_minutes,
+            env_vars_extra=env_vars_extra,
+            pending_blobs=dict(row.get("pending_blobs") or {}),
+        ) -> None:
+            if not session_ref.reporting_enabled:
+                discard_pending_blobs(
+                    payload,
+                    take_blob=lambda aid: pending_blobs.pop(aid, None) or st.take_pending_blob(aid),
+                )
+                return
+            upload_errors = resolve_pending_attachments(
+                session_ref.client,
+                payload,
+                resolve_blob=lambda aid: pending_blobs.get(aid) or st.take_pending_blob(aid),
+            )
+            if upload_errors:
+                session_ref.set_last_error(upload_errors[0])
+                if session_ref.config.require_report:
+                    session_ref.note_failed_report()
+                    session_ref.note_unsent_results()
+                    return
+            buffer.enqueue(
+                PendingResult(
+                    ctx=ctx,
+                    status=status,
+                    duration_minutes=duration_minutes,
+                    payload=payload,
+                    env_vars_extra=env_vars_extra,
+                )
+            )
+
+        upload_pool.enqueue(job)
+
+    end_reporting(_reporter)
+
+
+def _callspec_title_values(item: pytest.Item) -> dict[str, Any]:
+    callspec = getattr(item, "callspec", None)
+    if callspec is None:
+        return {}
+    values: dict[str, Any] = dict(getattr(callspec, "params", {}) or {})
+    cid = getattr(callspec, "id", None)
+    if isinstance(cid, str) and cid:
+        values.setdefault("param_id", cid)
+    return values
+
+
+def _resolve_autotest_name(bind_name: str | None, item: pytest.Item) -> str:
+    if bind_name:
+        return format_title(bind_name, _callspec_title_values(item))[:128]
+    return item.name[:128]
+
+
+def _read_bind(item: pytest.Item) -> tuple[int | None, str | None]:
+    marker = item.get_closest_marker("tracera")
+    if marker is None:
+        return None, None
+    case_id = marker.kwargs.get("id")
+    if case_id is None and marker.args:
+        case_id = marker.args[0]
+    try:
+        n = int(case_id) if case_id is not None else 0
+    except (TypeError, ValueError):
+        n = 0
+    name = marker.kwargs.get("name")
+    return (n if n > 0 else None), (name if isinstance(name, str) else None)
+
+
+def _skip_reason(report: pytest.TestReport) -> str | None:
+    longrepr = report.longrepr
+    if isinstance(longrepr, tuple) and len(longrepr) >= 3:
+        text = str(longrepr[2])
+        return text if text.strip() else None
+    if longrepr is not None:
+        text = str(longrepr)
+        return text if text.strip() else None
+    return None
+
+
+def _failure_source(call: pytest.CallInfo[Any], report: pytest.TestReport) -> Any:
+    """Prefer full traceback text; fall back to ExceptionInfo / longrepr."""
+    # longreprtext is pytest's formatted report (includes Traceback) — richest + stable.
+    text = getattr(report, "longreprtext", None)
+    if isinstance(text, str) and text.strip():
+        return text
+    if call.excinfo is not None:
+        return call.excinfo
+    return report.longrepr
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_fixture_setup(fixturedef: Any, request: Any) -> Generator[None, None, None]:
+    """Session/module/class fixtures must not record steps onto the active test."""
+    if _fixture_scope_name(fixturedef) == "function":
+        yield
+        return
+    st.set_reporting_suspended(True)
+    try:
+        with suspend_reporting_context():
+            yield
+    finally:
+        st.set_reporting_suspended(False)
+
+    def _suspend_before_teardown() -> None:
+        st.set_reporting_suspended(True)
+        suspend_reporting_context().__enter__()
+
+    fixturedef.addfinalizer(_suspend_before_teardown)
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_runtest_setup(item: pytest.Item) -> None:
+    st.set_reporting_suspended(False)
+    key = st.registry_key(item.nodeid)
+    attempt = st.note_attempt(key)
+    st.set_current_key(key)
+    case_id, bind_name = _read_bind(item)
+    ctx = create_test_context(
+        test_case_id=case_id,
+        autotest_name=_resolve_autotest_name(bind_name, item),
+    )
+    registry_set(key, ctx)
+    item._tracera_ctx = ctx  # type: ignore[attr-defined]
+    item._tracera_started = time.time()  # type: ignore[attr-defined]
+    item._tracera_attempt = attempt  # type: ignore[attr-defined]
+    item._tracera_token = run_with_context(ctx)  # type: ignore[attr-defined]
+    item._tracera_token.__enter__()  # type: ignore[attr-defined]
+    set_phase("setup")
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_runtest_call(item: pytest.Item) -> None:
+    ctx = getattr(item, "_tracera_ctx", None)
+    if ctx is not None:
+        set_phase("test")
+
+
+@pytest.hookimpl(hookwrapper=True, tryfirst=True)
+def pytest_runtest_teardown(
+    item: pytest.Item, nextitem: pytest.Item | None
+) -> Generator[None, None, None]:
+    # tryfirst so phase is Teardown before fixture teardown runs (default hook).
+    ctx = getattr(item, "_tracera_ctx", None)
+    if ctx is not None:
+        set_phase("teardown")
+    yield
+    _ = nextitem
+    # Drop registry fallback so module/session teardown cannot append onto the last test.
+    st.set_current_key(None)
+    st.set_reporting_suspended(True)
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(
+    item: pytest.Item, call: pytest.CallInfo[Any]
+) -> Generator[None, None, None]:
+    outcome = yield
+    assert outcome is not None
+    report: pytest.TestReport = outcome.get_result()
+    ctx = getattr(item, "_tracera_ctx", None)
+    if ctx is None:
+        return
+
+    if call.when == "setup":
+        if report.skipped:
+            record_skip(ctx, _skip_reason(report))
+            _store_final(item, ctx, "Skipped")
+        elif report.failed:
+            if not payload_has_step_error(snapshot_payload(ctx)):
+                record_failure(ctx, _failure_source(call, report))
+            _store_final(item, ctx, "Failed")
+        return
+
+    if call.when == "call":
+        if report.skipped:
+            record_skip(ctx, _skip_reason(report))
+            _store_final(item, ctx, "Skipped")
+        elif report.failed:
+            if not payload_has_step_error(snapshot_payload(ctx)):
+                record_failure(ctx, _failure_source(call, report))
+            _store_final(item, ctx, "Failed")
+        elif report.passed:
+            _store_final(item, ctx, "Passed")
+        return
+
+    if call.when == "teardown":
+        key = st.registry_key(item.nodeid)
+        row = _final_reports.get(key)
+        if row is None:
+            _store_final(item, ctx, "Passed")
+            row = _final_reports.get(key)
+        if row is not None:
+            payload = snapshot_payload(ctx)
+            status = row["status"]
+            if status == "Passed":
+                failed_step = any(
+                    isinstance(s, dict) and s.get("result") == "Failed"
+                    for s in (payload["setup"] + payload["test"] + payload["teardown"])
+                )
+                if failed_step or ctx.result_error:
+                    status = "Failed"
+            row["payload"] = payload
+            row["status"] = status
+            row["duration_ms"] = (
+                time.time() - getattr(item, "_tracera_started", time.time())
+            ) * 1000
+            # Snapshot pending blobs used by this test (payload-referenced only).
+            row["pending_blobs"] = pending_blobs_for_payload(st._pending_blobs, payload)  # noqa: SLF001
+        # Close context
+        token_cm = getattr(item, "_tracera_token", None)
+        if token_cm is not None:
+            try:
+                token_cm.__exit__(None, None, None)
+            except Exception:
+                pass
+            item._tracera_token = None  # type: ignore[attr-defined]
+
+
+def _store_final(item: pytest.Item, ctx: Any, status: str) -> None:
+    key = st.registry_key(item.nodeid)
+    attempt = getattr(item, "_tracera_attempt", 0)
+    started = getattr(item, "_tracera_started", time.time())
+    payload = snapshot_payload(ctx)
+    _final_reports[key] = {
+        "ctx": ctx,
+        "payload": payload,
+        "status": status,
+        "duration_ms": (time.time() - started) * 1000,
+        "retry": attempt,
+        "pending_blobs": {},
+    }

tracera_pytest-0.1.0rc1/src/tracera_pytest/runtime.py

@@ -0,0 +1,250 @@
+"""Runtime API for pytest."""
+
+from __future__ import annotations
+
+import inspect
+import uuid
+from contextlib import nullcontext
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, TypeVar, overload
+
+from tracera import get_context, run_with_context
+from tracera.context import (
+    AttachmentMeta,
+    StepContext,
+    TestContext,
+    format_step_title,
+)
+from tracera.registry import registry_get
+from tracera.runtime import create_tracera_runtime
+from tracera_pytest import state as st
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable[..., Any])
+
+_base = create_tracera_runtime()
+
+
+def _ensure_ctx() -> TestContext | None:
+    if st.reporting_suspended():
+        return None
+    ctx = get_context()
+    if ctx is not None:
+        return ctx
+    # Fallback: current node key from state
+    key = st.current_key()
+    if key:
+        existing = registry_get(key)
+        if existing:
+            return existing
+    return None
+
+
+def _run_step_body(title: str, body: Callable[[], T]) -> T:
+    ctx = _ensure_ctx()
+    if ctx is not None:
+        with run_with_context(ctx):
+            return _base.step(title, body)  # type: ignore[return-value]
+    if st.reporting_suspended():
+        return body()
+    return _base.step(title, body)  # type: ignore[return-value]
+
+
+def test_case(test_case_id: int, autotest_name: str | None = None) -> None:
+    """Imperative bind to a Tracera test case (optional result name). Prefer ``@tracera.id``."""
+    ctx = _ensure_ctx()
+    if ctx is not None:
+        ctx.test_case_id = test_case_id
+        if autotest_name:
+            ctx.autotest_name = autotest_name[:128]
+        with run_with_context(ctx):
+            _base.test_case(test_case_id, autotest_name)
+        return
+    _base.test_case(test_case_id, autotest_name)
+
+
+class _EnsuredStep:
+    """Re-bind pytest registry context for decorator / ``with`` / ``async with`` forms."""
+
+    def __init__(self, inner: StepContext) -> None:
+        self._inner = inner
+        self._token: Any = nullcontext()
+
+    def __enter__(self) -> StepContext:
+        if st.reporting_suspended():
+            self._dropped = True
+            self._token = nullcontext()
+            return self._inner
+        self._dropped = False
+        ctx = _ensure_ctx()
+        self._token = run_with_context(ctx) if ctx is not None else nullcontext()
+        self._token.__enter__()
+        return self._inner.__enter__()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: Any,
+    ) -> bool:
+        if getattr(self, "_dropped", False):
+            return False
+        try:
+            return self._inner.__exit__(exc_type, exc, tb)
+        finally:
+            self._token.__exit__(exc_type, exc, tb)
+
+    async def __aenter__(self) -> StepContext:
+        if st.reporting_suspended():
+            self._dropped = True
+            self._token = nullcontext()
+            return self._inner
+        self._dropped = False
+        ctx = _ensure_ctx()
+        self._token = run_with_context(ctx) if ctx is not None else nullcontext()
+        self._token.__enter__()
+        return await self._inner.__aenter__()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: Any,
+    ) -> bool:
+        if getattr(self, "_dropped", False):
+            return False
+        try:
+            return await self._inner.__aexit__(exc_type, exc, tb)
+        finally:
+            self._token.__exit__(exc_type, exc, tb)
+
+    def __call__(self, fn: F) -> F:
+        if inspect.iscoroutinefunction(fn):
+
+            @wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                title = format_step_title(self._inner.title, fn, args, kwargs)
+                async with _EnsuredStep(StepContext(title)):
+                    return await fn(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            title = format_step_title(self._inner.title, fn, args, kwargs)
+            with _EnsuredStep(StepContext(title)):
+                return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+
+@overload
+def step(title: str, body: Callable[[], T]) -> T: ...
+
+
+@overload
+def step(title: str, body: None = None) -> _EnsuredStep: ...
+
+
+@overload
+def step(title: F) -> F: ...
+
+
+def step(title: str | F, body: Callable[[], T] | None = None) -> T | _EnsuredStep | F:
+    """Record a step — call / decorator / ``with`` / ``async with`` (same forms as ``tracera.step``)."""
+    if callable(title) and body is None:
+        return _EnsuredStep(StepContext(title.__name__))(title)
+    if body is not None:
+        return _run_step_body(str(title), body)
+    return _EnsuredStep(_base.step(str(title)))  # type: ignore[arg-type]
+
+
+def comment(text: str) -> None:
+    """Comment on the open step, or on the result when no step is open."""
+    if st.reporting_suspended():
+        return
+    ctx = _ensure_ctx()
+    if ctx is not None:
+        with run_with_context(ctx):
+            _base.comment(text)
+        return
+    _base.comment(text)
+
+
+def error(text: str) -> None:
+    """Soft error text on the open step (or result). Does not by itself fail the test."""
+    if st.reporting_suspended():
+        return
+    ctx = _ensure_ctx()
+    if ctx is not None:
+        with run_with_context(ctx):
+            _base.error(text)
+        return
+    _base.error(text)
+
+
+def attachment(
+    meta: AttachmentMeta | dict[str, Any] | None = None,
+    *,
+    file_name: str | None = None,
+    mime_type: str | None = None,
+    data: bytes | str | None = None,
+    path: str | None = None,
+) -> None:
+    """Attach a file (pending upload) or an already-uploaded AttachmentMeta."""
+    if st.reporting_suspended():
+        return
+    ctx = _ensure_ctx()
+
+    def _do() -> None:
+        if isinstance(meta, AttachmentMeta) or (
+            isinstance(meta, dict) and "attachmentId" in meta and data is None and path is None
+        ):
+            _base.attachment(meta)  # type: ignore[arg-type]
+            return
+        fname = file_name
+        mime = mime_type or "application/octet-stream"
+        blob_data = data
+        blob_path = path
+        if isinstance(meta, dict) and data is None and path is None and "attachmentId" not in meta:
+            fname = meta.get("fileName") or meta.get("file_name") or fname
+            mime = meta.get("mimeType") or meta.get("mime_type") or mime
+            blob_data = meta.get("data")
+            blob_path = meta.get("path")
+        if not fname:
+            fname = Path(blob_path).name if blob_path else "attachment.bin"
+        if isinstance(blob_data, str):
+            blob_data = blob_data.encode("utf-8")
+        pending_id = f"pending:{uuid.uuid4()}"
+        st.register_pending_blob(
+            pending_id,
+            {"fileName": fname, "mimeType": mime, "data": blob_data, "path": blob_path},
+        )
+        _base.attachment({"attachmentId": pending_id, "fileName": fname, "mimeType": mime})
+
+    if ctx is not None:
+        with run_with_context(ctx):
+            _do()
+    else:
+        _do()
+
+
+class _TraceraApi:
+    test_case = staticmethod(test_case)
+    step = staticmethod(step)
+    comment = staticmethod(comment)
+    error = staticmethod(error)
+    attachment = staticmethod(attachment)
+    reserve_attachment = staticmethod(_base.reserve_attachment)
+    get_context = staticmethod(get_context)
+    run_with_context = staticmethod(run_with_context)
+    id: object | None = None  # patched below
+
+
+tracera = _TraceraApi()
+
+# Prefer ``from tracera_pytest import tracera, id`` — also expose ``tracera.id``.
+from tracera_pytest.annotations import id as _id  # noqa: E402
+
+tracera.id = _id

tracera_pytest-0.1.0rc1/src/tracera_pytest/state.py

@@ -0,0 +1,66 @@
+"""Per-test state for the pytest plugin (pending blobs, attempt counters)."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+_pending_blobs: dict[str, dict[str, Any]] = {}
+_attempts: dict[str, int] = {}
+_current_key: ContextVar[str | None] = ContextVar("tracera_pytest_current_key", default=None)
+_reporting_suspended: bool = False
+
+
+def set_current_key(key: str | None) -> None:
+    _current_key.set(key)
+
+
+def current_key() -> str | None:
+    return _current_key.get()
+
+
+def set_reporting_suspended(suspended: bool) -> None:
+    global _reporting_suspended
+    _reporting_suspended = suspended
+
+
+def reporting_suspended() -> bool:
+    return _reporting_suspended
+
+
+def registry_key(nodeid: str) -> str:
+    return f"pytest:{nodeid}"
+
+
+def note_attempt(key: str) -> int:
+    n = _attempts.get(key, -1) + 1
+    _attempts[key] = n
+    return n
+
+
+def register_pending_blob(pending_id: str, blob: dict[str, Any]) -> None:
+    # Path wins: drop in-memory data when a path is present (memory hygiene).
+    path = blob.get("path")
+    if isinstance(path, str) and path.strip():
+        _pending_blobs[pending_id] = {
+            "fileName": blob.get("fileName") or "attachment.bin",
+            "mimeType": blob.get("mimeType") or "application/octet-stream",
+            "path": path,
+        }
+        return
+    _pending_blobs[pending_id] = blob
+
+
+def take_pending_blob(pending_id: str) -> dict[str, Any] | None:
+    return _pending_blobs.pop(pending_id, None)
+
+
+def clear_pending_blobs() -> None:
+    _pending_blobs.clear()
+
+
+def clear_state() -> None:
+    _pending_blobs.clear()
+    _attempts.clear()
+    set_current_key(None)
+    set_reporting_suspended(False)