pytest-test-observer 0.1.0__tar.gz

pytest_test_observer-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,212 @@
+# 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/pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "pytest-test-observer"
+version = "0.1.0"
+description = "A pytest plugin for observing test execution events."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Dmitrii Shakhov", email = "sourx.rus@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pytest>=7.0",
+    "clickhouse-connect>=0.6.0",
+]
+
+[project.optional-dependencies]
+allure = ["allure-pytest>=2.13"]
+
+[project.entry-points.pytest11]
+test_observer = "pytest_test_observer.plugin"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "allure-pytest>=2.13",
+    "pytest-xdist>=3.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "ignore:The configuration option \"asyncio_default_fixture_loop_scope\":pytest.PytestDeprecationWarning",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/pytest_test_observer"]
+omit = []
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+precision = 1
+fail_under = 90
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "@overload",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+extend-exclude = [".venv", "dist", "build"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # bugbear
+    "UP",  # pyupgrade
+    "SIM", # simplify
+    "RUF", # ruff-specific
+]
+ignore = [
+    "E501", # line length is enforced by formatter, not the linter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]   # `assert False` is fine in tests
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

pytest_test_observer-0.1.0/src/pytest_test_observer/__init__.py

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

pytest_test_observer-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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")