testrelic-playwright 0.1.0__py3-none-any.whl

testrelic_playwright/__init__.py

@@ -0,0 +1,61 @@
+"""TestRelic Playwright analytics — pytest plugin and helpers."""
+
+from __future__ import annotations
+
+from testrelic_playwright._version import __version__
+from testrelic_playwright.config import (
+    DEFAULT_REDACT_BODY_FIELDS,
+    DEFAULT_REDACT_HEADERS,
+    DEFAULT_REDACTION_PATTERNS,
+    ReporterConfig,
+    resolve_config,
+)
+from testrelic_playwright.merge import merge_reports
+from testrelic_playwright.reporter import record_navigation
+from testrelic_playwright.schema import (
+    ATTACHMENT_CONTENT_TYPE,
+    ATTACHMENT_NAME,
+    PAYLOAD_VERSION,
+    SCHEMA_VERSION,
+)
+from testrelic_playwright.types import (
+    ApiAssertion,
+    ApiCallRecord,
+    AssertionLocation,
+    AssertionType,
+    CIMetadata,
+    FailureDiagnostic,
+    NavigationType,
+    NetworkStats,
+    Summary,
+    TestResult,
+    TestRunReport,
+    TimelineEntry,
+)
+
+__all__ = [
+    "ATTACHMENT_CONTENT_TYPE",
+    "ATTACHMENT_NAME",
+    "ApiAssertion",
+    "ApiCallRecord",
+    "AssertionLocation",
+    "AssertionType",
+    "CIMetadata",
+    "DEFAULT_REDACTION_PATTERNS",
+    "DEFAULT_REDACT_BODY_FIELDS",
+    "DEFAULT_REDACT_HEADERS",
+    "FailureDiagnostic",
+    "NavigationType",
+    "NetworkStats",
+    "PAYLOAD_VERSION",
+    "ReporterConfig",
+    "SCHEMA_VERSION",
+    "Summary",
+    "TestResult",
+    "TestRunReport",
+    "TimelineEntry",
+    "__version__",
+    "merge_reports",
+    "record_navigation",
+    "resolve_config",
+]

testrelic_playwright/_version.py

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

testrelic_playwright/api_request_tracker.py

@@ -0,0 +1,140 @@
+"""Track Playwright network requests/responses for the active test."""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from testrelic_playwright.config import ReporterConfig
+from testrelic_playwright.redaction import redact_body, redact_headers, redact_text
+from testrelic_playwright.types import ApiCallRecord, NetworkStats
+
+
+def _match_any(url: str, patterns: list[str]) -> bool:
+    if not patterns:
+        return False
+    parsed = urlparse(url)
+    needle = parsed.path or url
+    for pat in patterns:
+        if "*" in pat:
+            simplified = pat.replace("**", "*").replace("*", "")
+            if simplified and simplified in url:
+                return True
+        elif pat in url or pat in needle:
+            return True
+    return False
+
+
+class ApiRequestTracker:
+    """Per-test buffer of HTTP requests with optional URL allow/deny lists."""
+
+    def __init__(self, config: ReporterConfig) -> None:
+        self._config = config
+        self._calls: list[ApiCallRecord] = []
+        self._pending: dict[int, dict[str, Any]] = {}
+        self._stats = {"totalRequests": 0, "failedRequests": 0, "totalBytes": 0}
+        self._by_type: dict[str, int] = {}
+
+    @property
+    def calls(self) -> list[ApiCallRecord]:
+        return list(self._calls)
+
+    def network_stats(self) -> NetworkStats:
+        return NetworkStats(
+            totalRequests=self._stats["totalRequests"],
+            failedRequests=self._stats["failedRequests"],
+            totalBytes=self._stats["totalBytes"],
+            byType=dict(self._by_type),
+        )
+
+    def on_request(self, request: Any) -> None:
+        if not self._config.track_api_calls:
+            return
+        url = getattr(request, "url", "")
+        if self._config.api_include_urls and not _match_any(url, self._config.api_include_urls):
+            return
+        if _match_any(url, self._config.api_exclude_urls):
+            return
+
+        self._stats["totalRequests"] += 1
+        rtype = getattr(request, "resource_type", None) or "other"
+        self._by_type[rtype] = self._by_type.get(rtype, 0) + 1
+
+        entry: dict[str, Any] = {
+            "method": getattr(request, "method", "GET"),
+            "url": url,
+            "startedAt": datetime.now(timezone.utc).isoformat(),
+            "_start": time.monotonic(),
+        }
+        if self._config.capture_request_headers:
+            entry["requestHeaders"] = redact_headers(
+                dict(getattr(request, "headers", {}) or {}),
+                self._config.redact_headers,
+            )
+        if self._config.capture_request_body:
+            entry["requestBody"] = self._capture_body(getattr(request, "post_data", None))
+        self._pending[id(request)] = entry
+
+    def on_response(self, response: Any) -> None:
+        request = getattr(response, "request", None)
+        if request is None:
+            return
+        entry = self._pending.pop(id(request), None)
+        if entry is None:
+            return
+
+        status = getattr(response, "status", None)
+        if isinstance(status, int) and status >= 400:
+            self._stats["failedRequests"] += 1
+
+        try:
+            body_bytes = response.body() if self._config.capture_response_body else b""
+        except Exception:  # noqa: BLE001
+            body_bytes = b""
+
+        self._stats["totalBytes"] += len(body_bytes)
+
+        entry["statusCode"] = status
+        entry["durationMs"] = round((time.monotonic() - entry.pop("_start")) * 1000, 2)
+
+        if self._config.capture_response_headers:
+            entry["responseHeaders"] = redact_headers(
+                dict(getattr(response, "headers", {}) or {}),
+                self._config.redact_headers,
+            )
+
+        if self._config.capture_response_body:
+            entry["responseBody"] = self._capture_body(body_bytes)
+
+        self._calls.append(ApiCallRecord.model_validate(entry))
+
+    def on_request_failed(self, request: Any) -> None:
+        entry = self._pending.pop(id(request), None)
+        self._stats["failedRequests"] += 1
+        if entry is None:
+            return
+        entry["statusCode"] = None
+        entry["durationMs"] = round((time.monotonic() - entry.pop("_start")) * 1000, 2)
+        entry["responseBody"] = {"error": getattr(request, "failure", None)}
+        self._calls.append(ApiCallRecord.model_validate(entry))
+
+    def _capture_body(self, raw: Any) -> Any:
+        if raw is None:
+            return None
+        if isinstance(raw, bytes):
+            try:
+                raw = raw.decode("utf-8")
+            except UnicodeDecodeError:
+                return f"<{len(raw)} bytes binary>"
+        if isinstance(raw, str):
+            try:
+                parsed = json.loads(raw)
+                return redact_body(parsed, self._config.redact_body_fields)
+            except (TypeError, ValueError):
+                return redact_text(raw, self._config.resolved_redact_patterns)
+        if isinstance(raw, (dict, list)):
+            return redact_body(raw, self._config.redact_body_fields)
+        return raw

testrelic_playwright/ci_detector.py

@@ -0,0 +1,82 @@
+"""Detect CI provider and pull build metadata from environment variables."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from testrelic_playwright.types import CIMetadata
+
+
+def detect_ci() -> Optional[CIMetadata]:
+    """Return a populated `CIMetadata` if we recognise the CI provider."""
+    env = os.environ
+
+    if env.get("GITHUB_ACTIONS") == "true":
+        return CIMetadata(
+            provider="github-actions",
+            buildId=env.get("GITHUB_RUN_ID"),
+            commitSha=env.get("GITHUB_SHA"),
+            branch=env.get("GITHUB_REF_NAME"),
+            prNumber=_extract_pr_number(env.get("GITHUB_REF")),
+            workflow=env.get("GITHUB_WORKFLOW"),
+            runUrl=_github_run_url(env),
+        )
+
+    if env.get("GITLAB_CI") == "true":
+        return CIMetadata(
+            provider="gitlab-ci",
+            buildId=env.get("CI_PIPELINE_ID"),
+            commitSha=env.get("CI_COMMIT_SHA"),
+            branch=env.get("CI_COMMIT_REF_NAME"),
+            prNumber=env.get("CI_MERGE_REQUEST_IID"),
+            workflow=env.get("CI_JOB_NAME"),
+            runUrl=env.get("CI_PIPELINE_URL"),
+        )
+
+    if env.get("JENKINS_URL"):
+        return CIMetadata(
+            provider="jenkins",
+            buildId=env.get("BUILD_ID") or env.get("BUILD_NUMBER"),
+            commitSha=env.get("GIT_COMMIT"),
+            branch=env.get("GIT_BRANCH"),
+            workflow=env.get("JOB_NAME"),
+            runUrl=env.get("BUILD_URL"),
+        )
+
+    if env.get("CIRCLECI") == "true":
+        return CIMetadata(
+            provider="circleci",
+            buildId=env.get("CIRCLE_BUILD_NUM"),
+            commitSha=env.get("CIRCLE_SHA1"),
+            branch=env.get("CIRCLE_BRANCH"),
+            prNumber=_pr_from_url(env.get("CIRCLE_PULL_REQUEST")),
+            workflow=env.get("CIRCLE_JOB"),
+            runUrl=env.get("CIRCLE_BUILD_URL"),
+        )
+
+    return None
+
+
+def _extract_pr_number(ref: Optional[str]) -> Optional[str]:
+    if not ref:
+        return None
+    parts = ref.split("/")
+    if len(parts) >= 3 and parts[1] == "pull":
+        return parts[2]
+    return None
+
+
+def _github_run_url(env: dict[str, str]) -> Optional[str]:
+    server = env.get("GITHUB_SERVER_URL")
+    repo = env.get("GITHUB_REPOSITORY")
+    run = env.get("GITHUB_RUN_ID")
+    if server and repo and run:
+        return f"{server}/{repo}/actions/runs/{run}"
+    return None
+
+
+def _pr_from_url(url: Optional[str]) -> Optional[str]:
+    if not url:
+        return None
+    return url.rstrip("/").split("/")[-1] or None

testrelic_playwright/cli.py

@@ -0,0 +1,93 @@
+"""`testrelic-playwright` CLI.
+
+Two subcommands mirror the JS package:
+    testrelic-playwright merge a.json b.json -o merged.json
+    testrelic-playwright serve ./test-results/
+
+Plus a `version` helper.
+"""
+
+from __future__ import annotations
+
+import http.server
+import json
+import socketserver
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from testrelic_playwright._version import __version__
+from testrelic_playwright.merge import merge_reports
+
+app = typer.Typer(
+    name="testrelic-playwright",
+    help="TestRelic Playwright analytics CLI",
+    add_completion=False,
+)
+
+
+@app.command()
+def version() -> None:
+    """Print the package version."""
+    typer.echo(__version__)
+
+
+@app.command()
+def merge(
+    inputs: list[Path] = typer.Argument(..., help="Shard JSON reports to merge."),
+    output: Path = typer.Option(
+        "merged-report.json", "-o", "--output", help="Path to the merged JSON output."
+    ),
+) -> None:
+    """Combine multiple shard reports into a single JSON file."""
+    report = merge_reports(inputs, output=output)
+    typer.echo(f"[testrelic] merged {len(inputs)} reports -> {output}")
+    typer.echo(json.dumps(report.summary.model_dump(), indent=2))
+
+
+@app.command()
+def serve(
+    directory: Path = typer.Argument(..., help="Folder containing the HTML / JSON report."),
+    port: int = typer.Option(9323, "--port", help="Port to listen on (default 9323)."),
+    host: str = typer.Option("127.0.0.1", "--host", help="Address to bind to."),
+) -> None:
+    """Serve the HTML report locally (matches `npx testrelic serve`)."""
+    target = directory.resolve()
+    if not target.is_dir():
+        raise typer.BadParameter(f"{target} is not a directory")
+
+    handler = _make_handler(target)
+    with socketserver.TCPServer((host, port), handler) as server:
+        typer.echo(f"[testrelic] serving {target} at http://{host}:{port}/")
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            typer.echo("\n[testrelic] stopped")
+
+
+@app.command(name="drain")
+def drain(
+    queue_dir: Optional[Path] = typer.Option(
+        None,
+        "--queue-dir",
+        help="Override the queue directory. Defaults to .testrelic/queue/.",
+    ),
+) -> None:
+    """Retry queued failed uploads."""
+    from testrelic_playwright.cloud.queue import drain_queue
+
+    counts = drain_queue(queue_dir)
+    typer.echo(json.dumps(counts, indent=2))
+
+
+def _make_handler(root: Path) -> type[http.server.SimpleHTTPRequestHandler]:
+    class Handler(http.server.SimpleHTTPRequestHandler):
+        def __init__(self, *args: object, **kwargs: object) -> None:
+            super().__init__(*args, directory=str(root), **kwargs)  # type: ignore[arg-type]
+
+    return Handler
+
+
+if __name__ == "__main__":
+    app()

testrelic_playwright/cloud/__init__.py

@@ -0,0 +1,13 @@
+"""Cloud upload package.
+
+Public surface intentionally mirrors the JS `cloud-*` modules:
+    CloudUploader  - synchronous client that POSTs the batch payload
+    drain_queue    - replay failed uploads from disk
+"""
+
+from __future__ import annotations
+
+from testrelic_playwright.cloud.client import CloudUploader
+from testrelic_playwright.cloud.queue import drain_queue
+
+__all__ = ["CloudUploader", "drain_queue"]

testrelic_playwright/cloud/client.py

@@ -0,0 +1,52 @@
+"""HTTP client for uploading TestRelic reports to the cloud platform."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from testrelic_playwright._version import __version__
+from testrelic_playwright.cloud.queue import enqueue
+from testrelic_playwright.config import CloudConfig
+from testrelic_playwright.types import TestRunReport
+
+logger = logging.getLogger("testrelic")
+
+
+class CloudUploader:
+    """Single-shot uploader. POSTs the full batch payload then closes the client."""
+
+    def __init__(self, config: CloudConfig) -> None:
+        self._config = config
+
+    def send(self, report: TestRunReport) -> dict[str, Any]:
+        if not self._config.api_key:
+            raise RuntimeError("Cloud upload attempted without an apiKey.")
+
+        url = f"{self._config.endpoint.rstrip('/')}/test-runs"
+        payload = report.model_dump(by_alias=True)
+        headers = {
+            "Authorization": f"Bearer {self._config.api_key}",
+            "User-Agent": f"testrelic-playwright/{__version__}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        timeout = self._config.timeout / 1000
+
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                response = client.post(url, json=payload, headers=headers)
+            response.raise_for_status()
+            return response.json() if response.content else {}
+        except (httpx.HTTPError, ValueError) as exc:
+            queue_path = enqueue(
+                payload,
+                queue_dir=self._config.queue_directory,
+            )
+            logger.warning(
+                "[testrelic] cloud upload failed (%s); queued to %s", exc, queue_path
+            )
+            return {"queued": True, "path": str(queue_path)}

testrelic_playwright/cloud/queue.py

@@ -0,0 +1,83 @@
+"""Persist and replay failed uploads.
+
+The on-disk format is `.testrelic/queue/<uuid>.json` — the same convention used
+by the JS package, so a single queue directory can be drained by either
+runtime.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from testrelic_playwright._version import __version__
+
+logger = logging.getLogger("testrelic")
+_DEFAULT_QUEUE = Path(".testrelic") / "queue"
+
+
+def _resolve_queue_dir(directory: Optional[Path | str]) -> Path:
+    path = Path(directory) if directory else _DEFAULT_QUEUE
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def enqueue(payload: dict[str, Any], *, queue_dir: Optional[Path | str] = None) -> Path:
+    """Write a payload to disk for later retry."""
+    target = _resolve_queue_dir(queue_dir)
+    entry = {
+        "id": str(uuid.uuid4()),
+        "payload": payload,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+    out = target / f"{entry['id']}.json"
+    out.write_text(json.dumps(entry, indent=2), encoding="utf-8")
+    return out
+
+
+def drain_queue(queue_dir: Optional[Path | str] = None) -> dict[str, int]:
+    """Replay every queued payload to TestRelic. Returns {sent, failed, remaining}."""
+    import os
+
+    api_key = os.environ.get("TESTRELIC_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set TESTRELIC_API_KEY before draining the queue.")
+    endpoint = os.environ.get(
+        "TESTRELIC_CLOUD_ENDPOINT", "https://platform.testrelic.ai/api/v1"
+    ).rstrip("/")
+
+    target = _resolve_queue_dir(queue_dir)
+    files = sorted(target.glob("*.json"))
+    if not files:
+        return {"sent": 0, "failed": 0, "remaining": 0}
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": f"testrelic-playwright/{__version__}",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+    sent = failed = 0
+    with httpx.Client(timeout=30.0) as client:
+        for file in files:
+            try:
+                entry = json.loads(file.read_text(encoding="utf-8"))
+                response = client.post(
+                    f"{endpoint}/test-runs", json=entry["payload"], headers=headers
+                )
+                response.raise_for_status()
+                file.unlink()
+                sent += 1
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[testrelic] failed to replay %s: %s", file.name, exc)
+                failed += 1
+
+    remaining = len(list(target.glob("*.json")))
+    return {"sent": sent, "failed": failed, "remaining": remaining}

testrelic_playwright/code_extractor.py

@@ -0,0 +1,29 @@
+"""Extract source-code snippets around a failure line."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+
+def extract_snippet(file_path: str, line: int, context: int = 3) -> Optional[str]:
+    """Return `2*context+1` lines centred on `line` (1-indexed) or None."""
+    try:
+        path = Path(file_path)
+        if not path.is_file():
+            return None
+        lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return None
+
+    if line <= 0 or line > len(lines):
+        return None
+
+    start = max(1, line - context)
+    end = min(len(lines), line + context)
+    width = len(str(end))
+    rendered: list[str] = []
+    for idx in range(start, end + 1):
+        marker = ">" if idx == line else " "
+        rendered.append(f"{marker} {str(idx).rjust(width)} | {lines[idx - 1]}")
+    return "\n".join(rendered)