tracera-core 0.1.0rc1__tar.gz

tracera_core-0.1.0rc1/.gitignore

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

tracera_core-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_core-0.1.0rc1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: tracera-core
+Version: 0.1.0rc1
+Summary: Tracera Autotest adapter core (HTTP + steps + result upload)
+Project-URL: Homepage, https://tracera.dev/docs/adapters
+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: adapter,autotest,reporting,test-reporting,testops,tracera
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# tracera-core
+
+Shared Autotest HTTP client, step context, and result upload for Tracera adapters.
+
+**Requires Python ≥ 3.11.**
+
+```bash
+pip install tracera-core
+```
+
+Import package name is **`tracera`**.
+
+Foreign thread: capture `get_context()` on the test thread, then wrap the worker in `with run_with_context(ctx):`. Without a pin, steps and comments on that thread are dropped.
+
+**Several test processes** (e.g. Pabot, parallel Behave): they share one run automatically — the last process to finish closes it. You do not create the run by hand.
+
+```python
+from tracera import step
+
+step("title", lambda: None)
+
+
+@step("open {path}")
+def open_login(path: str): ...
+
+
+with step("title"):
+    ...
+
+async with step("title"):
+    ...
+```
+
+Used by the official Python adapters. Customer how-to: [Autotest adapters](https://tracera.dev/docs/adapters). Prefer a framework package unless you write a custom runner integration.
+
+Plugin / runner helpers (`begin_reporting`, `create_test_context`, …) live in submodules (`tracera.session`, `tracera.context`, …) — not on the `tracera` package root.

tracera_core-0.1.0rc1/README.md

@@ -0,0 +1,36 @@
+# tracera-core
+
+Shared Autotest HTTP client, step context, and result upload for Tracera adapters.
+
+**Requires Python ≥ 3.11.**
+
+```bash
+pip install tracera-core
+```
+
+Import package name is **`tracera`**.
+
+Foreign thread: capture `get_context()` on the test thread, then wrap the worker in `with run_with_context(ctx):`. Without a pin, steps and comments on that thread are dropped.
+
+**Several test processes** (e.g. Pabot, parallel Behave): they share one run automatically — the last process to finish closes it. You do not create the run by hand.
+
+```python
+from tracera import step
+
+step("title", lambda: None)
+
+
+@step("open {path}")
+def open_login(path: str): ...
+
+
+with step("title"):
+    ...
+
+async with step("title"):
+    ...
+```
+
+Used by the official Python adapters. Customer how-to: [Autotest adapters](https://tracera.dev/docs/adapters). Prefer a framework package unless you write a custom runner integration.
+
+Plugin / runner helpers (`begin_reporting`, `create_test_context`, …) live in submodules (`tracera.session`, `tracera.context`, …) — not on the `tracera` package root.

tracera_core-0.1.0rc1/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "tracera-core"
+version = "0.1.0rc1"
+description = "Tracera Autotest adapter core (HTTP + steps + result upload)"
+readme = "README.md"
+license = { text = "SEE LICENSE IN LICENSE.md" }
+authors = [{ name = "Tracera", email = "contact@tracera.dev" }]
+requires-python = ">=3.11"
+keywords = ["tracera", "autotest", "test-reporting", "testops", "adapter", "reporting"]
+dependencies = [
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://tracera.dev/docs/adapters"
+Bug-Tracker = "https://github.com/tracera-dev/tracera-releases/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Distribution: tracera-core. Import package: tracera (mirrors @tracera/core → import from package).
+[tool.hatch.build.targets.wheel]
+packages = ["src/tracera"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/tracera" = "tracera"
+
+# Publish surface: runtime package + docs only (no tests / harness / gitignore).
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/tracera",
+  "LICENSE.md",
+  "README.md",
+]

tracera_core-0.1.0rc1/src/tracera/__init__.py

@@ -0,0 +1,35 @@
+"""Tracera Autotest adapter core — customer DX.
+
+Public surface: ``step`` / ``comment`` / ``error`` / ``attachment`` /
+``get_context`` / ``run_with_context`` (+ types). How-to:
+https://tracera.dev/docs/adapters
+
+Plugin / runner helpers stay in submodules (``tracera.session``, ``tracera.context``,
+``tracera.registry``, ``tracera.runtime``, …) — not on this package root / ``__all__``.
+"""
+
+from __future__ import annotations
+
+from tracera.context import (
+    AttachmentMeta,
+    TestContext,
+    attachment,
+    comment,
+    error,
+    get_context,
+    reserve_attachment,
+    run_with_context,
+    step,
+)
+
+__all__ = [
+    "AttachmentMeta",
+    "TestContext",
+    "attachment",
+    "comment",
+    "error",
+    "get_context",
+    "reserve_attachment",
+    "run_with_context",
+    "step",
+]

tracera_core-0.1.0rc1/src/tracera/bind.py

@@ -0,0 +1,18 @@
+"""Declarative bind helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TraceraBind:
+    test_case_id: int
+    autotest_name: str | None = None
+
+
+def make_bind(test_case_id: int, autotest_name: str | None = None) -> TraceraBind:
+    return TraceraBind(
+        test_case_id=test_case_id,
+        autotest_name=autotest_name[:128] if autotest_name else None,
+    )

tracera_core-0.1.0rc1/src/tracera/buffer.py

@@ -0,0 +1,245 @@
+"""Result buffer, session, soft-disable after consecutive batch failures."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Final, Literal
+
+from tracera.client import BatchItem, TraceraClient
+from tracera.config import TraceraConfig
+from tracera.context import TestContext, snapshot_payload
+from tracera.env_snapshot import snapshot_env_vars
+from tracera.log import log
+
+CONSECUTIVE_BATCH_FAIL_LIMIT: Final[int] = 2
+
+Status = Literal["Passed", "Failed", "Skipped"]
+
+
+@dataclass
+class PendingResult:
+    ctx: TestContext
+    status: Status
+    duration_minutes: float | None
+    payload: dict[str, Any] | None = None
+    env_vars_extra: dict[str, str] | None = None
+
+
+@dataclass
+class ReportSession:
+    client: TraceraClient
+    config: TraceraConfig
+    test_run_id: int
+    owned_by_adapter: bool
+    reporting_enabled: bool = True
+    failed_report: int = 0
+    unsent_results: int = 0
+    last_error: str | None = None
+    """When True, finish via peer handoff refcount (Pabot / Behave / …)."""
+    peer_handoff: bool = False
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
+
+    def note_failed_report(self, n: int = 1) -> None:
+        with self._lock:
+            self.failed_report += n
+
+    def note_unsent_results(self, n: int = 1) -> None:
+        with self._lock:
+            self.unsent_results += n
+
+    def clear_one_failed_report(self) -> None:
+        with self._lock:
+            self.failed_report = max(0, self.failed_report - 1)
+
+    def disable_reporting(self) -> None:
+        with self._lock:
+            self.reporting_enabled = False
+
+    def set_last_error(self, message: str | None) -> None:
+        with self._lock:
+            self.last_error = message
+
+
+def _create_session(
+    client: TraceraClient,
+    config: TraceraConfig,
+    test_run_id: int,
+    owned_by_adapter: bool,
+    *,
+    peer_handoff: bool = False,
+) -> ReportSession:
+    return ReportSession(
+        client=client,
+        config=config,
+        test_run_id=test_run_id,
+        owned_by_adapter=owned_by_adapter,
+        peer_handoff=peer_handoff,
+    )
+
+
+class ResultBuffer:
+    def __init__(self, session: ReportSession) -> None:
+        self._session = session
+        self._pending: list[PendingResult] = []
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._flushing = threading.Lock()
+        self._transport_failures: dict[int, int] = {}
+        self._consecutive_batch_failures = 0
+
+    def enqueue(self, item: PendingResult) -> None:
+        if not self._session.reporting_enabled:
+            return
+        if item.ctx.test_case_id is None or not isinstance(item.ctx.test_case_id, int):
+            return
+        with self._lock:
+            self._pending.append(item)
+            if len(self._pending) >= self._session.config.flush_max_items:
+                self._schedule_flush(immediate=True)
+                return
+            if self._timer is None:
+                self._schedule_flush(immediate=False)
+
+    @property
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending)
+
+    def _schedule_flush(self, *, immediate: bool) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+        if immediate:
+            threading.Thread(target=self.flush, daemon=True).start()
+            return
+        delay = self._session.config.flush_max_ms / 1000
+        self._timer = threading.Timer(delay, self.flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def flush(self) -> None:
+        with self._flushing:
+            self._flush_once()
+            if self._session.reporting_enabled and self.pending_count > 0:
+                self._flush_once()
+
+    def _flush_once(self) -> None:
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            if not self._session.reporting_enabled or not self._pending:
+                return
+            pending_snapshot = list(self._pending)
+            self._pending.clear()
+
+        retry_later: list[PendingResult] = []
+        idx = 0
+        while self._session.reporting_enabled and idx < len(pending_snapshot):
+            batch = pending_snapshot[idx : idx + self._session.config.flush_max_items]
+            idx += len(batch)
+            log.debug(f"Tracera: sent {len(batch)} result(s)")
+            base_env = snapshot_env_vars()
+            items: list[BatchItem] = []
+            for p in batch:
+                if isinstance(p.payload, dict):
+                    snap = p.payload
+                else:
+                    snap = snapshot_payload(p.ctx)
+                error_message = snap.get("errorMessage")
+                if error_message is None:
+                    error_message = p.ctx.result_error
+                comment = snap.get("comment")
+                if comment is None:
+                    comment = p.ctx.result_comment
+                env_vars = {**base_env, **p.env_vars_extra} if p.env_vars_extra else base_env
+                items.append(
+                    BatchItem(
+                        is_automated=True,
+                        test_case_id=p.ctx.test_case_id or 0,
+                        test_run_id=self._session.test_run_id,
+                        result=p.status,
+                        autotest_name=p.ctx.autotest_name or None,
+                        duration_minutes=p.duration_minutes,
+                        setup=snap.get("setup") or [],
+                        test=snap.get("test") or [],
+                        teardown=snap.get("teardown") or [],
+                        attachments=snap.get("attachments") or [],
+                        error_message=error_message,
+                        comment=comment,
+                        env_vars=env_vars,
+                    )
+                )
+            try:
+                res = self._session.client.post_results_batch(self._session.test_run_id, items)
+                self._consecutive_batch_failures = 0
+                for p in batch:
+                    self._note_transport_success(p)
+                for r in res.results:
+                    if r.get("ok"):
+                        continue
+                    self._session.note_failed_report()
+                    self._session.set_last_error(r.get("error") or "item_failed")
+                    ridx = int(r.get("index", -1))
+                    test_case_id = items[ridx].test_case_id if 0 <= ridx < len(items) else None
+                    case_part = (
+                        f"testCaseId={test_case_id}"
+                        if test_case_id is not None
+                        else f"batch index {ridx}"
+                    )
+                    log.error(
+                        f"Tracera: server rejected result ({case_part}): {r.get('error') or 'unknown'}"
+                    )
+            except Exception as e:
+                self._session.set_last_error(str(e))
+                log.error(f"Tracera: {self._session.last_error} — requeued")
+                for p in batch:
+                    self._note_transport_failure(p)
+                retry_later.extend(batch)
+                self._consecutive_batch_failures += 1
+                if self._consecutive_batch_failures >= CONSECUTIVE_BATCH_FAIL_LIMIT:
+                    self._session.disable_reporting()
+                    log.error(
+                        f"Tracera: stopped reporting after {CONSECUTIVE_BATCH_FAIL_LIMIT} "
+                        "failed batch uploads"
+                    )
+                    break
+
+        # Soft-disable mid-flush: never-attempted snapshot batches must stay
+        # buffered (count as not uploaded) instead of vanishing.
+        if idx < len(pending_snapshot):
+            retry_later.extend(pending_snapshot[idx:])
+        if retry_later:
+            with self._lock:
+                self._pending = retry_later + self._pending
+
+    def _note_transport_success(self, item: PendingResult) -> None:
+        key = id(item)
+        if self._transport_failures.get(key, 0) == 0:
+            return
+        self._session.clear_one_failed_report()
+        self._transport_failures.pop(key, None)
+
+    def _note_transport_failure(self, item: PendingResult) -> None:
+        key = id(item)
+        n = self._transport_failures.get(key, 0) + 1
+        self._transport_failures[key] = n
+        if n == 1:
+            self._session.note_failed_report()
+
+
+def _print_summary(session: ReportSession) -> None:
+    log.link(session.client.run_url(session.test_run_id))
+
+
+def finish_owned_run(session: ReportSession) -> None:
+    if not session.owned_by_adapter:
+        return
+    try:
+        session.client.finish_run(session.test_run_id)
+    except Exception as e:
+        session.set_last_error(str(e))
+        session.note_failed_report()
+        msg = session.last_error or str(e)
+        log.error(msg if msg.startswith("Tracera:") else f"Tracera: {msg}")