airflow-pytest-plugin 0.3.2__tar.gz → 0.4.0__tar.gz

{airflow_pytest_plugin-0.3.2 → airflow_pytest_plugin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airflow-pytest-plugin
-Version: 0.3.2
+Version: 0.4.0
 Summary: View airflow-pytest-operator results in the Airflow 3 web UI.
 Project-URL: Homepage, https://github.com/IKrysanov/airflow-pytest-plugin
 Project-URL: Repository, https://github.com/IKrysanov/airflow-pytest-plugin
@@ -37,6 +37,11 @@ Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: secure-xml
 Requires-Dist: defusedxml>=0.7; extra == 'secure-xml'
+Provides-Extra: ui-test
+Requires-Dist: fastapi>=0.110; extra == 'ui-test'
+Requires-Dist: pytest-playwright>=0.5; extra == 'ui-test'
+Requires-Dist: pytest>=7.0; extra == 'ui-test'
+Requires-Dist: uvicorn>=0.23; extra == 'ui-test'
 Provides-Extra: web
 Requires-Dist: fastapi>=0.110; extra == 'web'
 Requires-Dist: uvicorn>=0.23; extra == 'web'
@@ -91,6 +96,7 @@ It has two halves that share one on-disk layout:
 - [HTTP API](#http-api)
 - [Access control (RBAC)](#access-control-rbac)
 - [Configuration](#configuration)
+- [Prometheus metrics](#prometheus-metrics)
 - [Architecture (SOLID)](#architecture-solid)
 - [Development](#development)
 - [License](#license)
@@ -124,9 +130,21 @@ run; expanding a case offers its full **history**:
 
 ![Pytest Reports — flaky tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/flaky.png)
 
+**Slow tests & duration regressions** — the *Slowdowns* KPI opens a panel of tests
+whose **execution time got slower** (recent-half average vs the older half, over a
+configurable window) alongside the **slowest tests** by average duration. A test
+that speeds back up drops off the list. Inside a run, the case table sorts by
+execution time (slowest first) so the heaviest tests surface immediately.
+
+![Pytest Reports — slow tests & regressions](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/slow.png)
+
 **Unique tests & failures** — the *Unique tests* KPI opens the searchable,
-paginated catalogue of every distinct test; the *Failures* KPI lists every
-failed/errored case across the visible runs — a row jumps to that run:
+paginated catalogue of every distinct test (each with its runs / pass-fail-error-skip
+counts / average time); the *Failures* KPI shows what's broken **now** — failures in each
+dag·task's latest run, so the count shrinks as tests are fixed — grouped into **clusters
+by normalized error** (biggest first) so common root causes surface instead of
+per-failure spam. Expand a cluster to its tests, or open the same clusters scoped to one
+run via the detail's *Error clusters* button:
 
 ![Pytest Reports — unique tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/unique.png)
 
@@ -234,15 +252,18 @@ runtime. Endpoints (relative to the mount):
 | `GET /api/reports?dag_id=&run_id=` | summaries, newest first |
 | `GET /api/reports/{report_id}` | one report with per-case rows |
 | `GET /api/groups?dag_id=&task_id=` | runs aggregated by dag·task (count, pass-rate, avg duration, last status) |
-| `GET /api/failures?dag_id=&run_id=&task_id=` | failed/errored cases across the visible runs |
+| `GET /api/failures?dag_id=&run_id=&task_id=&latest=` | failed/errored cases — each dag·task's latest run by default (`latest=0` for full history) |
+| `GET /api/failure-clusters?dag_id=&run_id=&task_id=&latest=` | failures grouped by normalized error signature (biggest first); latest-run-only by default |
 | `GET /api/compare?base=&head=` | per-test diff between two runs (newly failed / fixed / …) |
 | `GET /api/flaky?dag_id=&task_id=&window=` | flaky tests with score, trend, and a quarantine flag |
+| `GET /api/slow?dag_id=&task_id=&window=` | duration regressions (tests whose execution time got slower) + the slowest tests by average |
 | `GET /api/test-history?dag_id=&task_id=&node_id=&limit=` | one test's outcome per run |
-| `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ list when `full`) |
+| `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ when `full`, each test's runs / passed / failed / errors / skipped / avg duration) |
 | `DELETE /api/reports/{report_id}` | delete a report (RBAC-gated) |
 | `GET /api/reports/{report_id}/allure.zip` | raw Allure results as a zip (if any) |
 | `GET /api/health` | liveness + readiness: `status`, `ready`, `reports_root`(+`_exists`), `auth`, `secure_xml` |
 | `GET /api/version` | `{"name": ..., "version": ...}` from package metadata |
+| `GET /api/metrics` | Prometheus exposition — opt-in, bearer-token (see [Prometheus metrics](#prometheus-metrics)) |
 | `GET /api/docs` | OpenAPI docs (Swagger UI) |
 
 The reads (`GET`) and the delete are gated by Airflow RBAC — see below.
@@ -308,7 +329,10 @@ Download them from a report's detail view, or `GET
 | `AIRFLOW_PYTEST_FLAKY_WINDOW` (env/cfg) | `30` | default recent runs the flaky detector scans |
 | `AIRFLOW_PYTEST_FLAKY_QUARANTINE_SCORE` (env/cfg) | `0.5` | flakiness score (0–1) that flags a test for quarantine |
 | `AIRFLOW_PYTEST_FLAKY_MIN_SCORE` (env/cfg) | `0.1` | flakiness score (0–1) below which a test is not counted as flaky |
+| `AIRFLOW_PYTEST_SLOW_FACTOR` (env/cfg) | `1.3` | how much slower (recent-half avg ÷ older half, ≥1) a test must get to count as a duration regression |
+| `AIRFLOW_PYTEST_SLOW_MIN_DELTA` (env/cfg) | `0.5` | minimum absolute slowdown in seconds for a regression to register (filters jittery fast tests) |
 | `AIRFLOW_PYTEST_SUCCESS_THRESHOLD` (env/cfg) | `0.85` | pass-rate (0–1) over executed tests at/above which a run counts as successful (*Passing runs*); `1.0` = strict, zero failures/errors |
+| `AIRFLOW_PYTEST_METRICS_TOKEN` (env/cfg) | — | bearer token that **enables** the Prometheus `/api/metrics` endpoint; unset = disabled (see [below](#prometheus-metrics)) |
 
 **Enable / disable the reader.** Set `AIRFLOW_PYTEST_PLUGIN_ENABLE` to a falsey
 value (`0`, `false`, `no`, `off`) to stop the plugin registering its UI and API
@@ -328,6 +352,34 @@ single scan for `AIRFLOW_PYTEST_SCAN_CACHE_TTL` seconds (default `2.0`; deletes
 invalidate it immediately). New runs therefore appear within a couple of seconds (or
 on **Refresh**); set it to `0` for no caching, or higher on a very large tree.
 
+## Prometheus metrics
+
+`GET /api/metrics` exposes per-dag·task gauges (from each dag·task's **latest** run)
+in the Prometheus text format — `airflow_pytest_latest_{passed,failed,errors,skipped,
+tests,pass_ratio,duration_seconds,success,run_timestamp_seconds}{dag_id,task_id}` and
+`airflow_pytest_dagtask_runs{dag_id,task_id}`, plus globals
+`airflow_pytest_{up,runs,dagtasks,latest_failures,series_truncated,build_info}` (all gauges).
+
+It's **disabled by default** and turns on only when you set a scrape token; requests must
+then present it as a bearer token (constant-time compared). The scrape is cheap and
+bounded — one cached directory scan, summary-derived (no per-run reads), capped at 2000
+series — so it's safe to poll frequently.
+
+```bash
+export AIRFLOW_PYTEST_METRICS_TOKEN="$(openssl rand -hex 16)"
+```
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: airflow-pytest
+    metrics_path: /pytest-reports/api/metrics   # the plugin's mount prefix
+    authorization:
+      credentials: "<AIRFLOW_PYTEST_METRICS_TOKEN>"
+    static_configs:
+      - targets: ["airflow-apiserver:8080"]
+```
+
 ## Retention (auto-cleanup)
 
 Reports accumulate forever unless you prune them. Set any of the

{airflow_pytest_plugin-0.3.2 → airflow_pytest_plugin-0.4.0}/README.md

@@ -47,6 +47,7 @@ It has two halves that share one on-disk layout:
 - [HTTP API](#http-api)
 - [Access control (RBAC)](#access-control-rbac)
 - [Configuration](#configuration)
+- [Prometheus metrics](#prometheus-metrics)
 - [Architecture (SOLID)](#architecture-solid)
 - [Development](#development)
 - [License](#license)
@@ -80,9 +81,21 @@ run; expanding a case offers its full **history**:
 
 ![Pytest Reports — flaky tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/flaky.png)
 
+**Slow tests & duration regressions** — the *Slowdowns* KPI opens a panel of tests
+whose **execution time got slower** (recent-half average vs the older half, over a
+configurable window) alongside the **slowest tests** by average duration. A test
+that speeds back up drops off the list. Inside a run, the case table sorts by
+execution time (slowest first) so the heaviest tests surface immediately.
+
+![Pytest Reports — slow tests & regressions](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/slow.png)
+
 **Unique tests & failures** — the *Unique tests* KPI opens the searchable,
-paginated catalogue of every distinct test; the *Failures* KPI lists every
-failed/errored case across the visible runs — a row jumps to that run:
+paginated catalogue of every distinct test (each with its runs / pass-fail-error-skip
+counts / average time); the *Failures* KPI shows what's broken **now** — failures in each
+dag·task's latest run, so the count shrinks as tests are fixed — grouped into **clusters
+by normalized error** (biggest first) so common root causes surface instead of
+per-failure spam. Expand a cluster to its tests, or open the same clusters scoped to one
+run via the detail's *Error clusters* button:
 
 ![Pytest Reports — unique tests](https://raw.githubusercontent.com/IKrysanov/airflow-pytest-plugin/main/docs/screenshots/unique.png)
 
@@ -190,15 +203,18 @@ runtime. Endpoints (relative to the mount):
 | `GET /api/reports?dag_id=&run_id=` | summaries, newest first |
 | `GET /api/reports/{report_id}` | one report with per-case rows |
 | `GET /api/groups?dag_id=&task_id=` | runs aggregated by dag·task (count, pass-rate, avg duration, last status) |
-| `GET /api/failures?dag_id=&run_id=&task_id=` | failed/errored cases across the visible runs |
+| `GET /api/failures?dag_id=&run_id=&task_id=&latest=` | failed/errored cases — each dag·task's latest run by default (`latest=0` for full history) |
+| `GET /api/failure-clusters?dag_id=&run_id=&task_id=&latest=` | failures grouped by normalized error signature (biggest first); latest-run-only by default |
 | `GET /api/compare?base=&head=` | per-test diff between two runs (newly failed / fixed / …) |
 | `GET /api/flaky?dag_id=&task_id=&window=` | flaky tests with score, trend, and a quarantine flag |
+| `GET /api/slow?dag_id=&task_id=&window=` | duration regressions (tests whose execution time got slower) + the slowest tests by average |
 | `GET /api/test-history?dag_id=&task_id=&node_id=&limit=` | one test's outcome per run |
-| `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ list when `full`) |
+| `GET /api/unique-tests?dag_id=&task_id=&run_id=&full=` | distinct test count (+ when `full`, each test's runs / passed / failed / errors / skipped / avg duration) |
 | `DELETE /api/reports/{report_id}` | delete a report (RBAC-gated) |
 | `GET /api/reports/{report_id}/allure.zip` | raw Allure results as a zip (if any) |
 | `GET /api/health` | liveness + readiness: `status`, `ready`, `reports_root`(+`_exists`), `auth`, `secure_xml` |
 | `GET /api/version` | `{"name": ..., "version": ...}` from package metadata |
+| `GET /api/metrics` | Prometheus exposition — opt-in, bearer-token (see [Prometheus metrics](#prometheus-metrics)) |
 | `GET /api/docs` | OpenAPI docs (Swagger UI) |
 
 The reads (`GET`) and the delete are gated by Airflow RBAC — see below.
@@ -264,7 +280,10 @@ Download them from a report's detail view, or `GET
 | `AIRFLOW_PYTEST_FLAKY_WINDOW` (env/cfg) | `30` | default recent runs the flaky detector scans |
 | `AIRFLOW_PYTEST_FLAKY_QUARANTINE_SCORE` (env/cfg) | `0.5` | flakiness score (0–1) that flags a test for quarantine |
 | `AIRFLOW_PYTEST_FLAKY_MIN_SCORE` (env/cfg) | `0.1` | flakiness score (0–1) below which a test is not counted as flaky |
+| `AIRFLOW_PYTEST_SLOW_FACTOR` (env/cfg) | `1.3` | how much slower (recent-half avg ÷ older half, ≥1) a test must get to count as a duration regression |
+| `AIRFLOW_PYTEST_SLOW_MIN_DELTA` (env/cfg) | `0.5` | minimum absolute slowdown in seconds for a regression to register (filters jittery fast tests) |
 | `AIRFLOW_PYTEST_SUCCESS_THRESHOLD` (env/cfg) | `0.85` | pass-rate (0–1) over executed tests at/above which a run counts as successful (*Passing runs*); `1.0` = strict, zero failures/errors |
+| `AIRFLOW_PYTEST_METRICS_TOKEN` (env/cfg) | — | bearer token that **enables** the Prometheus `/api/metrics` endpoint; unset = disabled (see [below](#prometheus-metrics)) |
 
 **Enable / disable the reader.** Set `AIRFLOW_PYTEST_PLUGIN_ENABLE` to a falsey
 value (`0`, `false`, `no`, `off`) to stop the plugin registering its UI and API
@@ -284,6 +303,34 @@ single scan for `AIRFLOW_PYTEST_SCAN_CACHE_TTL` seconds (default `2.0`; deletes
 invalidate it immediately). New runs therefore appear within a couple of seconds (or
 on **Refresh**); set it to `0` for no caching, or higher on a very large tree.
 
+## Prometheus metrics
+
+`GET /api/metrics` exposes per-dag·task gauges (from each dag·task's **latest** run)
+in the Prometheus text format — `airflow_pytest_latest_{passed,failed,errors,skipped,
+tests,pass_ratio,duration_seconds,success,run_timestamp_seconds}{dag_id,task_id}` and
+`airflow_pytest_dagtask_runs{dag_id,task_id}`, plus globals
+`airflow_pytest_{up,runs,dagtasks,latest_failures,series_truncated,build_info}` (all gauges).
+
+It's **disabled by default** and turns on only when you set a scrape token; requests must
+then present it as a bearer token (constant-time compared). The scrape is cheap and
+bounded — one cached directory scan, summary-derived (no per-run reads), capped at 2000
+series — so it's safe to poll frequently.
+
+```bash
+export AIRFLOW_PYTEST_METRICS_TOKEN="$(openssl rand -hex 16)"
+```
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: airflow-pytest
+    metrics_path: /pytest-reports/api/metrics   # the plugin's mount prefix
+    authorization:
+      credentials: "<AIRFLOW_PYTEST_METRICS_TOKEN>"
+    static_configs:
+      - targets: ["airflow-apiserver:8080"]
+```
+
 ## Retention (auto-cleanup)
 
 Reports accumulate forever unless you prune them. Set any of the

{airflow_pytest_plugin-0.3.2 → airflow_pytest_plugin-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "airflow-pytest-plugin"
-version = "0.3.2"
+version = "0.4.0"
 description = "View airflow-pytest-operator results in the Airflow 3 web UI."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,6 +60,14 @@ dev = [
     "mypy>=1.8",
     "ruff>=0.4",
 ]
+# Playwright UI regression suite (tests/ui, marker `ui`). Opt-in: heavy (real browser),
+# run locally + in a dedicated CI job. After install: `playwright install chromium`.
+ui-test = [
+    "pytest>=7.0",
+    "pytest-playwright>=0.5",
+    "fastapi>=0.110",
+    "uvicorn>=0.23",        # the standalone dev server the UI tests drive
+]
 
 [project.urls]
 Homepage = "https://github.com/IKrysanov/airflow-pytest-plugin"
@@ -83,6 +91,15 @@ include = ["src", "tests", "examples", "README.md", "LICENSE"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
+# UI (Playwright) tests are opt-in and excluded by default so the unit suite stays fast
+# and browser-free. Run them explicitly: `pytest -m ui` (standalone dev server) or
+# `pytest -m ui_airflow` (embedded in a real Airflow api-server). Both need the
+# `ui-test` extra + browsers; `ui_airflow` also needs Airflow installed.
+addopts = ["-m", "not ui and not ui_airflow"]
+markers = [
+    "ui: Playwright UI regression test (opt-in; needs the 'ui-test' extra + browsers)",
+    "ui_airflow: Playwright UI test against a real Airflow api-server with the plugin embedded",
+]
 
 [tool.coverage.run]
 branch = true

{airflow_pytest_plugin-0.3.2 → airflow_pytest_plugin-0.4.0}/src/airflow_pytest_plugin/config.py

@@ -16,6 +16,7 @@
 
 from __future__ import annotations
 
+import math
 import os
 
 from .compat import get_conf_value
@@ -149,6 +150,49 @@ def get_flaky_min_score() -> float:
     )
 
 
+#: Duration-regression detector. A test is flagged "slower" when its recent-half
+#: average duration is at least ``SLOW_FACTOR``× its older-half average AND the
+#: absolute increase clears ``SLOW_MIN_DELTA`` seconds (the delta filters noise on
+#: fast tests, where a tiny jitter can still beat the ratio). Shares the flaky window.
+SLOW_FACTOR_ENV = "AIRFLOW_PYTEST_SLOW_FACTOR"
+DEFAULT_SLOW_FACTOR = 1.3
+SLOW_MIN_DELTA_ENV = "AIRFLOW_PYTEST_SLOW_MIN_DELTA"
+DEFAULT_SLOW_MIN_DELTA = 0.5
+
+
+def _positive_float_setting(
+    env_var: str, conf_key: str, default: float, *, minimum: float
+) -> float:
+    """A float ≥ ``minimum`` from env, then cfg; default on missing/invalid/below."""
+    raw = os.environ.get(env_var)
+    if raw is None or not raw.strip():
+        raw = get_conf_value(CONF_SECTION, conf_key)
+    if raw is None or not str(raw).strip():
+        return default
+    try:
+        value = float(str(raw).strip())
+    except ValueError:
+        return default
+    # Reject NaN/inf: they'd serialize to non-spec JSON ("NaN"/"Infinity") downstream.
+    if not math.isfinite(value):
+        return default
+    return value if value >= minimum else default
+
+
+def get_slow_factor() -> float:
+    """Multiplier a test's recent-half avg duration must reach to count as a regression."""
+    return _positive_float_setting(
+        SLOW_FACTOR_ENV, "slow_factor", DEFAULT_SLOW_FACTOR, minimum=1.0
+    )
+
+
+def get_slow_min_delta() -> float:
+    """Minimum absolute slowdown (seconds) for a duration regression to register."""
+    return _positive_float_setting(
+        SLOW_MIN_DELTA_ENV, "slow_min_delta", DEFAULT_SLOW_MIN_DELTA, minimum=0.0
+    )
+
+
 #: Pass-rate (0–1) at/above which a run counts as successful ("Passing runs"). The
 #: rate is over executed tests, so a run can carry a few failures and still pass.
 #: At 1.0 a run is successful only with zero failures/errors (the strict default of
@@ -164,6 +208,20 @@ def get_success_threshold() -> float:
     )
 
 
+#: Opt-in bearer token for the Prometheus ``/api/metrics`` endpoint. Secure-by-default:
+#: unset = the endpoint is DISABLED (404). When set, a scrape must send
+#: ``Authorization: Bearer <token>``. Reads the env var, then the cfg key.
+METRICS_TOKEN_ENV = "AIRFLOW_PYTEST_METRICS_TOKEN"
+
+
+def get_metrics_token() -> str | None:
+    """The metrics scrape token, or ``None`` when the endpoint should stay disabled."""
+    raw = os.environ.get(METRICS_TOKEN_ENV)
+    if raw is None or not raw.strip():
+        raw = get_conf_value(CONF_SECTION, "metrics_token")
+    return raw.strip() if raw and raw.strip() else None
+
+
 def get_reports_root() -> str:
     """Resolve the report root directory (absolute path)."""
     env = os.environ.get(ENV_VAR)

{airflow_pytest_plugin-0.3.2 → airflow_pytest_plugin-0.4.0}/src/airflow_pytest_plugin/sources/filesystem.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import io
 import json
 import logging
+import math
 import os
 import shutil
 import threading
@@ -101,7 +102,17 @@ class FileSystemReportSource(ReportSource):
             if summary is not None:
                 out.append(summary)
         # Newest first: ISO-8601 created_at sorts chronologically; missing sorts last.
-        out.sort(key=lambda s: s.created_at or "", reverse=True)
+        # Tiebreak deterministically (try_number, run_id, map_index) so that on equal or
+        # missing created_at a stable "latest" run is chosen (e.g. a retry wins its try).
+        out.sort(
+            key=lambda s: (
+                s.created_at or "",
+                s.ref.try_number,
+                s.ref.run_id,
+                s.ref.map_index,
+            ),
+            reverse=True,
+        )
         return out
 
     def _all_summaries(self) -> list[ReportSummary]:
@@ -206,6 +217,10 @@ class FileSystemReportSource(ReportSource):
                         if len(row) > 2 and isinstance(row[2], int | float)
                         else 0.0
                     )
+                    # Guard NaN/Infinity from a corrupt meta so they can't reach a
+                    # JSON response (json.dumps would emit non-spec NaN/Infinity).
+                    if not math.isfinite(dur):
+                        dur = 0.0
                     out[str(row[0])] = {"outcome": str(row[1]), "duration": dur}
             return out
         # Older archive without the per-test map: parse junit.xml on demand.
@@ -217,12 +232,13 @@ class FileSystemReportSource(ReportSource):
         except Exception:
             _log.exception("Failed to parse JUnit report %s", report_path)
             return None
+
+        def _dur(c: Any) -> float:
+            d = float(getattr(c, "time", 0.0) or 0.0)
+            return d if math.isfinite(d) else 0.0
+
         return {
-            c.node_id: {
-                "outcome": c.outcome,
-                "duration": float(getattr(c, "time", 0.0) or 0.0),
-            }
-            for c in result.cases
+            c.node_id: {"outcome": c.outcome, "duration": _dur(c)} for c in result.cases
         }
 
     def delete(self, ref: ReportRef) -> bool:

airflow_pytest_plugin-0.4.0/src/airflow_pytest_plugin/web/routes/failures.py

@@ -0,0 +1,281 @@
+# Copyright 2026 the airflow-pytest-plugin contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Failures route — failed/errored cases across the visible runs, flat or clustered."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+
+from .common import RouteDeps, ok
+
+TAG = "failures"
+
+#: Upper bound on failed cases returned, to keep the payload bounded.
+_FAILURES_CAP = 5000
+#: Cap on failing tests listed under a single cluster (the count is still exact).
+_CLUSTER_TESTS_CAP = 200
+
+# Volatile bits scrubbed from an error message so messages that differ only by run
+# specifics collapse to one signature. Order matters: UUID before the generic digit
+# rule (a UUID is mostly digits), hex addresses before digits too.
+_RE_UUID = re.compile(r"[0-9a-fA-F]{8}-(?:[0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}")
+_RE_HEX = re.compile(r"0x[0-9a-fA-F]+")
+_RE_NUM = re.compile(r"\d+")
+_RE_WS = re.compile(r"\s+")
+
+
+def _error_line(message: str | None) -> str:
+    """First meaningful line of a case message (skips our ``--- section ---`` headers)."""
+    for line in (message or "").splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("---"):
+            return stripped
+    return (message or "").strip()
+
+
+def normalize_error(message: str | None) -> str:
+    """A stable signature for an error message: its first line with volatile bits masked.
+
+    Strips UUIDs, hex addresses and numbers (and collapses whitespace) so that
+    ``expected 5 got 7`` and ``expected 8 got 3`` share the signature
+    ``expected N got N``. Capped to keep signatures comparable and bounded.
+    """
+    line = _error_line(message)
+    line = _RE_UUID.sub("UUID", line)
+    line = _RE_HEX.sub(
+        "ADDR", line
+    )  # digit-free placeholder so the number rule won't touch it
+    line = _RE_NUM.sub("N", line)
+    return _RE_WS.sub(" ", line).strip()[:200]
+
+
+def cluster_failures(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Group failing cases by normalized message (pure), most common cluster first.
+
+    Each cluster carries the ``signature``, an exact ``count``, the ``outcomes`` seen,
+    a representative raw ``sample`` line, and the (capped) list of failing ``tests``.
+    """
+    clusters: dict[str, dict[str, Any]] = {}
+    for it in items:
+        sig = normalize_error(it.get("message"))
+        c = clusters.get(sig)
+        if c is None:
+            c = clusters[sig] = {
+                "signature": sig,
+                "count": 0,
+                "sample": _error_line(it.get("message")),
+                "outcomes": set(),
+                "tests": [],
+            }
+        c["count"] += 1
+        c["outcomes"].add(it["outcome"])
+        if len(c["tests"]) < _CLUSTER_TESTS_CAP:
+            c["tests"].append(
+                {
+                    k: it[k]
+                    for k in (
+                        "id",
+                        "dag_id",
+                        "task_id",
+                        "run_id",
+                        "created_at",
+                        "node_id",
+                        "outcome",
+                    )
+                }
+            )
+    out = [{**c, "outcomes": sorted(c["outcomes"])} for c in clusters.values()]
+    out.sort(key=lambda c: (-c["count"], c["signature"]))
+    return out
+
+
+def _collect_failures(
+    deps: RouteDeps,
+    user: Any,
+    *,
+    dag_id: str | None,
+    run_id: str | None,
+    task_q: str,
+    latest: bool,
+    with_message: bool,
+) -> tuple[list[dict[str, Any]], bool]:
+    """Collect failed/errored cases across readable runs (newest first).
+
+    When ``latest`` (the default for the views), only each **dag·task's** newest readable
+    run is considered — that's the pipeline's current state across all of its run_ids, so
+    a fixed test drops off once its next run is green and the list reflects *current*
+    breakage rather than every failure ever archived (older run_ids are history). Runs are
+    deduped per (dag_id, task_id); a retry wins its run via the scan's created_at/
+    try_number ordering. ``latest=False`` walks the full history. Returns ``(items, capped)``.
+    """
+    src, read_auth = deps.src, deps.read_auth
+    items: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    capped = False
+    for s in src.list_summaries(dag_id=dag_id, run_id=run_id):  # newest first
+        if task_q and task_q not in s.ref.task_id.lower():
+            continue
+        if not read_auth(s.ref.dag_id, user):
+            continue
+        key = (s.ref.dag_id, s.ref.task_id)
+        if latest:
+            if key in seen:  # an older run of a group whose newest we already passed
+                continue
+            seen.add(
+                key
+            )  # mark before the green check, so a green newest hides old fails
+        if (s.failed + s.errors) <= 0:
+            continue
+        detail = src.get_detail(s.ref)
+        if detail is None:
+            continue
+        for c in detail.cases:
+            if c.outcome not in ("failed", "error"):
+                continue
+            item = {
+                "id": s.ref.token,
+                "dag_id": s.ref.dag_id,
+                "task_id": s.ref.task_id,
+                "run_id": s.ref.run_id,
+                "created_at": s.created_at,
+                "node_id": c.node_id,
+                "outcome": c.outcome,
+            }
+            if with_message:
+                item["message"] = c.message
+            items.append(item)
+            if len(items) >= _FAILURES_CAP:  # stop mid-run, don't over-read one big run
+                capped = True
+                break
+        if capped:
+            break
+    return items[:_FAILURES_CAP], capped
+
+
+def build_router(deps: RouteDeps) -> APIRouter:
+    """Routes tagged ``failures``."""
+    router = APIRouter(tags=[TAG])
+    user_dep = deps.user_dep
+
+    @router.get(
+        "/api/failures",
+        summary="Failed cases across runs",
+        responses=ok(
+            {
+                "failures": [
+                    {
+                        "id": "YXBpX2dhdGV3YXl8...",
+                        "dag_id": "api_gateway",
+                        "task_id": "integration_tests",
+                        "run_id": "scheduled__2026-06-20",
+                        "created_at": "2026-06-20T07:00:00+00:00",
+                        "node_id": "tests/api.py::test_auth",
+                        "outcome": "failed",
+                    }
+                ],
+                "total": 1,
+                "capped": False,
+            }
+        ),
+    )
+    def failures(
+        dag_id: str | None = None,
+        run_id: str | None = None,
+        task_id: str | None = None,
+        latest: bool = True,
+        user: Any = Depends(user_dep),  # noqa: B008 - FastAPI dependency idiom
+    ) -> JSONResponse:
+        """Currently-failing cases (one flat list), newest run first.
+
+        By default only each dag·task's **latest** readable run is considered, so a
+        fixed test drops off once its next run is green — the list reflects what's broken
+        *now* and shrinks as code improves. Pass ``latest=0`` for the full history.
+        Filters mirror the run list (``dag_id`` / ``run_id`` / ``task_id``); RBAC; capped
+        at ``5000`` (``capped`` flags truncation).
+        """
+        items, capped = _collect_failures(
+            deps,
+            user,
+            dag_id=dag_id,
+            run_id=run_id,
+            task_q=(task_id or "").lower(),
+            latest=latest,
+            with_message=False,
+        )
+        return JSONResponse({"failures": items, "total": len(items), "capped": capped})
+
+    @router.get(
+        "/api/failure-clusters",
+        summary="Failures grouped by error",
+        responses=ok(
+            {
+                "clusters": [
+                    {
+                        "signature": "AssertionError: expected N got N",
+                        "count": 12,
+                        "sample": "AssertionError: expected 5 got 7",
+                        "outcomes": ["failed"],
+                        "tests": [
+                            {
+                                "id": "YXBpX2dhdGV3YXl8...",
+                                "dag_id": "api_gateway",
+                                "task_id": "integration_tests",
+                                "run_id": "scheduled__2026-06-20",
+                                "created_at": "2026-06-20T07:00:00+00:00",
+                                "node_id": "tests/api.py::test_auth",
+                                "outcome": "failed",
+                            }
+                        ],
+                    }
+                ],
+                "total": 12,
+                "capped": False,
+            }
+        ),
+    )
+    def failure_clusters(
+        dag_id: str | None = None,
+        run_id: str | None = None,
+        task_id: str | None = None,
+        latest: bool = True,
+        user: Any = Depends(user_dep),  # noqa: B008 - FastAPI dependency idiom
+    ) -> JSONResponse:
+        """Currently-failing cases grouped by a normalized error signature, biggest first.
+
+        Same scan/filters/RBAC/cap as ``/api/failures``, and likewise defaults to each
+        dag·task's **latest** run (``latest=0`` for full history) — so clusters reflect
+        what's broken now and shrink as tests are fixed. Instead of a flat list it
+        returns clusters, so common root causes surface instead of per-failure spam; each
+        has an exact ``count``, a representative ``sample`` message, and the (capped)
+        failing ``tests``. Scope to one ``run_id`` for the in-run view.
+        """
+        items, capped = _collect_failures(
+            deps,
+            user,
+            dag_id=dag_id,
+            run_id=run_id,
+            task_q=(task_id or "").lower(),
+            latest=latest,
+            with_message=True,
+        )
+        return JSONResponse(
+            {"clusters": cluster_failures(items), "total": len(items), "capped": capped}
+        )
+
+    return router