tracera-robot 0.1.0rc1__tar.gz

tracera_robot-0.1.0rc1/.gitignore

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

tracera_robot-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_robot-0.1.0rc1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: tracera-robot
+Version: 0.1.0rc1
+Summary: Tracera Autotest adapter for Robot Framework
+Project-URL: Homepage, https://tracera.dev/docs/robot
+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,robotframework,test-reporting,testops,tracera
+Requires-Python: >=3.11
+Requires-Dist: tracera-core==0.1.0rc1
+Provides-Extra: dev
+Requires-Dist: robotframework>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tracera-robot
+
+Tracera Autotest adapter for Robot Framework (listener).
+
+**Requires Python ≥ 3.11 and Robot Framework ≥ 7.**
+
+```bash
+pip install tracera-robot
+```
+
+How-to: [Robot Framework](https://tracera.dev/docs/robot). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+```bash
+robot --listener tracera_robot.listener.TraceraListener suite.robot
+```
+
+Optional companion library for comment / error / attachment / explicit step:
+
+```robot
+*** Settings ***
+Library    tracera_robot.keywords.TraceraKeywords
+```
+
+## Bind
+
+Tags `tracera.id:…` / optional literal `tracera.name:…`. If `tracera.name` is omitted → Robot test name. Tags do not support `{param}` templates. Imperative `Tracera Test Case` via the companion library is also available.
+
+## Skip
+
+Stock Robot `Skip`. The reason becomes a result `comment`.
+
+## Steps
+
+User and library keywords → **Test** steps (nesting follows keyword calls). FOR / IF / WHILE / TRY are reported. **Test** Setup / Teardown → **Setup** / **Teardown**; Suite Setup / Teardown are not reported.
+
+By default the step title is the keyword name. For a different title, use the companion library keyword `Tracera Step` (custom title, then the keyword to run). Python helpers can also use `tracera.step` or `@tracera.step("…")` from core.
+
+## Comments, errors, and attachments
+
+Use `TraceraKeywords` (`Tracera Comment`, `Tracera Error`, `Tracera Attachment`) — see [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Parameterized
+
+Stock `[Template]` — same `tracera.id` for every argument line under the template. Different id per row → one Robot test per row.
+
+**Pabot:** workers share one run automatically — nothing extra to set.

tracera_robot-0.1.0rc1/README.md

@@ -0,0 +1,48 @@
+# tracera-robot
+
+Tracera Autotest adapter for Robot Framework (listener).
+
+**Requires Python ≥ 3.11 and Robot Framework ≥ 7.**
+
+```bash
+pip install tracera-robot
+```
+
+How-to: [Robot Framework](https://tracera.dev/docs/robot). Shared env / run mode: [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Setup
+
+```bash
+robot --listener tracera_robot.listener.TraceraListener suite.robot
+```
+
+Optional companion library for comment / error / attachment / explicit step:
+
+```robot
+*** Settings ***
+Library    tracera_robot.keywords.TraceraKeywords
+```
+
+## Bind
+
+Tags `tracera.id:…` / optional literal `tracera.name:…`. If `tracera.name` is omitted → Robot test name. Tags do not support `{param}` templates. Imperative `Tracera Test Case` via the companion library is also available.
+
+## Skip
+
+Stock Robot `Skip`. The reason becomes a result `comment`.
+
+## Steps
+
+User and library keywords → **Test** steps (nesting follows keyword calls). FOR / IF / WHILE / TRY are reported. **Test** Setup / Teardown → **Setup** / **Teardown**; Suite Setup / Teardown are not reported.
+
+By default the step title is the keyword name. For a different title, use the companion library keyword `Tracera Step` (custom title, then the keyword to run). Python helpers can also use `tracera.step` or `@tracera.step("…")` from core.
+
+## Comments, errors, and attachments
+
+Use `TraceraKeywords` (`Tracera Comment`, `Tracera Error`, `Tracera Attachment`) — see [Autotest adapters](https://tracera.dev/docs/adapters).
+
+## Parameterized
+
+Stock `[Template]` — same `tracera.id` for every argument line under the template. Different id per row → one Robot test per row.
+
+**Pabot:** workers share one run automatically — nothing extra to set.

tracera_robot-0.1.0rc1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "tracera-robot"
+version = "0.1.0rc1"
+description = "Tracera Autotest adapter for Robot Framework"
+readme = "README.md"
+license = { text = "SEE LICENSE IN LICENSE.md" }
+authors = [{ name = "Tracera", email = "contact@tracera.dev" }]
+requires-python = ">=3.11"
+keywords = ["tracera", "autotest", "robotframework", "test-reporting", "testops"]
+dependencies = [
+  "tracera-core==0.1.0rc1",
+]
+
+[project.optional-dependencies]
+dev = ["robotframework>=7"]
+
+[project.urls]
+Homepage = "https://tracera.dev/docs/robot"
+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_robot"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/tracera_robot" = "tracera_robot"
+
+# Publish surface: runtime package + docs only (no tests / harness / gitignore).
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/tracera_robot",
+  "LICENSE.md",
+  "README.md",
+]

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

@@ -0,0 +1,7 @@
+"""Tracera Autotest adapter for Robot Framework."""
+
+from __future__ import annotations
+
+from tracera_robot.runtime import tracera
+
+__all__ = ["tracera"]

tracera_robot-0.1.0rc1/src/tracera_robot/keywords.py

@@ -0,0 +1,60 @@
+"""Robot Framework library for imperative Tracera APIs.
+
+Companion keywords are not auto-mapped as steps (PRODUCT) — they would duplicate
+explicit ``tracera.step`` / side-effect APIs. Prefer tags for bind; user /
+library/builtin keywords and FOR/IF/WHILE/TRY (listener API 3 control hooks)
+build the step tree; use this library for comment / error / attachment and
+optional ``tracera.test_case`` / ``tracera.step``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from tracera_robot.runtime import tracera
+
+
+class TraceraKeywords:
+    """Companion keywords — comment / attach / step; not auto-mapped into the tree."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def tracera_test_case(self, test_case_id: int | str, name: str | None = None) -> None:
+        tracera.test_case(int(test_case_id), name)
+
+    def tracera_comment(self, text: str) -> None:
+        tracera.comment(str(text))
+
+    def tracera_error(self, text: str) -> None:
+        tracera.error(str(text))
+
+    def tracera_attach_file(
+        self,
+        path: str,
+        mime_type: str = "application/octet-stream",
+        file_name: str | None = None,
+    ) -> None:
+        p = Path(path)
+        tracera.attachment(
+            file_name=file_name or p.name,
+            mime_type=mime_type,
+            path=str(p),
+        )
+
+    def tracera_attach_text(self, file_name: str, content: str) -> None:
+        tracera.attachment(
+            file_name=file_name,
+            mime_type="text/plain",
+            data=content.encode("utf-8"),
+        )
+
+    def tracera_step(self, title: str, keyword: str, *args: object) -> object:
+        """Run a Robot keyword inside an explicit ``tracera.step`` (custom title)."""
+        from robot.libraries.BuiltIn import BuiltIn
+
+        def body() -> object:
+            # RF stubs type run_keyword narrowly; keyword name + args are dynamic at runtime.
+            return BuiltIn().run_keyword(cast(Any, keyword), *cast(tuple[Any, ...], args))
+
+        return tracera.step(str(title), body)

tracera_robot-0.1.0rc1/src/tracera_robot/listener.py

@@ -0,0 +1,374 @@
+"""Robot Framework listener — bind via tags, auto keyword / control-structure steps."""
+
+from __future__ import annotations
+
+import re
+import time
+from contextlib import AbstractContextManager
+from typing import Any, ClassVar, Literal
+from urllib.parse import unquote
+
+from tracera import (
+    run_with_context,
+)
+from tracera.buffer import PendingResult
+from tracera.context import (
+    StepNode,
+    TestContext,
+    create_test_context,
+    empty_pm_doc,
+    get_context,
+    record_failure,
+    record_skip,
+    set_phase,
+    snapshot_payload,
+)
+from tracera.env_extras import build_env_vars_extra
+from tracera.parallel import sync_pabot_env_from_robot
+from tracera.pending import (
+    discard_pending_blobs,
+    pending_blobs_for_payload,
+    resolve_pending_attachments,
+)
+from tracera.session import (
+    ReporterState,
+    begin_reporting,
+    create_reporter_state,
+    duration_minutes_from_ms,
+    end_reporting,
+)
+from tracera_robot import runtime as rt
+
+_ID_TAG = re.compile(r"^tracera\.id:(\d+)$", re.I)
+_NAME_TAG = re.compile(r"^tracera\.name:(.+)$", re.I)
+
+Status = Literal["Passed", "Failed", "Skipped"]
+
+
+class TraceraListener:
+    """Register with ``--listener tracera_robot.listener.TraceraListener``."""
+
+    ROBOT_LISTENER_API_VERSION: ClassVar[int] = 3
+
+    def __init__(self) -> None:
+        self._reporter: ReporterState = create_reporter_state()
+        self._ctx: TestContext | None = None
+        self._token: AbstractContextManager[TestContext] | None = None
+        self._started: float = 0.0
+        self._status: Status = "Passed"
+        self._open_steps: int = 0
+
+    def start_suite(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        if getattr(data, "parent", None) is None:
+            rt.clear_pending()
+            # Pabot injects pool/queue as Robot variables — promote before handoff detect.
+            sync_pabot_env_from_robot()
+            begin_reporting(self._reporter)
+
+    def end_suite(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        if getattr(data, "parent", None) is None:
+            end_reporting(self._reporter)
+
+    def start_test(self, data: Any, result: Any) -> None:
+        # RF listener API 3: `data.tags` keep unresolved `${VAR}`; resolved tags are on `result`.
+        raw_tags = getattr(result, "tags", None) or getattr(data, "tags", None) or []
+        case_id, name = _parse_tags(list(raw_tags))
+        self._ctx = create_test_context(
+            test_case_id=case_id,
+            autotest_name=(name or getattr(data, "name", "") or "")[:128],
+        )
+        rt.set_listener_context(self._ctx)
+        self._token = run_with_context(self._ctx)
+        self._token.__enter__()
+        self._started = time.time()
+        self._status = "Passed"
+        self._open_steps = 0
+        set_phase("test")
+
+    def end_test(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        if self._ctx is None:
+            return
+        status = str(getattr(result, "status", "") or "").upper()
+        if status == "SKIP":
+            self._status = "Skipped"
+            record_skip(self._ctx, getattr(result, "message", None) or None)
+        elif status != "PASS":
+            self._status = "Failed"
+            msg = getattr(result, "message", None)
+            if msg:
+                payload = snapshot_payload(self._ctx)
+                has_step_err = any(
+                    isinstance(s, dict)
+                    and isinstance(s.get("errorMessage"), str)
+                    and s["errorMessage"].strip()
+                    for s in payload["setup"] + payload["test"] + payload["teardown"]
+                )
+                if not has_step_err:
+                    record_failure(self._ctx, msg)
+        self._enqueue_current()
+        if self._token is not None:
+            try:
+                self._token.__exit__(None, None, None)
+            except Exception:
+                pass
+        rt.set_listener_context(None)
+        self._ctx = None
+        self._token = None
+
+    def start_keyword(self, data: Any, result: Any) -> None:
+        if self._ctx is None:
+            return
+        kw_type = str(getattr(data, "type", "") or "").upper()
+        if kw_type in ("SETUP", "SUITE SETUP", "TEST SETUP"):
+            set_phase("setup")
+            return
+        if kw_type in ("TEARDOWN", "SUITE TEARDOWN", "TEST TEARDOWN"):
+            set_phase("teardown")
+            return
+        if not _should_report_keyword(data, result):
+            return
+        self._begin_reported_step(getattr(data, "name", None) or "keyword")
+
+    def end_keyword(self, data: Any, result: Any) -> None:
+        if self._ctx is None:
+            return
+        kw_type = str(getattr(data, "type", "") or "").upper()
+        if kw_type in ("SETUP", "SUITE SETUP", "TEST SETUP"):
+            set_phase("test")
+            return
+        if kw_type in ("TEARDOWN", "SUITE TEARDOWN", "TEST TEARDOWN"):
+            set_phase("test")
+            return
+        if not _should_report_keyword(data, result):
+            return
+        self._end_reported_step(result)
+
+    # --- RF listener API 3: control structures are not start_keyword -------------
+
+    def start_for(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._begin_reported_step(_control_step_title(data))
+
+    def end_for(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._end_reported_step(result)
+
+    def start_while(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._begin_reported_step(_control_step_title(data))
+
+    def end_while(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._end_reported_step(result)
+
+    def start_if_branch(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._begin_reported_step(_control_step_title(data))
+
+    def end_if_branch(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._end_reported_step(result)
+
+    def start_try_branch(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._begin_reported_step(_control_step_title(data))
+
+    def end_try_branch(self, data: Any, result: Any) -> None:  # noqa: ARG002
+        self._end_reported_step(result)
+
+    # start_for_iteration / start_while_iteration / start_if / start_try omitted on purpose
+    # (ITERATION + IF/TRY roots — body nests under FOR/WHILE / IF|TRY branches).
+
+    def _begin_reported_step(self, title: str) -> None:
+        if self._ctx is None:
+            return
+        _push_step(title)
+        self._open_steps += 1
+
+    def _end_reported_step(self, result: Any) -> None:
+        if self._ctx is None or self._open_steps <= 0:
+            return
+        failed = str(getattr(result, "status", "") or "").upper() == "FAIL"
+        msg = getattr(result, "message", None) if failed else None
+        _pop_step(failed=failed, message=msg)
+        self._open_steps -= 1
+
+    def _enqueue_current(self) -> None:
+        if self._ctx is None:
+            return
+        if (
+            self._reporter.soft_disabled
+            or not self._reporter.session
+            or not self._reporter.buffer
+            or not self._reporter.upload_pool
+        ):
+            payload = snapshot_payload(self._ctx)
+            discard_pending_blobs(payload, take_blob=rt.take_pending)
+            rt.clear_pending()
+            return
+        payload = snapshot_payload(self._ctx)
+        env_vars_extra = build_env_vars_extra(
+            package_ids=["robotframework"],
+            version_key="ROBOT_VERSION",
+        )
+        duration_minutes = duration_minutes_from_ms((time.time() - self._started) * 1000)
+        session_ref = self._reporter.session
+        buffer = self._reporter.buffer
+        pending = pending_blobs_for_payload(rt.all_pending(), payload)
+        ctx = self._ctx
+        status = self._status
+
+        def job() -> None:
+            if not session_ref.reporting_enabled:
+                discard_pending_blobs(
+                    payload,
+                    take_blob=lambda aid: pending.pop(aid, None) or rt.take_pending(aid),
+                )
+                return
+            errs = resolve_pending_attachments(
+                session_ref.client,
+                payload,
+                resolve_blob=lambda aid: pending.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,  # type: ignore[arg-type]
+                    duration_minutes=duration_minutes,
+                    payload=payload,
+                    env_vars_extra=env_vars_extra,
+                )
+            )
+
+        self._reporter.upload_pool.enqueue(job)
+
+
+def _push_step(title: str) -> None:
+    ctx = get_context()
+    if ctx is None:
+        return
+    node = StepNode(
+        id=ctx._next_step_id,
+        parent_id=ctx._step_stack[-1].id if ctx._step_stack else None,
+        result="NotSet",
+        action=empty_pm_doc(title),
+        expectation={"type": "doc", "content": [{"type": "paragraph"}]},
+        attachments=[],
+        error_message=None,
+        comment=None,
+    )
+    ctx._next_step_id += 1
+    parent = ctx._step_stack[-1] if ctx._step_stack else None
+    if parent:
+        parent.children.append(node)
+    else:
+        ctx._roots[ctx.section].append(node)
+    ctx._step_stack.append(node)
+
+
+def _pop_step(*, failed: bool, message: str | None) -> None:
+    from tracera.context import append_text, format_failure_text
+
+    ctx = get_context()
+    if ctx is None or not ctx._step_stack:
+        return
+    node = ctx._step_stack.pop()
+    if failed:
+        node.result = "Failed"
+        if message:
+            node.error_message = append_text(node.error_message, format_failure_text(message))
+    elif node.result == "NotSet":
+        node.result = "Passed"
+
+
+# Control structures use dedicated API 3 hooks (not start_keyword). Still skip if
+# a type ever leaks through the keyword path.
+_SKIP_KEYWORD_TYPES = frozenset(
+    {
+        "FOR",
+        "WHILE",
+        "IF",
+        "ELSE IF",
+        "ELSE",
+        "TRY",
+        "EXCEPT",
+        "FINALLY",
+        "ITERATION",
+        "IF/ELSE ROOT",
+        "TRY/EXCEPT ROOT",
+        "GROUP",
+        "VAR",
+        "BREAK",
+        "CONTINUE",
+        "RETURN",
+        "ERROR",
+    }
+)
+
+
+def _control_step_title(data: Any) -> str:
+    """Stable step title for FOR / WHILE / IF|TRY branches (RF log-like)."""
+    kw_type = str(getattr(data, "type", "") or "").upper()
+    if kw_type == "FOR":
+        assign = tuple(str(a) for a in (getattr(data, "assign", None) or ()))
+        flavor = str(getattr(data, "flavor", None) or "IN")
+        values = tuple(str(v) for v in (getattr(data, "values", None) or ()))
+        return " ".join(("FOR", *assign, flavor, *values))
+    if kw_type == "WHILE":
+        cond = getattr(data, "condition", None)
+        return f"WHILE {cond}" if cond not in (None, "") else "WHILE"
+    if kw_type in ("IF", "ELSE IF"):
+        cond = getattr(data, "condition", None)
+        return f"{kw_type} {cond}" if cond not in (None, "") else kw_type
+    if kw_type == "EXCEPT":
+        patterns = tuple(str(p) for p in (getattr(data, "patterns", None) or ()))
+        return "EXCEPT " + " ".join(patterns) if patterns else "EXCEPT"
+    if kw_type in ("ELSE", "TRY", "FINALLY"):
+        return kw_type
+    return str(getattr(data, "name", None) or kw_type or "keyword")
+
+
+def _is_tracera_companion_lib(lib: str) -> bool:
+    """Companion `TraceraKeywords` — comment/attach/step APIs, not tree content."""
+    low = lib.lower().replace("\\", "/")
+    return "tracerakeywords" in low.replace("_", "") or "tracera_robot.keywords" in low
+
+
+def _should_report_keyword(data: Any, result: Any | None = None) -> bool:
+    kw_type = str(getattr(data, "type", "") or "").upper()
+    if kw_type in _SKIP_KEYWORD_TYPES:
+        return False
+    # RF listener API 3: library ownership lives on `result`, not `data`.
+    lib = ""
+    if result is not None:
+        lib = getattr(result, "owner", None) or getattr(result, "libname", None) or ""
+    if not lib:
+        lib = getattr(data, "owner", None) or getattr(data, "libname", None) or ""
+    if isinstance(lib, str) and lib and _is_tracera_companion_lib(lib):
+        # Skip companion APIs (would double-nest under explicit `Tracera Step`).
+        return False
+    name = getattr(data, "name", "") or ""
+    if name.startswith("${") or name.startswith("@{"):
+        return False
+    # BuiltIn Skip / Fail — status/error land on the parent keyword or result; not tree leaves
+    # (Skipped UI = empty Steps; Failed UI = user keyword only with the fail text).
+    lib_l = str(lib).lower() if isinstance(lib, str) else ""
+    if str(name).strip().lower() in ("skip", "fail") and (not lib_l or lib_l == "builtin"):
+        return False
+    return True
+
+
+def _parse_tags(tags: list[Any]) -> tuple[int | None, str | None]:
+    case_id: int | None = None
+    name: str | None = None
+    for raw in tags:
+        t = str(raw).strip()
+        m = _ID_TAG.match(t)
+        if m:
+            n = int(m.group(1))
+            if n > 0:
+                case_id = n
+            continue
+        m = _NAME_TAG.match(t)
+        if m:
+            name = unquote(m.group(1))[:128]
+    return case_id, name

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

@@ -0,0 +1,143 @@
+"""Companion API for Robot keywords (imperative bind + steps)."""
+
+from __future__ import annotations
+
+import uuid
+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
+from tracera.runtime import create_tracera_runtime
+
+T = TypeVar("T")
+_base = create_tracera_runtime()
+_pending: dict[str, dict[str, Any]] = {}
+# Listener holds the active test. Under Pabot, ContextVar can be empty when
+# companion library keywords run — fall back to this pin.
+_listener_ctx: TestContext | None = None
+
+
+def set_listener_context(ctx: TestContext | None) -> None:
+    global _listener_ctx
+    _listener_ctx = ctx
+
+
+def _pinned_context() -> TestContext | None:
+    return get_context() or _listener_ctx
+
+
+def take_pending(ref: str) -> dict[str, Any] | None:
+    return _pending.pop(ref, None)
+
+
+def all_pending() -> dict[str, dict[str, Any]]:
+    return dict(_pending)
+
+
+def clear_pending() -> None:
+    _pending.clear()
+
+
+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:`` tags."""
+    ctx = _pinned_context()
+    if ctx is None:
+        _base.test_case(test_case_id, autotest_name)
+        return
+    with run_with_context(ctx):
+        _base.test_case(test_case_id, autotest_name)
+
+
+@overload
+def step(title: str, body: Callable[[], T]) -> T: ...
+
+
+@overload
+def step(title: str, body: None = None) -> StepContext: ...
+
+
+@overload
+def step(title: Callable[..., T]) -> Callable[..., T]: ...
+
+
+def step(
+    title: str | Callable[..., T], body: Callable[[], T] | None = None
+) -> T | StepContext | Callable[..., T]:
+    """Record a step — call / decorator / ``with`` / ``async with`` (same forms as ``tracera.step``)."""
+    ctx = _pinned_context()
+    if ctx is None:
+        return _base.step(title, body)  # type: ignore[arg-type,return-value]
+    with run_with_context(ctx):
+        return _base.step(title, body)  # type: ignore[arg-type,return-value]
+
+
+def comment(text: str) -> None:
+    """Comment on the open step, or on the result when no step is open."""
+    ctx = _pinned_context()
+    if ctx is None:
+        return
+    with run_with_context(ctx):
+        _base.comment(text)
+
+
+def error(text: str) -> None:
+    """Soft error text on the open step (or result). Does not by itself fail the test."""
+    ctx = _pinned_context()
+    if ctx is None:
+        return
+    with run_with_context(ctx):
+        _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."""
+    ctx = _pinned_context()
+
+    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 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()}"
+        stored: dict[str, Any] = {
+            "fileName": fname,
+            "mimeType": mime,
+        }
+        if path:
+            stored["path"] = path
+        else:
+            stored["data"] = blob_data
+        _pending[pending_id] = stored
+        _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)
+
+
+tracera = _TraceraApi()