tracera-playwright 0.1.0rc1__tar.gz

tracera_playwright-0.1.0rc1/.gitignore

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

tracera_playwright-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_playwright-0.1.0rc1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: tracera-playwright
+Version: 0.1.0rc1
+Summary: Tracera Autotest adapter for Playwright (Python)
+Project-URL: Homepage, https://tracera.dev/docs/playwright-python
+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,playwright,pytest,test-reporting,testops,tracera
+Requires-Python: >=3.11
+Requires-Dist: tracera-core==0.1.0rc1
+Provides-Extra: dev
+Requires-Dist: playwright>=1.40; extra == 'dev'
+Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tracera-playwright
+
+Tracera Autotest adapter for Playwright for Python (pytest plugin).
+
+**Requires Python ≥ 3.11, pytest ≥ 8, and Playwright ≥ 1.40.**
+
+```bash
+pip install tracera-playwright
+```
+
+How-to: [Playwright Python](https://tracera.dev/docs/playwright-python). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+The package registers as a pytest plugin automatically. Do **not** load `tracera-pytest` and `tracera-playwright` in the same pytest run.
+
+```python
+from tracera_playwright import id as tracera_id
+from tracera_playwright import tracera
+
+
+@tracera_id(42, "e2e/login")
+def test_login(page):
+    page.goto("/login")
+    tracera.step("assert signed in", 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` / `async with tracera.step("…"):`. Function-scoped fixtures → **Setup** / **Teardown**; suite-level fixtures are not reported. Video / trace attach to the result when present under the test output dir.
+
+## 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; `PLAYWRIGHT_RETRY` on Env when retry > 0.

tracera_playwright-0.1.0rc1/README.md

@@ -0,0 +1,46 @@
+# tracera-playwright
+
+Tracera Autotest adapter for Playwright for Python (pytest plugin).
+
+**Requires Python ≥ 3.11, pytest ≥ 8, and Playwright ≥ 1.40.**
+
+```bash
+pip install tracera-playwright
+```
+
+How-to: [Playwright Python](https://tracera.dev/docs/playwright-python). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+The package registers as a pytest plugin automatically. Do **not** load `tracera-pytest` and `tracera-playwright` in the same pytest run.
+
+```python
+from tracera_playwright import id as tracera_id
+from tracera_playwright import tracera
+
+
+@tracera_id(42, "e2e/login")
+def test_login(page):
+    page.goto("/login")
+    tracera.step("assert signed in", 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` / `async with tracera.step("…"):`. Function-scoped fixtures → **Setup** / **Teardown**; suite-level fixtures are not reported. Video / trace attach to the result when present under the test output dir.
+
+## 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; `PLAYWRIGHT_RETRY` on Env when retry > 0.

tracera_playwright-0.1.0rc1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "tracera-playwright"
+version = "0.1.0rc1"
+description = "Tracera Autotest adapter for Playwright (Python)"
+readme = "README.md"
+license = { text = "SEE LICENSE IN LICENSE.md" }
+authors = [{ name = "Tracera", email = "contact@tracera.dev" }]
+requires-python = ">=3.11"
+keywords = ["tracera", "autotest", "playwright", "pytest", "test-reporting", "testops"]
+dependencies = [
+  "tracera-core==0.1.0rc1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "playwright>=1.40", "pytest-playwright>=0.5"]
+
+[project.entry-points.pytest11]
+tracera_playwright = "tracera_playwright.plugin"
+
+[project.urls]
+Homepage = "https://tracera.dev/docs/playwright-python"
+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_playwright"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/tracera_playwright" = "tracera_playwright"
+
+# Publish surface: runtime package + docs only (no tests / harness / gitignore).
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/tracera_playwright",
+  "LICENSE.md",
+  "README.md",
+]

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

@@ -0,0 +1,8 @@
+"""Tracera Autotest adapter for Playwright (Python)."""
+
+from __future__ import annotations
+
+from tracera_playwright.annotations import id
+from tracera_playwright.runtime import tracera
+
+__all__ = ["tracera", "id"]

tracera_playwright-0.1.0rc1/src/tracera_playwright/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 Playwright-for-Python 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_playwright-0.1.0rc1/src/tracera_playwright/plugin.py

@@ -0,0 +1,426 @@
+"""Self-contained Playwright-for-Python pytest plugin (not tracera-pytest)."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+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 RunnerEnvContext, 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_playwright import runtime as rt
+
+_reporter = create_reporter_state()
+_final_reports: dict[str, dict[str, Any]] = {}
+_attempts: dict[str, int] = {}
+
+
+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",
+    )
+
+
+@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:
+    rt.clear_pending()
+    _final_reports.clear()
+    _attempts.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:
+        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 rt.take_pending(aid)
+                ),
+            )
+        rt.clear_pending()
+        end_reporting(_reporter)
+        return
+
+    for row in _final_reports.values():
+        ctx = row["ctx"]
+        payload = row["payload"]
+        status = row["status"]
+        env_vars_extra = build_env_vars_extra(
+            retry=row.get("retry", 0),
+            retry_key="PLAYWRIGHT_RETRY",
+            package_ids=["playwright"],
+            version_key="PLAYWRIGHT_VERSION",
+            context=row.get("env_context"),
+        )
+        duration_minutes = duration_minutes_from_ms(row["duration_ms"])
+        session_ref = _reporter.session
+        buffer = _reporter.buffer
+        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 rt.take_pending(aid),
+                )
+                return
+            errs = resolve_pending_attachments(
+                session_ref.client,
+                payload,
+                resolve_blob=lambda aid: pending_blobs.get(aid) or rt.take_pending(aid),
+            )
+            if errs:
+                session_ref.set_last_error(errs[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,
+                )
+            )
+
+        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."""
+    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
+
+
+def _safe_node_slug(nodeid: str) -> str:
+    return "".join(c if c.isalnum() or c in "._-" else "_" for c in nodeid)[:120] or "test"
+
+
+def _artifact_folder_name(nodeid: str) -> str:
+    """Per-test folder name under ``--output`` (pytest-playwright layout when available)."""
+    try:
+        from pytest_playwright.pytest_playwright import _truncate_file_name
+        from slugify import slugify
+
+        return _truncate_file_name(slugify(nodeid))
+    except Exception:
+        return _safe_node_slug(nodeid)
+
+
+def _playwright_artifact_dir(item: pytest.Item) -> Path:
+    """Exact per-test output folder used by pytest-playwright (``--output`` / slug(nodeid))."""
+    try:
+        output = Path(str(item.config.getoption("--output", default="test-results"))).absolute()
+    except (ValueError, AttributeError):
+        output = Path("test-results").absolute()
+    return output / _artifact_folder_name(item.nodeid)
+
+
+def _attach_path(ctx: Any, path: Path, mime: str) -> None:
+    if not path.is_file():
+        return
+    try:
+        with run_with_context(ctx):
+            rt.attachment(file_name=path.name, mime_type=mime, path=str(path))
+    except Exception:
+        pass
+
+
+def _try_capture_screenshot(item: pytest.Item, ctx: Any) -> None:
+    """Live screenshot while ``page`` is still open (call failure)."""
+    try:
+        page = item.funcargs.get("page")  # type: ignore[attr-defined]
+    except Exception:
+        page = None
+    if page is None:
+        return
+    try:
+        path = Path.cwd() / f".tracera-pw-{_safe_node_slug(item.nodeid)}.png"
+        with run_with_context(ctx):
+            page.screenshot(path=str(path))
+            rt.attachment(file_name=path.name, mime_type="image/png", path=str(path))
+    except Exception:
+        pass
+
+
+def _try_attach_playwright_artifacts(item: pytest.Item, ctx: Any) -> None:
+    """Attach video/trace from this test's pytest-playwright folder only.
+
+    Called after fixture teardown — ArtifactsRecorder has already moved files into
+    ``--output/<slug(nodeid)>/``. Never scan sibling test dirs.
+    """
+    art = _playwright_artifact_dir(item)
+    if not art.is_dir():
+        return
+    _attach_path(ctx, art / "video.webm", "video/webm")
+    _attach_path(ctx, art / "trace.zip", "application/zip")
+    for found in sorted(art.glob("video-*.webm")):
+        _attach_path(ctx, found, "video/webm")
+    for found in sorted(art.glob("trace-*.zip")):
+        _attach_path(ctx, found, "application/zip")
+
+
+@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
+    rt.set_reporting_suspended(True)
+    try:
+        with suspend_reporting_context():
+            yield
+    finally:
+        rt.set_reporting_suspended(False)
+
+    def _suspend_before_teardown() -> None:
+        rt.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:
+    rt.set_reporting_suspended(False)
+    key = f"pw:{item.nodeid}"
+    attempt = _attempts.get(key, -1) + 1
+    _attempts[key] = attempt
+    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)
+    rt.set_current_key(key)
+    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_key = key  # 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:
+    if getattr(item, "_tracera_ctx", None) 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).
+    if getattr(item, "_tracera_ctx", None) is not None:
+        set_phase("teardown")
+    yield
+    _ = nextitem
+    rt.set_current_key(None)
+    rt.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
+
+    browser_name = None
+    try:
+        browser_name = item.callspec.params.get("browser_name")  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+    def store(status: str) -> None:
+        key = getattr(item, "_tracera_key", item.nodeid)
+        payload = snapshot_payload(ctx)
+        _final_reports[key] = {
+            "ctx": ctx,
+            "payload": payload,
+            "status": status,
+            "duration_ms": (time.time() - getattr(item, "_tracera_started", time.time())) * 1000,
+            "retry": getattr(item, "_tracera_attempt", 0),
+            "pending_blobs": pending_blobs_for_payload(rt.all_pending(), payload),
+            "env_context": RunnerEnvContext(browser=browser_name) if browser_name else None,
+        }
+
+    if call.when == "setup":
+        if report.skipped:
+            record_skip(ctx, _skip_reason(report))
+            store("Skipped")
+        elif report.failed:
+            if not payload_has_step_error(snapshot_payload(ctx)):
+                record_failure(ctx, _failure_source(call, report))
+            store("Failed")
+        return
+
+    if call.when == "call":
+        if report.failed:
+            _try_capture_screenshot(item, ctx)
+            if not payload_has_step_error(snapshot_payload(ctx)):
+                record_failure(ctx, _failure_source(call, report))
+            store("Failed")
+        elif report.skipped:
+            record_skip(ctx, _skip_reason(report))
+            store("Skipped")
+        elif report.passed:
+            store("Passed")
+        return
+
+    if call.when == "teardown":
+        key = getattr(item, "_tracera_key", item.nodeid)
+        row = _final_reports.get(key)
+        if row is None:
+            store("Passed")
+            row = _final_reports.get(key)
+        if row is not None:
+            # Fixtures (incl. pytest-playwright ArtifactsRecorder) have finished —
+            # attach video/trace from this test's output folder only.
+            if row["status"] == "Failed":
+                _try_attach_playwright_artifacts(item, ctx)
+            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
+            row["pending_blobs"] = pending_blobs_for_payload(rt.all_pending(), payload)
+        token_cm = getattr(item, "_tracera_token", None)
+        if token_cm is not None:
+            try:
+                token_cm.__exit__(None, None, None)
+            except Exception:
+                pass

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

@@ -0,0 +1,272 @@
+"""Runtime API (mirrors tracera-pytest; independent package)."""
+
+from __future__ import annotations
+
+import inspect
+import uuid
+from contextlib import nullcontext
+from contextvars import ContextVar
+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
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable[..., Any])
+
+_base = create_tracera_runtime()
+_pending: dict[str, dict[str, Any]] = {}
+_current_key: ContextVar[str | None] = ContextVar("tracera_playwright_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 _register_pending(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[pending_id] = {
+            "fileName": blob.get("fileName") or "attachment.bin",
+            "mimeType": blob.get("mimeType") or "application/octet-stream",
+            "path": path,
+        }
+        return
+    _pending[pending_id] = blob
+
+
+def take_pending(pending_id: str) -> dict[str, Any] | None:
+    return _pending.pop(pending_id, None)
+
+
+def all_pending() -> dict[str, dict[str, Any]]:
+    return dict(_pending)
+
+
+def clear_pending() -> None:
+    _pending.clear()
+    set_current_key(None)
+    set_reporting_suspended(False)
+
+
+def _ensure_ctx() -> TestContext | None:
+    if reporting_suspended():
+        return None
+    ctx = get_context()
+    if ctx is not None:
+        return ctx
+    key = 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 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 playwright-python registry context for decorator / ``with`` / ``async with``."""
+
+    def __init__(self, inner: StepContext) -> None:
+        self._inner = inner
+        self._token: Any = nullcontext()
+
+    def __enter__(self) -> StepContext:
+        if 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:
+        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:
+        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 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 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 reporting_suspended():
+        return
+    ctx = _ensure_ctx()
+
+    def _do() -> None:
+        if isinstance(meta, AttachmentMeta) or (
+            isinstance(meta, dict) and meta.get("attachmentId") and data is None and path is None
+        ):
+            _base.attachment(meta)  # type: ignore[arg-type]
+            return
+        fname = file_name or (Path(path).name if path else "attachment.bin")
+        mime = mime_type or "application/octet-stream"
+        blob_data = data.encode("utf-8") if isinstance(data, str) else data
+        pending_id = f"pending:{uuid.uuid4()}"
+        _register_pending(
+            pending_id, {"fileName": fname, "mimeType": mime, "data": blob_data, "path": 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
+
+
+tracera = _TraceraApi()
+
+from tracera_playwright.annotations import id as _id  # noqa: E402
+
+tracera.id = _id