pytest-test-observer 0.1.0__py3-none-any.whl

pytest_test_observer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pytest_test_observer/allure_compat.py

@@ -0,0 +1,66 @@
+"""Compatibility layer for allure-pytest — the public API surface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pytest_test_observer.allure_compat_helpers import (
+    extract_labels,
+    extract_links,
+    first_label_value,
+    read_allure_title,
+)
+from pytest_test_observer.constants import ID_LABEL, SEVERITY_LABEL, TestStatus
+from pytest_test_observer.models import AllureMeta
+
+if TYPE_CHECKING:
+    import pytest
+
+__all__ = ("AllureMeta", "detect_allure", "empty_allure_meta", "extract_allure_meta", "map_status")
+
+
+def detect_allure(pluginmanager: Any) -> bool:
+    return bool(pluginmanager.hasplugin("allure_pytest"))
+
+
+def map_status(report: pytest.TestReport) -> TestStatus:
+    """Map a pytest TestReport to the allure-style status vocabulary.
+
+    Rules:
+    - skipped → SKIPPED
+    - passed  → PASSED
+    - failed (call phase) → FAILED
+    - failed (setup/teardown phase) → BROKEN  (allure convention)
+    - outcome == 'rerun' (pytest-rerunfailures) → FAILED/BROKEN by phase
+    - anything else → UNKNOWN
+    """
+    if report.skipped:
+        return TestStatus.SKIPPED
+    if report.passed:
+        return TestStatus.PASSED
+    if report.failed or report.outcome == TestStatus.RERUN:
+        if report.when == "call":
+            return TestStatus.FAILED
+        if report.when in ("setup", "teardown"):
+            return TestStatus.BROKEN
+    return TestStatus.UNKNOWN
+
+
+def extract_allure_meta(item: pytest.Item) -> AllureMeta:
+    meta = empty_allure_meta()
+    meta["labels"] = extract_labels(item)
+    meta["links"] = extract_links(item)
+    meta["title"] = read_allure_title(item)
+    meta["severity"] = first_label_value(meta["labels"], SEVERITY_LABEL)
+    meta["allure_id"] = first_label_value(meta["labels"], ID_LABEL)
+    return meta
+
+
+def empty_allure_meta() -> AllureMeta:
+    return {
+        "labels": {},
+        "links": [],
+        "title": "",
+        "severity": "",
+        "allure_id": "",
+    }

pytest_test_observer/allure_compat_helpers.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pytest_test_observer.constants import (
+    DISPLAY_NAME_ATTR,
+    LABEL_MARK,
+    LABEL_TYPE_KEY,
+    LINK_MARK,
+    LINK_NAME_KEY,
+    LINK_TYPE_KEY,
+)
+from pytest_test_observer.helper import as_str
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def extract_labels(item: pytest.Item) -> dict[str, list[str]]:
+    labels: dict[str, list[str]] = {}
+    for mark in item.iter_markers(LABEL_MARK):
+        label_type = mark.kwargs.get(LABEL_TYPE_KEY)
+        if label_type is None:
+            continue
+        type_str = as_str(label_type)
+        for value in mark.args:
+            labels.setdefault(type_str, []).append(as_str(value))
+    return labels
+
+
+def extract_links(item: pytest.Item) -> list[tuple[str, str, str]]:
+    links: list[tuple[str, str, str]] = []
+    for mark in item.iter_markers(LINK_MARK):
+        if not mark.args:
+            continue
+        url = as_str(mark.args[0])
+        link_type = as_str(mark.kwargs.get(LINK_TYPE_KEY, ""))
+        link_name = as_str(mark.kwargs.get(LINK_NAME_KEY, ""))
+        links.append((link_type, url, link_name))
+    return links
+
+
+def read_allure_title(item: pytest.Item) -> str:
+    func = getattr(item, "function", None) or getattr(item, "obj", None)
+    if func is None:
+        return ""
+    return str(getattr(func, DISPLAY_NAME_ATTR, "") or "")
+
+
+def first_label_value(labels: dict[str, list[str]], key: str) -> str:
+    values = labels.get(key, ())
+    return values[0] if values else ""

pytest_test_observer/buffer.py

@@ -0,0 +1,51 @@
+"""On-disk JSONL fallback for batches we couldn't push to ClickHouse."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+_BUFFER_SUBDIR = "pytest-test-observer"
+_EXTENSION = ".jsonl"
+
+# Whitelist of characters allowed verbatim in run_id-derived filenames.
+# Anything else (including path separators and `..`) is mapped to '_'.
+_UNSAFE_CHARS = re.compile(r"[^A-Za-z0-9._-]")
+# OS filename limits hover around 255 bytes; leave headroom for the
+# extension and any pathological multi-byte inputs.
+_MAX_RUN_ID = 128
+
+
+def buffer_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / _BUFFER_SUBDIR
+
+
+def write_jsonl(rows: list[dict], run_id: str) -> Path:
+    safe_id = _sanitize_run_id(run_id)
+    path = buffer_dir() / f"{safe_id}{_EXTENSION}"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not rows:
+        return path
+    content = "\n".join(json.dumps(row, default=_json_default) for row in rows) + "\n"
+    with path.open("a", encoding="utf-8") as f:
+        f.write(content)
+    return path
+
+
+def _sanitize_run_id(run_id: str) -> str:
+    cleaned = _UNSAFE_CHARS.sub("_", run_id or "")[:_MAX_RUN_ID]
+    return cleaned or "unknown"
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, datetime):
+        return obj.isoformat(timespec="milliseconds")
+    if isinstance(obj, tuple):
+        return list(obj)
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")

pytest_test_observer/constants.py

@@ -0,0 +1,57 @@
+from enum import StrEnum
+
+from pytest_test_observer.models import _CIProvider
+
+
+class TestStatus(StrEnum):
+    PASSED = "passed"
+    FAILED = "failed"
+    BROKEN = "broken"
+    SKIPPED = "skipped"
+    RERUN = "rerun"
+    UNKNOWN = "unknown"
+
+
+_CI_PROVIDERS: tuple[_CIProvider, ...] = (
+    _CIProvider(
+        name="github",
+        sentinel="GITHUB_ACTIONS",
+        run_id_vars=("GITHUB_RUN_ID",),
+        commit_vars=("GITHUB_SHA",),
+        branch_vars=("GITHUB_HEAD_REF", "GITHUB_REF_NAME"),
+    ),
+    _CIProvider(
+        name="gitlab",
+        sentinel="GITLAB_CI",
+        run_id_vars=("CI_PIPELINE_ID",),
+        commit_vars=("CI_COMMIT_SHA",),
+        branch_vars=("CI_COMMIT_REF_NAME",),
+    ),
+    _CIProvider(
+        name="circle",
+        sentinel="CIRCLECI",
+        run_id_vars=("CIRCLE_BUILD_NUM",),
+        commit_vars=("CIRCLE_SHA1",),
+        branch_vars=("CIRCLE_BRANCH",),
+    ),
+    _CIProvider(
+        name="jenkins",
+        sentinel="JENKINS_URL",
+        run_id_vars=("BUILD_ID", "BUILD_NUMBER"),
+        commit_vars=("GIT_COMMIT",),
+        branch_vars=("GIT_BRANCH",),
+    ),
+)
+
+
+LABEL_MARK = "allure_label"
+LINK_MARK = "allure_link"
+
+LABEL_TYPE_KEY = "label_type"
+LINK_TYPE_KEY = "link_type"
+LINK_NAME_KEY = "name"
+
+SEVERITY_LABEL = "severity"
+ID_LABEL = "as_id"  # LabelType.ID resolves to "as_id" in allure-python-commons
+
+DISPLAY_NAME_ATTR = "__allure_display_name__"

pytest_test_observer/context.py

@@ -0,0 +1,63 @@
+"""Detect CI provider context and read git commit/branch for the current run."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Mapping
+
+from pytest_test_observer.constants import _CI_PROVIDERS
+from pytest_test_observer.models import CIContext
+
+
+def is_ci() -> bool:
+    env = os.environ
+    return any(env.get(p.sentinel) for p in _CI_PROVIDERS)
+
+
+def detect_ci_context() -> CIContext:
+    env = os.environ
+    for provider in _CI_PROVIDERS:
+        if env.get(provider.sentinel):
+            return {
+                "ci_provider": provider.name,
+                "ci_run_id": _first_env(env, provider.run_id_vars),
+                "git_commit": _first_env(env, provider.commit_vars),
+                "git_branch": _first_env(env, provider.branch_vars),
+            }
+    commit, branch = _git_local()
+    return {
+        "ci_provider": "local",
+        "ci_run_id": "",
+        "git_commit": commit,
+        "git_branch": branch,
+    }
+
+
+def _first_env(env: Mapping[str, str], names: tuple[str, ...]) -> str:
+    for name in names:
+        value = env.get(name, "")
+        if value:
+            return value
+    return ""
+
+
+def _git_local() -> tuple[str, str]:
+    return (
+        _run_git(["rev-parse", "HEAD"]),
+        _run_git(["rev-parse", "--abbrev-ref", "HEAD"]),
+    )
+
+
+def _run_git(args: list[str]) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=True,
+        )
+        return result.stdout.strip()
+    except Exception:
+        return ""

pytest_test_observer/helper.py

@@ -0,0 +1,25 @@
+"""Small, plugin-agnostic value-normalisation helpers."""
+
+from __future__ import annotations
+
+import enum
+from typing import Any
+
+
+def as_str(value: Any) -> str:
+    if isinstance(value, enum.Enum):
+        return str(value.value)
+    return str(value)
+
+
+def as_bool(value: Any, default: bool = False) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    s = str(value).strip().lower()
+    if s in ("true", "1", "yes", "on"):
+        return True
+    if s in ("false", "0", "no", "off", ""):
+        return False
+    return default

pytest_test_observer/models.py

@@ -0,0 +1,30 @@
+"""Shared data shapes used across the plugin."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypedDict
+
+
+class AllureMeta(TypedDict):
+    labels: dict[str, list[str]]
+    links: list[tuple[str, str, str]]
+    title: str
+    severity: str
+    allure_id: str
+
+
+class CIContext(TypedDict):
+    ci_provider: str
+    ci_run_id: str
+    git_commit: str
+    git_branch: str
+
+
+@dataclass(frozen=True)
+class _CIProvider:
+    name: str
+    sentinel: str 
+    run_id_vars: tuple[str, ...]
+    commit_vars: tuple[str, ...]
+    branch_vars: tuple[str, ...]

pytest_test_observer/options.py

@@ -0,0 +1,68 @@
+"""CLI / env-var / pyproject.toml-ini option registration and resolution."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pytest
+
+
+# (cli_name, ini_name, env_var, default)
+OPTION_SPECS: tuple[tuple[str, str, str, str | None], ...] = (
+    ("--ch-url", "ch_url", "PYTEST_OBSERVER_CH_URL", None),
+    ("--ch-user", "ch_user", "PYTEST_OBSERVER_CH_USER", "default"),
+    ("--ch-password", "ch_password", "PYTEST_OBSERVER_CH_PASSWORD", ""),
+    ("--ch-db", "ch_db", "PYTEST_OBSERVER_CH_DB", "default"),
+    ("--ch-table", "ch_table", "PYTEST_OBSERVER_CH_TABLE", "pytest_results"),
+    ("--ch-send-from", "ch_send_from", "PYTEST_OBSERVER_CH_SEND_FROM", "any"),
+    ("--ch-auto-migrate", "ch_auto_migrate", "PYTEST_OBSERVER_CH_AUTO_MIGRATE", "true"),
+)
+
+_HELP: dict[str, str] = {
+    "ch_url": "ClickHouse URL (host, host:port, or http(s)://host:port).",
+    "ch_user": "ClickHouse username.",
+    "ch_password": "ClickHouse password.",
+    "ch_db": "ClickHouse database name.",
+    "ch_table": "ClickHouse table name.",
+    "ch_send_from": "When to send: 'any' (default: local + CI) or 'ci' (skip when no CI env detected).",
+    "ch_auto_migrate": "Auto-add missing columns via ALTER TABLE when the schema drifts forward. true/false (default true).",
+}
+
+
+def add_options(parser: pytest.Parser) -> None:
+    group = parser.getgroup("test-observer")
+    for cli, ini, env, _default in OPTION_SPECS:
+        group.addoption(
+            cli,
+            action="store",
+            default=None,
+            help=f"{_HELP[ini]} Also: env {env} or `{ini}` in pyproject.toml [tool.pytest.ini_options].",
+        )
+        parser.addini(ini, _HELP[ini], default=None)
+
+
+def resolve_options(config: pytest.Config) -> dict[str, str | None]:
+    return {
+        ini: _resolve_one(config, cli, ini, env, default) for cli, ini, env, default in OPTION_SPECS
+    }
+
+
+def _resolve_one(
+    config: pytest.Config,
+    cli: str,
+    ini: str,
+    env: str,
+    default: str | None,
+) -> str | None:
+    cli_value = config.getoption(cli)
+    if cli_value is not None:
+        return cli_value
+    env_value = os.environ.get(env)
+    if env_value is not None:
+        return env_value
+    ini_value = config.getini(ini)
+    if ini_value:
+        return ini_value
+    return default

pytest_test_observer/plugin.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+import uuid
+import warnings
+from datetime import datetime, timezone
+
+import pytest
+
+from pytest_test_observer import buffer
+from pytest_test_observer.allure_compat import (
+    detect_allure,
+    empty_allure_meta,
+    extract_allure_meta,
+    map_status,
+)
+from pytest_test_observer.context import detect_ci_context, is_ci
+from pytest_test_observer.helper import as_bool
+from pytest_test_observer.options import add_options, resolve_options
+from pytest_test_observer.reporter import ClickHouseReporter
+
+_USER_PROP_MARKERS = "_test_observer_markers"
+_USER_PROP_ALLURE = "_test_observer_allure"
+_USER_PROP_TIMING = "_test_observer_timing"
+_FLUSH_TIMEOUT = 10.0
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    add_options(parser)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    opts = resolve_options(config)
+    if not opts["ch_url"]:
+        return
+    if str(opts.get("ch_send_from", "any")).lower() == "ci" and not is_ci():
+        return
+    plugin = ObserverPlugin(config, opts)
+    config._test_observer = plugin
+    config.pluginmanager.register(plugin, "test_observer_plugin")
+
+
+def pytest_unconfigure(config: pytest.Config) -> None:
+    plugin = getattr(config, "_test_observer", None)
+    if plugin is not None and config.pluginmanager.is_registered(plugin):
+        config.pluginmanager.unregister(plugin)
+    config._test_observer = None
+
+
+class ObserverPlugin:
+    def __init__(self, config: pytest.Config, opts: dict) -> None:
+        self.config = config
+        self.opts = opts
+        self.is_worker = hasattr(config, "workerinput")
+        self.run_id = os.environ.get("PYTEST_OBSERVER_RUN_ID") or str(uuid.uuid4())
+        self.context = detect_ci_context() if not self.is_worker else {}
+        self.results: list = []
+        self.allure_active = detect_allure(config.pluginmanager)
+
+    @pytest.hookimpl(hookwrapper=True, trylast=True)
+    def pytest_runtest_makereport(self, item: pytest.Item, call: pytest.CallInfo):
+        outcome = yield
+        report = outcome.get_result()
+        markers = sorted({m.name for m in item.iter_markers() if not m.name.startswith("allure_")})
+        report.user_properties.append((_USER_PROP_MARKERS, markers))
+        report.user_properties.append((_USER_PROP_ALLURE, extract_allure_meta(item)))
+        report.user_properties.append(
+            (_USER_PROP_TIMING, (getattr(call, "start", None), getattr(call, "stop", None)))
+        )
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        if self.is_worker or not _should_record(report):
+            return
+        markers, allure_meta, timing = _read_user_properties(report)
+        self.results.append(
+            _build_row(
+                report=report,
+                run_id=self.run_id,
+                markers=markers,
+                allure_meta=allure_meta,
+                timing=timing,
+                context=self.context,
+            )
+        )
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        if self.is_worker or not self.results:
+            return
+
+        reporter = ClickHouseReporter(
+            url=self.opts["ch_url"],
+            user=self.opts["ch_user"],
+            password=self.opts["ch_password"],
+            db=self.opts["ch_db"],
+            table=self.opts["ch_table"],
+            auto_migrate=as_bool(self.opts["ch_auto_migrate"], default=True),
+        )
+        rows = list(self.results)
+        flush_done = threading.Event()
+
+        def _run_flush() -> None:
+            try:
+                reporter.flush(rows, self.run_id)
+            finally:
+                flush_done.set()
+
+        thread = threading.Thread(
+            target=_run_flush,
+            daemon=True,
+            name="test-observer-flush",
+        )
+        thread.start()
+
+        if not flush_done.wait(timeout=_FLUSH_TIMEOUT) and not flush_done.is_set():
+            warnings.warn(
+                "[pytest-test-observer] flush thread timed out; buffering to disk",
+                stacklevel=2,
+            )
+            with contextlib.suppress(Exception):
+                buffer.write_jsonl(rows, self.run_id)
+
+
+def _should_record(report: pytest.TestReport) -> bool:
+    if report.when == "call":
+        return True
+    if report.when == "setup":
+        return bool(report.failed or report.skipped)
+    if report.when == "teardown":
+        return bool(report.failed)
+    return False
+
+
+def _build_row(*, report, run_id, markers, allure_meta, timing, context) -> dict:
+    started, finished = timing
+    return {
+        "run_id": run_id,
+        "timestamp": datetime.now(timezone.utc),
+        "started_at": int(started * 1000) if started else 0,
+        "finished_at": int(finished * 1000) if finished else 0,
+        "nodeid": report.nodeid,
+        "status": map_status(report),
+        "when_phase": report.when,
+        "duration": float(report.duration),
+        "markers": list(markers),
+        "worker_id": _worker_id(report),
+        "ci_provider": context.get("ci_provider", ""),
+        "ci_run_id": context.get("ci_run_id", ""),
+        "git_commit": context.get("git_commit", ""),
+        "git_branch": context.get("git_branch", ""),
+        "allure_id": allure_meta.get("allure_id", ""),
+        "allure_title": allure_meta.get("title", ""),
+        "allure_severity": allure_meta.get("severity", ""),
+        "allure_labels": dict(allure_meta.get("labels", {})),
+        "allure_links": [tuple(link) for link in allure_meta.get("links", [])],
+    }
+
+
+def _read_user_properties(report: pytest.TestReport) -> tuple:
+    markers: list = []
+    allure_meta: dict = empty_allure_meta()
+    timing: tuple = (None, None)
+    for key, value in getattr(report, "user_properties", []):
+        if key == _USER_PROP_MARKERS:
+            markers = value
+        elif key == _USER_PROP_ALLURE:
+            allure_meta = value
+        elif key == _USER_PROP_TIMING:
+            timing = value
+    return markers, allure_meta, timing
+
+
+def _worker_id(report: pytest.TestReport) -> str:
+    try:
+        gw_id = report.node.gateway.id
+    except AttributeError:
+        return "master"
+    return str(gw_id) if gw_id else "master"

pytest_test_observer/replay.py

@@ -0,0 +1,201 @@
+"""Replay buffered JSONL files back into ClickHouse.
+
+When a session-end flush fails (network down, CH unreachable, timeout, etc.),
+each session's rows are written to
+``$XDG_CACHE_HOME/pytest-test-observer/<run_id>.jsonl``. This tool reads those
+files, parses each line, and pushes the rows to ClickHouse. On success the
+buffer file is deleted; on failure it's recreated by the reporter's fallback
+path so a later replay can pick up where this one left off.
+
+Invocation:
+
+    python -m pytest_test_observer.replay --ch-url=localhost:8123
+    python -m pytest_test_observer.replay /path/to/specific.jsonl
+    python -m pytest_test_observer.replay --dry-run
+
+Options mirror the plugin (``--ch-url``, ``--ch-user``, ``--ch-password``,
+``--ch-db``, ``--ch-table``, ``--ch-auto-migrate``) and pick up the same
+``PYTEST_OBSERVER_CH_*`` env vars when set.
+
+Forward-compatibility with older schemas: rows missing any current column
+get a sensible default (empty string / 0 / empty array), so a JSONL file
+written by an older plugin version replays cleanly into the latest table.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import warnings
+from pathlib import Path
+
+from pytest_test_observer.buffer import buffer_dir
+from pytest_test_observer.helper import as_bool
+from pytest_test_observer.reporter import ClickHouseReporter
+from pytest_test_observer.schema import SCHEMA
+
+_DEFAULT_FOR_TYPE: dict = {
+    "String": "",
+    "DateTime64(3)": "",  # ISO string accepted by clickhouse-connect
+    "UInt64": 0,
+    "Float64": 0.0,
+    "LowCardinality(String)": "",
+    "Array(String)": [],
+    "Map(String, Array(String))": {},
+    "Array(Tuple(String, String, String))": [],
+}
+
+# Pre-compute per-column defaults so the inner loop is cheap.
+_COLUMN_DEFAULTS: dict = {name: _DEFAULT_FOR_TYPE.get(type_, "") for name, type_ in SCHEMA}
+
+
+def parse_jsonl_text(text: str) -> tuple[list, int]:
+    rows: list = []
+    skipped = 0
+    for line_num, line in enumerate(text.splitlines(), 1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        try:
+            row = json.loads(stripped)
+        except json.JSONDecodeError as exc:
+            warnings.warn(
+                f"[replay] line {line_num}: not valid JSON ({exc}); skipping",
+                stacklevel=2,
+            )
+            skipped += 1
+            continue
+        if not isinstance(row, dict):
+            warnings.warn(
+                f"[replay] line {line_num}: not a JSON object; skipping",
+                stacklevel=2,
+            )
+            skipped += 1
+            continue
+        for col, default in _COLUMN_DEFAULTS.items():
+            row.setdefault(col, default)
+        rows.append(row)
+    return rows, skipped
+
+
+def replay_file(reporter: ClickHouseReporter, path: Path, *, keep: bool) -> tuple[int, int, bool]:
+    text = path.read_text(encoding="utf-8")
+    rows, skipped = parse_jsonl_text(text)
+    if not rows:
+        return 0, skipped, True
+    if not keep:
+        path.unlink()
+    ok = reporter.flush(rows, path.stem)
+    return len(rows), skipped, ok
+
+
+def find_buffer_files(paths: list) -> list:
+    if not paths:
+        return sorted(buffer_dir().glob("*.jsonl"))
+    files: list = []
+    for p in paths:
+        if p.is_dir():
+            files.extend(sorted(p.glob("*.jsonl")))
+        elif p.exists():
+            files.append(p)
+        else:
+            warnings.warn(f"[replay] no such file or directory: {p}", stacklevel=2)
+    return files
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="python -m pytest_test_observer.replay",
+        description="Replay buffered JSONL files into ClickHouse.",
+    )
+    p.add_argument(
+        "paths",
+        nargs="*",
+        type=Path,
+        help="JSONL files or directories to replay (default: scan buffer dir)",
+    )
+    p.add_argument(
+        "--ch-url",
+        default=os.environ.get("PYTEST_OBSERVER_CH_URL"),
+        help="ClickHouse URL (host, host:port, or http(s)://...) [required]",
+    )
+    p.add_argument("--ch-user", default=os.environ.get("PYTEST_OBSERVER_CH_USER", "default"))
+    p.add_argument("--ch-password", default=os.environ.get("PYTEST_OBSERVER_CH_PASSWORD", ""))
+    p.add_argument("--ch-db", default=os.environ.get("PYTEST_OBSERVER_CH_DB", "default"))
+    p.add_argument(
+        "--ch-table",
+        default=os.environ.get("PYTEST_OBSERVER_CH_TABLE", "pytest_results"),
+    )
+    p.add_argument(
+        "--ch-auto-migrate",
+        default=os.environ.get("PYTEST_OBSERVER_CH_AUTO_MIGRATE", "true"),
+        help="true/false; auto-add missing columns via ALTER TABLE",
+    )
+    p.add_argument(
+        "--keep",
+        action="store_true",
+        help="don't delete buffer files after successful replay",
+    )
+    p.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="list files that would be replayed; don't touch ClickHouse",
+    )
+    return p
+
+
+def main(argv: list | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    files = find_buffer_files(args.paths)
+
+    if not files:
+        print("no buffer files found", file=sys.stderr)
+        return 0
+
+    if args.dry_run:
+        for f in files:
+            line_count = sum(
+                1 for line in f.read_text(encoding="utf-8").splitlines() if line.strip()
+            )
+            print(f"would replay {f}  ({line_count} lines)")
+        return 0
+
+    if not args.ch_url:
+        print(
+            "error: --ch-url is required (or set PYTEST_OBSERVER_CH_URL)",
+            file=sys.stderr,
+        )
+        return 2
+
+    reporter = ClickHouseReporter(
+        url=args.ch_url,
+        user=args.ch_user,
+        password=args.ch_password,
+        db=args.ch_db,
+        table=args.ch_table,
+        auto_migrate=as_bool(args.ch_auto_migrate, default=True),
+    )
+
+    rows_total = 0
+    skipped_total = 0
+    failures: list = []
+    for f in files:
+        rows, skipped, ok = replay_file(reporter, f, keep=args.keep)
+        rows_total += rows
+        skipped_total += skipped
+        status = "ok" if ok else "FAILED (re-buffered)"
+        print(f"  {f}: {rows} rows, {skipped} skipped — {status}")
+        if not ok:
+            failures.append(f)
+
+    print(
+        f"\ndone: {rows_total} rows replayed across {len(files)} files; "
+        f"{skipped_total} malformed lines skipped; {len(failures)} files failed."
+    )
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pytest_test_observer/reporter.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import warnings
+from urllib.parse import urlparse
+
+import clickhouse_connect
+
+from pytest_test_observer import buffer
+from pytest_test_observer.schema import COLUMNS, column_defs_sql, ensure_schema
+
+_METRICS_ENV = "PYTEST_OBSERVER_METRICS_FILE"
+
+# Re-export COLUMNS for callers that imported it from reporter (back-compat).
+__all__ = ("COLUMNS", "CREATE_TABLE_SQL", "ClickHouseReporter", "parse_url")
+
+CREATE_TABLE_SQL = (
+    "CREATE TABLE IF NOT EXISTS {table} (\n    "
+    + column_defs_sql()
+    + "\n) ENGINE = MergeTree\nORDER BY (nodeid, timestamp)\nPARTITION BY toYYYYMM(timestamp)"
+)
+
+
+class ClickHouseReporter:
+    def __init__(
+        self,
+        *,
+        url: str,
+        user: str,
+        password: str,
+        db: str,
+        table: str,
+        auto_migrate: bool = True,
+    ):
+        self.url = url
+        self.user = user
+        self.password = password
+        self.db = db
+        self.table = table
+        self.auto_migrate = auto_migrate
+
+    def flush(self, rows: list, run_id: str) -> bool:
+        if not rows:
+            return True
+        metrics = {
+            "rows": len(rows),
+            "bytes_written": 0,
+            "flush_seconds": 0.0,
+            "ok": False,
+            "migrations_applied": [],
+        }
+        start = time.perf_counter()
+        try:
+            host, port, secure = parse_url(self.url)
+            client = clickhouse_connect.get_client(
+                host=host,
+                port=port,
+                username=self.user,
+                password=self.password,
+                database=self.db,
+                secure=secure,
+                connect_timeout=5,
+                send_receive_timeout=10,
+            )
+            client.command(CREATE_TABLE_SQL.format(table=self.table))
+            added = ensure_schema(client, self.table, auto_migrate=self.auto_migrate)
+            if added:
+                metrics["migrations_applied"] = added
+                warnings.warn(
+                    f"[pytest-test-observer] auto-migrated {self.table!r}: added columns {added}",
+                    stacklevel=2,
+                )
+            data = [[row[c] for c in COLUMNS] for row in rows]
+            summary = client.insert(self.table, data, column_names=list(COLUMNS))
+            metrics["bytes_written"] = _summary_bytes(summary)
+            metrics["ok"] = True
+        except Exception as exc:
+            warnings.warn(
+                f"[pytest-test-observer] flush to ClickHouse failed: {exc!r}; "
+                f"writing {len(rows)} rows to disk buffer",
+                stacklevel=2,
+            )
+            try:
+                path = buffer.write_jsonl(rows, run_id)
+                warnings.warn(
+                    f"[pytest-test-observer] buffered to {path}",
+                    stacklevel=2,
+                )
+            except Exception as exc2:
+                warnings.warn(
+                    f"[pytest-test-observer] disk buffer also failed: {exc2!r}",
+                    stacklevel=2,
+                )
+        finally:
+            metrics["flush_seconds"] = time.perf_counter() - start
+            _maybe_write_metrics(metrics)
+        return metrics["ok"]
+
+
+def _summary_bytes(summary) -> int:
+    if summary is None:
+        return 0
+    payload = getattr(summary, "summary", None) or {}
+    raw = payload.get("written_bytes") or payload.get("read_bytes") or 0
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _maybe_write_metrics(metrics: dict) -> None:
+    path = os.environ.get(_METRICS_ENV)
+    if not path:
+        return
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(metrics, f)
+    except Exception:
+        pass
+
+
+def parse_url(url: str) -> tuple:
+    if "://" in url:
+        parsed = urlparse(url)
+        host = parsed.hostname or ""
+        secure = parsed.scheme == "https"
+        port = parsed.port or (8443 if secure else 8123)
+        return host, port, secure
+    if ":" in url:
+        host, _, port_s = url.partition(":")
+        return host, int(port_s), False
+    return url, 8123, False

pytest_test_observer/schema.py

@@ -0,0 +1,90 @@
+"""ClickHouse schema definition + diff/migrate helpers."""
+
+from __future__ import annotations
+
+import re
+
+SCHEMA: tuple = (
+    ("run_id", "String"),
+    ("timestamp", "DateTime64(3)"),
+    ("started_at", "UInt64"),
+    ("finished_at", "UInt64"),
+    ("nodeid", "String"),
+    ("status", "LowCardinality(String)"),
+    ("when_phase", "LowCardinality(String)"),
+    ("duration", "Float64"),
+    ("markers", "Array(String)"),
+    ("worker_id", "LowCardinality(String)"),
+    ("ci_provider", "LowCardinality(String)"),
+    ("ci_run_id", "String"),
+    ("git_commit", "String"),
+    ("git_branch", "String"),
+    ("allure_id", "String"),
+    ("allure_title", "String"),
+    ("allure_severity", "LowCardinality(String)"),
+    ("allure_labels", "Map(String, Array(String))"),
+    ("allure_links", "Array(Tuple(String, String, String))"),
+)
+
+EXPECTED_SCHEMA: dict = dict(SCHEMA)
+COLUMNS: tuple = tuple(name for name, _ in SCHEMA)
+
+
+def column_defs_sql() -> str:
+    return ",\n    ".join(f"{name} {type_}" for name, type_ in SCHEMA)
+
+
+class SchemaError(Exception):
+    """Raised when the ClickHouse table can't be safely migrated."""
+
+
+def ensure_schema(client, table: str, *, auto_migrate: bool) -> list:
+    actual = _read_actual_columns(client, table)
+
+    type_mismatches = [
+        (name, actual[name], expected_type)
+        for name, expected_type in EXPECTED_SCHEMA.items()
+        if name in actual and not _types_compatible(actual[name], expected_type)
+    ]
+    if type_mismatches:
+        details = "; ".join(f"{n} has {a!r}, expected {e!r}" for n, a, e in type_mismatches)
+        raise SchemaError(
+            f"ClickHouse table {table!r} has incompatible column types ({details}). "
+            "This requires a manual migration — either DROP and recreate the table "
+            "(loses history) or ALTER TABLE MODIFY COLUMN with appropriate care."
+        )
+
+    missing = [(name, type_) for name, type_ in EXPECTED_SCHEMA.items() if name not in actual]
+    if not missing:
+        return []
+
+    if not auto_migrate:
+        sql = "; ".join(f"ALTER TABLE {table} ADD COLUMN {name} {type_}" for name, type_ in missing)
+        raise SchemaError(
+            f"ClickHouse table {table!r} is missing {len(missing)} column(s) "
+            f"and ch_auto_migrate is disabled. Run manually:\n  {sql}"
+        )
+
+    for name, type_ in missing:
+        client.command(f"ALTER TABLE {table} ADD COLUMN IF NOT EXISTS {name} {type_}")
+    return [name for name, _ in missing]
+
+
+def _read_actual_columns(client, table: str) -> dict:
+    result = client.query(
+        "SELECT name, type FROM system.columns "
+        "WHERE database = currentDatabase() AND table = {table:String}",
+        parameters={"table": table},
+    )
+    return {row[0]: row[1] for row in result.result_rows}
+
+
+def _types_compatible(actual: str, expected: str) -> bool:
+    return _normalize(actual) == _normalize(expected)
+
+
+_WS_RE = re.compile(r"\s+")
+
+
+def _normalize(t: str) -> str:
+    return _WS_RE.sub("", t)

pytest_test_observer-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.3
+Name: pytest-test-observer
+Version: 0.1.0
+Summary: A pytest plugin for observing test execution events.
+Author: Dmitrii Shakhov
+Author-email: Dmitrii Shakhov <sourx.rus@gmail.com>
+License: MIT
+Requires-Dist: pytest>=7.0
+Requires-Dist: clickhouse-connect>=0.6.0
+Requires-Dist: allure-pytest>=2.13 ; extra == 'allure'
+Requires-Python: >=3.9
+Provides-Extra: allure
+Description-Content-Type: text/markdown
+
+# pytest-test-observer
+
+An easy-to-use pytest plugin to take your test observability to the next level. Compatible with `allure-pytest`.
+
+## Install
+
+The plugin isn't published to PyPI yet - install from source:
+
+```bash
+uv add --editable git+https://github.com/shakhov-dmitrii/pytest-test-observer
+# or for development inside a clone:
+uv sync
+```
+
+For Allure support, install the extra:
+
+```bash
+uv add "pytest-test-observer[allure]"
+```
+
+## Quick start
+
+1. Start a local ClickHouse **and Grafana**:
+
+   ```bash
+   docker compose up -d
+   ```
+
+   This brings up:
+   - ClickHouse on <http://localhost:8123> (HTTP) and `:9000` (native)
+   - Grafana on <http://localhost:3000> (login: `admin` / `admin`) with the ClickHouse datasource auto-provisioned and a starter dashboard pre-loaded.
+
+2. Run your tests with the ClickHouse URL:
+
+   ```bash
+   pytest --ch-url=localhost:8123 --ch-table=pytest_results
+   ```
+
+3. Inspect the rows - either via SQL:
+
+   ```bash
+   docker exec -it pytest-test-observer-clickhouse clickhouse-client \
+     -q "SELECT nodeid, status, duration, ci_provider FROM default.pytest_results ORDER BY timestamp DESC LIMIT 20 FORMAT PrettyCompact"
+   ```
+
+   or in the dashboard: <http://localhost:3000/d/pytest-test-observer-overview>
+
+If `--ch-url` is not provided, it does nothing and adds no overhead.
+
+## Configuration
+
+Every connection setting can be supplied three ways, resolved in this order (highest priority first):
+
+1. **CLI flag** - `pytest --ch-url=...`
+2. **Environment variable** - `PYTEST_OBSERVER_CH_URL=...`
+3. **pyproject.toml** - `ch_url = "..."` under `[tool.pytest.ini_options]` (or any other pytest config file)
+4. Built-in default
+
+| CLI flag           | Env var                          | Ini key (`pyproject.toml`) | Default          |
+| ------------------ | -------------------------------- | -------------------------- | ---------------- |
+| `--ch-url`         | `PYTEST_OBSERVER_CH_URL`         | `ch_url`                   | none             |
+| `--ch-user`        | `PYTEST_OBSERVER_CH_USER`        | `ch_user`                  | `default`        |
+| `--ch-password`    | `PYTEST_OBSERVER_CH_PASSWORD`    | `ch_password`              | `""`             |
+| `--ch-db`          | `PYTEST_OBSERVER_CH_DB`          | `ch_db`                    | `default`        |
+| `--ch-table`       | `PYTEST_OBSERVER_CH_TABLE`       | `ch_table`                 | `pytest_results` |
+| `--ch-send-from`   | `PYTEST_OBSERVER_CH_SEND_FROM`   | `ch_send_from`             | `any`            |
+| `--ch-auto-migrate`| `PYTEST_OBSERVER_CH_AUTO_MIGRATE`| `ch_auto_migrate`          | `true`           |
+
+### `--ch-send-from`: where rows come from
+
+- `any` (default) - send for both local and CI runs.
+- `ci` - only send when a provider-specific CI sentinel is set (`GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, or `JENKINS_URL`).
+
+### `--ch-auto-migrate`: schema migrations across plugin versions
+
+When a new plugin version adds columns, the plugin auto-applies `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` for each missing column. Existing rows get the column's default value. Old data doesn't change.
+
+If your team's policy forbids the plugin running DDL, set `ch_auto_migrate = false` in `pyproject.toml` (or the env / CLI equivalent). The plugin will then refuse to migrate and surface the SQL you'd need to run yourself.
+
+### Example: defaults into `pyproject.toml`
+
+```toml
+[tool.pytest.ini_options]
+ch_url   = "clickhouse.internal:8123"
+ch_db    = "ci_metrics"
+ch_table = "pytest_results"
+```
+
+Then a plain `pytest` picks them up - no flags, no env vars.
+
+### Example: CI secret via env var
+
+```yaml
+# GitHub Actions
+- run: pytest
+  env:
+    PYTEST_OBSERVER_CH_URL: ${{ secrets.CLICKHOUSE_URL }}
+    PYTEST_OBSERVER_CH_PASSWORD: ${{ secrets.CLICKHOUSE_PASSWORD }}
+```
+
+### Other environment variables
+
+| Variable                    | Effect                                                           |
+| --------------------------- | ---------------------------------------------------------------- |
+| `PYTEST_OBSERVER_RUN_ID`    | Override the auto-generated `run_id` (UUID) for the session      |
+| `XDG_CACHE_HOME`            | Base directory for the disk-buffer fallback                      |
+
+## ClickHouse schema
+
+The table is auto-created on first flush:
+
+```sql
+CREATE TABLE IF NOT EXISTS pytest_results (
+    run_id             String,
+    timestamp          DateTime64(3),           
+    started_at         UInt64,                  
+    finished_at        UInt64,                  
+    nodeid             String,
+    status             LowCardinality(String),  
+    when_phase         LowCardinality(String),  
+    duration           Float64,
+    markers            Array(String),           
+    worker_id          LowCardinality(String),  
+    ci_provider        LowCardinality(String),  
+    ci_run_id          String,
+    git_commit         String,
+    git_branch         String,
+    allure_id          String,
+    allure_title       String,
+    allure_severity    LowCardinality(String),
+    allure_labels      Map(String, Array(String)),
+    allure_links       Array(Tuple(String, String, String))
+) ENGINE = MergeTree
+ORDER BY (nodeid, timestamp)
+PARTITION BY toYYYYMM(timestamp);
+```
+
+## Allure compatibility
+
+When `allure-pytest` is installed and tests use the standard Allure decorators, the plugin captures:
+
+- Labels (`@allure.feature`, `@allure.story`, `@allure.tag`, `@allure.severity`, `@allure.id`, `@allure.epic`, `@allure.suite`, ...) -> `allure_labels`
+- Links (`@allure.link`, `@allure.issue`, `@allure.testcase`) -> `allure_links`
+- `@allure.title(...)` -> `allure_title`
+- `@allure.severity(...)` -> `allure_severity` (also stored in `allure_labels`)
+- `@allure.id(...)` -> `allure_id`
+
+## CI / git context detection
+
+Detected automatically.
+
+| Provider       | Env vars used                                                                        |
+| -------------- | -------------------------------------------------------------------------------------|
+| GitHub Actions | `GITHUB_ACTIONS`, `GITHUB_RUN_ID`, `GITHUB_SHA`, `GITHUB_HEAD_REF`/`GITHUB_REF_NAME` |
+| GitLab CI      | `GITLAB_CI`, `CI_PIPELINE_ID`, `CI_COMMIT_SHA`, `CI_COMMIT_REF_NAME`                 |
+| CircleCI       | `CIRCLECI`, `CIRCLE_BUILD_NUM`, `CIRCLE_SHA1`, `CIRCLE_BRANCH`                       |
+| Jenkins        | `JENKINS_URL`, `BUILD_ID`/`BUILD_NUMBER`, `GIT_COMMIT`, `GIT_BRANCH`                 |
+| Local          | `git rev-parse HEAD` and `git rev-parse --abbrev-ref HEAD` (`ci_provider="local"`)   |
+
+## Disk buffer fallback
+
+When ClickHouse is unreachable, slow, or rejects the insert, the batch is written to:
+
+```
+$XDG_CACHE_HOME/pytest-test-observer/<run_id>.jsonl   # or ~/.cache/... if unset
+```
+
+One JSON object per line, keys identical to the ClickHouse columns. The plugin emits a `warnings.warn` with the path. **The pytest exit code is unaffected.**
+
+### Replaying buffered files back into ClickHouse
+
+Once ClickHouse is reachable again, run:
+
+```bash
+python -m pytest_test_observer.replay --ch-url=localhost:8123
+# or pick specific files:
+python -m pytest_test_observer.replay /path/to/run-abc.jsonl
+# or just see what would happen:
+python -m pytest_test_observer.replay --dry-run
+```
+
+All the `PYTEST_OBSERVER_CH_*` env vars from the configuration table are honoured by the replay tool too.
+
+## Example queries
+
+```sql
+-- Top 10 flakiest tests in the last 30 days
+SELECT
+    nodeid,
+    countIf(status IN ('failed','broken')) AS non_passes,
+    count() AS total,
+    non_passes / total AS flakiness
+FROM pytest_results
+WHERE timestamp > now() - INTERVAL 30 DAY
+GROUP BY nodeid
+HAVING total >= 10 AND non_passes > 0
+ORDER BY flakiness DESC
+LIMIT 10;
+
+-- Slowest 10 tests (median duration)
+SELECT nodeid, quantileExact(0.5)(duration) AS p50_seconds, count() AS runs
+FROM pytest_results
+WHERE timestamp > now() - INTERVAL 7 DAY AND status = 'passed'
+GROUP BY nodeid
+ORDER BY p50_seconds DESC
+LIMIT 10;
+```
+
+## License
+
+This project is licensed under the MIT License.
+See the LICENSE file for details.

pytest_test_observer-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+pytest_test_observer/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pytest_test_observer/allure_compat.py,sha256=hNm7Eq1HsxL9Hj5YPG7qJaOvYa-3DPNsGKM5ENlUsnc,1986
+pytest_test_observer/allure_compat_helpers.py,sha256=Vyrwy58qDguKZnhd14VkavE8GrerbH_V5mt4VACLZqI,1522
+pytest_test_observer/buffer.py,sha256=fo6hwkUluESsjXWcLMzAY8cxk4rY6Go2SUtSkP9_nrU,1595
+pytest_test_observer/constants.py,sha256=UlL6FZE50lCybOrIFzQ8whmaBJIvPvp5k7P3sKehPUQ,1405
+pytest_test_observer/context.py,sha256=6-vNjz92_XAkt_oIZpcIVOoq1V-B_pXUry-RRSnPh9c,1628
+pytest_test_observer/helper.py,sha256=tvsvqmwHvblrz3w6f7MGfKLdsOk5w7d5ydStIsq4_JA,590
+pytest_test_observer/models.py,sha256=AulyJDaI8Eho8ATdsHlxr1C5IDo0dAtG9Z4o627FFa8,590
+pytest_test_observer/options.py,sha256=qSWBoScjfnh9XqesYCJaxXcbbhEJRzowaQ1ZTL_rTCw,2324
+pytest_test_observer/plugin.py,sha256=dSVoKBtrg1Ueq8t4ZNZZZMT35qEUdR0Kl4-CF5n9Pmc,6253
+pytest_test_observer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_test_observer/replay.py,sha256=Ph4tVth0WawvTt_rEpHL2PFYvUK42nzyt8VvR37xdlA,6515
+pytest_test_observer/reporter.py,sha256=__Xtb98dgLZNPQWj3L3G6SLZn4qBE3I8ndjeKudBaU0,4186
+pytest_test_observer/schema.py,sha256=SX3Qih_jDR9KfexnzGMTalxJU7oGNcclzvtSBc5cxB8,2995
+pytest_test_observer-0.1.0.dist-info/WHEEL,sha256=mydTeHxOpFHo-DnYhAd_3ATePms-g4rrYvM7wJK8P-U,80
+pytest_test_observer-0.1.0.dist-info/entry_points.txt,sha256=5V4PR2th3XvrXC_oObaQN01AHLvSG2PojUYgSxrU6Ck,56
+pytest_test_observer-0.1.0.dist-info/METADATA,sha256=CWQe642ERAr34hvu1wfUpxXhTnJrwh104D3cF3dLw4M,8483
+pytest_test_observer-0.1.0.dist-info/RECORD,,

pytest_test_observer-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.9
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_test_observer-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+test_observer = pytest_test_observer.plugin
+