Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

6.8 KB
Raw Blame
"""Coverage helpers.

Each group runs with its own ``COVERAGE_FILE`` so parallel pytest invocations
don't trample each other. After all groups complete, ``combine_and_report``
merges them into a single ``.coverage`` and emits XML/HTML.
"""

from __future__ import annotations

import logging
import os
import shutil
import subprocess
import sys
from pathlib import Path

from tests.rig.groups import REPO_ROOT

log = logging.getLogger(__name__)

# Cap each coverage subprocess. Runs after the per-group loop, so per-group
# timeouts don't apply; without this a slow `uv run --with` resolve could hang
# the job to the CI ceiling.
_COVERAGE_TIMEOUT_SECONDS = 300


def _clean_env() -> dict[str, str]:
    """Env for ``uv run`` that drops a leaked ``VIRTUAL_ENV`` (e.g. tox's
    ``.tox/<env>``) so uv resolves the project venv without a mismatch warning.

    Also strips ``COVERAGE_FILE``: per-group coverage files are scoped via the
    subprocess env that ``coverage_env()`` builds, never via the rig parent's
    own environ. If the rig is itself running under coverage (e.g. the unit-rig
    self-tests of ``combine_and_report``), an inherited ``COVERAGE_FILE`` would
    redirect ``coverage combine``'s output back into the parent's data file and
    either corrupt it or fail with `no such table: coverage_schema`.
    """
    env = os.environ.copy()
    env.pop("VIRTUAL_ENV", None)
    env.pop("UV_PROJECT_ENVIRONMENT", None)
    env.pop("COVERAGE_FILE", None)
    return env


def coverage_env(group_name: str, reports_dir: Path) -> dict[str, str]:
    """Env vars to scope a group's coverage file under ``reports_dir``."""
    cov_file = reports_dir / f".coverage.{group_name}"
    cov_file.parent.mkdir(parents=True, exist_ok=True)
    return {"COVERAGE_FILE": str(cov_file)}


def _coverage_base() -> list[str]:
    """Pick a runner for ``coverage`` that has the package available.

    Prefers ``uv run --with coverage`` so the same dependency-resolution
    strategy as the test runs is used, and ``coverage`` doesn't need to be
    installed in the parent interpreter. Falls back to ``python -m coverage``
    if uv isn't around.
    """
    if shutil.which("uv"):
        return ["uv", "run", "--with", "coverage[toml]", "coverage"]
    return [sys.executable, "-m", "coverage"]


def combine_and_report(reports_dir: Path) -> None:
    """Combine all per-group ``.coverage.<group>`` files and emit xml + html.

    Combine runs in ``reports_dir`` so the .coverage files are colocated; xml
    and html run from ``REPO_ROOT`` so coverage can resolve the original source
    file paths (stored as repo-relative in ``COVERAGE_FILE`` thanks to
    ``[tool.coverage.run].relative_files = true``).

    This is called once per tier invocation (``tox -e unit`` then
    ``tox -e integration`` run as separate processes). ``coverage combine``
    consumes its inputs, so a fresh combine of only this tier's files would
    discard an earlier tier's merged data. To carry it forward we rename the
    existing ``reports/.coverage`` to a suffixed ``.coverage.<tag>`` and feed
    it back in as an input — ``coverage combine`` only picks up suffixed data
    files, never a bare ``.coverage`` (that's the output target), so the
    rename is required. The result is the union across every tier that ran.

    Errors are logged (not raised) because a coverage failure shouldn't drop
    the test run's exit code.
    """
    files = sorted(reports_dir.glob(".coverage.*"))
    target = reports_dir / ".coverage"
    # Carry the prior tier's merged data forward. `coverage combine` ignores a
    # bare `.coverage` arg (it's the output), so promote it to a suffixed
    # input name. `__prior__` sorts before tier files but order is irrelevant
    # to the union; the suffix just needs to match the `.coverage.*` glob.
    if target.exists():
        prior = reports_dir / ".coverage.__prior__"
        try:
            target.rename(prior)
        except OSError as exc:
            # Degrade like every other coverage step: log + continue. A raise
            # here would propagate past `cmd_run`'s try/finally (both call
            # sites — `cli.py` `cmd_run` post-loop and `cmd_report` — sit
            # outside it), replacing the test run's real exit code with a
            # coverage-plumbing traceback and skipping summary emission.
            # Conditions that trip this in CI: EXDEV on overlay/tmpfs mounts,
            # EROFS/ENOSPC on the reports volume, or a stale lock from a
            # crashed prior run. On failure the source `.coverage` is left in
            # place (rename is atomic) and the next successful call's rename
            # will pick it up — at the cost of this tier's combine omitting
            # earlier tiers' data, which is strictly better than dropping the
            # exit code.
            log.warning(
                "could not carry prior coverage forward (%s): %s; "
                "this tier's combine will omit earlier tiers' data",
                prior,
                exc,
            )
        else:
            files = [prior, *files]
    if not files:
        return

    base = _coverage_base()
    clean_env = _clean_env()
    if not _run_coverage(
        [*base, "combine", *[str(p) for p in files]],
        cwd=reports_dir,
        env=clean_env,
    ):
        return

    combined = reports_dir / ".coverage"
    xml_cmd = [
        *base,
        "xml",
        "--data-file",
        str(combined),
        "-o",
        str(reports_dir / "coverage.xml"),
    ]
    html_cmd = [
        *base,
        "html",
        "--data-file",
        str(combined),
        "-d",
        str(reports_dir / "htmlcov"),
    ]
    for cmd in (xml_cmd, html_cmd):
        _run_coverage(cmd, cwd=REPO_ROOT, env=clean_env)


def _run_coverage(cmd: list[str], *, cwd: Path, env: dict[str, str]) -> bool:
    """Run a coverage subprocess with a timeout. Returns True on success.

    A timeout is essential: ``uv run --with coverage[toml]`` can resolve over a
    slow index, and this runs AFTER the per-group loop so the rig's per-group
    timeouts don't apply — without a cap it could hang the job to the CI limit.
    Failures are logged, not raised (coverage is best-effort reporting).
    """
    try:
        result = subprocess.run(
            cmd,
            cwd=cwd,
            capture_output=True,
            text=True,
            env=env,
            timeout=_COVERAGE_TIMEOUT_SECONDS,
        )
    except subprocess.TimeoutExpired:
        log.warning(
            "coverage step timed out after %ds: %s",
            _COVERAGE_TIMEOUT_SECONDS,
            " ".join(cmd),
        )
        return False
    if result.returncode != 0:
        log.warning(
            "%s failed (exit %d): %s",
            " ".join(cmd),
            result.returncode,
            (result.stderr or result.stdout).strip(),
        )
        return False
    return True