ocr-service/test_metrics.py

@@ -61,7 +61,15 @@ def fresh_metrics(monkeypatch):
 
 @pytest.mark.asyncio
 async def test_metrics_endpoint_returns_200():
-    """`GET /metrics` returns 200 with Prometheus exposition content."""
+    """`GET /metrics` returns 200 with Prometheus exposition content.
+
+    Uses the global REGISTRY by design — does NOT take the `fresh_metrics` fixture.
+    The `/metrics` endpoint is wired by `prometheus-fastapi-instrumentator`, which
+    binds to the default REGISTRY at app-construction time; swapping `main.metrics`
+    via the fixture would not redirect what `/metrics` exposes. This test only
+    asserts response shape (status code + content-type substring), not numeric
+    counter values, so cross-test state leakage cannot affect it.
+    """
     with patch("main.kraken_engine.load_models"), \
          patch("main.load_spell_checker"):
         async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
@@ -73,7 +81,15 @@ async def test_metrics_endpoint_returns_200():
 
 @pytest.mark.asyncio
 async def test_metrics_includes_http_request_metrics_after_ocr_call():
-    """After a request to /ocr, `/metrics` exposes auto-instrumented http_* metrics."""
+    """After a request to /ocr, `/metrics` exposes auto-instrumented http_* metrics.
+
+    Uses the global REGISTRY by design — does NOT take the `fresh_metrics` fixture.
+    The `http_requests_total` / `http_request_duration_seconds` metrics live on
+    the instrumentator's default REGISTRY (not on `main.metrics`), so a fresh
+    CollectorRegistry would never see them. This test only asserts response shape
+    (substring presence in the exposition body), not numeric counter values, so
+    cross-test state leakage cannot affect it.
+    """
     mock_images = [Image.new("RGB", (100, 100))]
     mock_blocks = [{"pageNumber": 1, "x": 0.0, "y": 0.0, "width": 1.0, "height": 1.0,
                     "polygon": None, "text": "hi", "words": []}]