Move orchestration out of the route handlers into a service layer

The backend policy - which backend to try, in what order, when to fall
back, what counts as evidence a backend is unhealthy, when a patent is
absent rather than merely unreachable - was written inline in FastAPI route
handlers. It is not HTTP-specific: it would be equally true behind a CLI or
a queue consumer, and putting it there meant exercising any of it cost an
ASGI round-trip plus monkeypatching module globals.

It now lives in services.py as SearchService and PatentService, which take
their stateful collaborators (HTTP client, browser provider, circuit
breaker, OPS credentials) as constructor arguments. app.py keeps the
module-level instances and wires them in through `Depends`, so
`app.dependency_overrides` replaces them in a test.

The services raise domain errors - PatentNotFound, UpstreamUnavailable,
OPSUnconfigured - rather than HTTPException. Mapping those onto status
codes is the HTTP layer's job and is now three exception handlers instead
of the same branching repeated across two endpoints. app.py no longer
imports HTTPException at all.

What this buys, concretely:

- The autouse fixture that reset a process-wide circuit breaker between
tests is gone; each test builds a service with its own breaker.
- The pokes at ops token_manager._key / ._secret from two different test
files are gone; tests pass a small stand-in with a `configured` flag.
- 40 tests that needed an ASGI client are now plain unit tests. The
SearchService suite runs 22 tests in 0.21s.
- test_app.py is now about what app.py does: endpoint-to-service dispatch,
validation, dependency wiring, and the lifespan.

Also closes the coverage the refactor would otherwise have lost.
Splitting the scrapers left the four-line composition in each `query_*`
untested, so tests/test_serp_navigation.py covers it with a recording
stand-in browser - asserting each scraper navigates to the URL its own
builder produced. That is precisely the link the deleted goto-patching
harness could never test, since it accepted the URL and discarded it.

The full mutation battery from the review now stands at 18 of 18 killed,
against 6 of 13 when the review was written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MSNSYnceqvdVz7Csis4K9e

CONTRIBUTING.md

@@ -30,7 +30,7 @@ ruff check .   # same lint CI runs
 pytest
 ```
 
-199 tests, a few seconds, fully offline. All outbound HTTP is mocked with
+238 tests, a few seconds, fully offline. All outbound HTTP is mocked with
 `respx`; the Playwright-driven scrapers (Bing, Brave, Google Scholar,
 Google Patents search) run against a real headless Chromium but navigate to
 local fixture HTML instead of the live sites — see `tests/helpers.py` for
@@ -55,6 +55,34 @@ bug here — fix it the same way as anything else (see below): update the
 fixture HTML to match the new real markup, confirm the test fails against
 the current selectors, fix the selectors, confirm green.
 
+## How the code is laid out
+
+- **`app.py`** is HTTP wiring only: request validation, dependency
+  providers, the lifespan, and mapping domain errors onto status codes.
+- **`services.py`** holds the orchestration policy - which backend to try,
+  in what order, when to fall back, what counts as evidence a backend is
+  unhealthy, and when a patent is genuinely absent rather than merely
+  unreachable. None of that is HTTP-specific, and keeping it out of route
+  handlers is why most of its tests need no ASGI client.
+- **`serp.py` / `scrap.py` / `ops.py`** are the backends. Each scraper is
+  split into a pure URL builder, a navigation step, and an `_extract_*`
+  function taking an already-loaded page, so all three can be tested
+  separately.
+- **`utils.py` / `circuit_breaker.py`** are dependency-free helpers.
+
+The services take their stateful collaborators (HTTP client, browser,
+circuit breaker, OPS credentials) as constructor arguments. That is
+deliberate and worth preserving: it is what lets a test build a service
+with its own circuit breaker instead of resetting a process-wide singleton
+between tests, and hand in a stand-in for the OPS credentials instead of
+assigning to private attributes on the real token manager. `app.py`'s
+`get_search_service` / `get_patent_service` providers exist so
+`app.dependency_overrides` can replace them wholesale in a test.
+
+The stateless backend functions stay module-level imports in
+`services.py`; monkeypatching one of those in a test is fine, because they
+hold no state to leak between tests.
+
 ## The development loop (TDD, not test-after)
 
 Every change in this codebase's history followed the same loop, and new

app.py

@@ -1,24 +1,24 @@
-import asyncio
 import logging
 import os
 import secrets
 from contextlib import asynccontextmanager
 from typing import Annotated, Optional
-from fastapi import FastAPI, HTTPException, Request
+
+import httpx
+import uvicorn
+from fastapi import Depends, FastAPI, Request
 from fastapi.responses import JSONResponse
 from fastapi.routing import APIRouter
-import httpx
-from httpx import HTTPStatusError
+from playwright.async_api import Browser, async_playwright
 from pydantic import BaseModel, Field, StringConstraints
-from playwright.async_api import async_playwright, Browser
-import uvicorn
 
-from circuit_breaker import CircuitBreaker, CircuitOpenError
-from scrap import PatentScrapBulkResponse, PatentScrapResult, scrap_patent_async, scrap_patent_bulk_async
-from serp import EmptyResultsError, PATENT_ID_CORE, SerpQuery, SerpResults, query_arxiv, query_bing_search, query_brave_search, query_ddg_search, query_google_patents, query_google_scholar
-from ops import OPSBulkResponse, OPSNotConfigured, ops_scrap_patent, ops_scrap_patent_bulk, ops_search, token_manager as ops_token_manager
-from utils import log_gathered_exceptions
+from circuit_breaker import CircuitBreaker
 from mcp_server import mount_mcp_server
+from ops import OPSBulkResponse, token_manager as ops_token_manager
+from scrap import PatentScrapBulkResponse, PatentScrapResult
+from serp import PATENT_ID_CORE, SerpQuery, SerpResults
+from services import (OPSUnconfigured, PatentNotFound, PatentService,
+                      SearchService, UpstreamUnavailable)
 
 # Anchored version of serp.py's PATENT_ID_CORE: validates a whole
 # user-supplied patent id rather than finding one inside free text. Rejects
@@ -26,6 +26,11 @@ from mcp_server import mount_mcp_server
 # instead of it reaching Google Patents/OPS as a confusing request.
 PatentId = Annotated[str, StringConstraints(pattern=rf"^{PATENT_ID_CORE}$")]
 
+# Same reasoning as MAX_QUERIES_PER_REQUEST in serp.py: one accepted
+# request must not be able to queue unbounded outbound work. The OPS
+# variant is the expensive one - three requests per id.
+MAX_BULK_PATENT_IDS = 50
+
 logging.basicConfig(
     level=logging.INFO,
     format='[%(asctime)s][%(levelname)s][%(filename)s:%(lineno)d]: %(message)s',
@@ -36,12 +41,19 @@ logging.basicConfig(
 playwright = None
 pw_browser: Optional[Browser] = None
 
-# httpx client. Constructed at import so module-level handlers can close
-# over it, but its lifetime is owned by `api_lifespan`, which closes it on
-# shutdown alongside the browser.
+# httpx client. Constructed at import so the dependency providers below can
+# close over it, but its lifetime is owned by `api_lifespan`, which closes
+# it on shutdown alongside the browser.
 httpx_client = httpx.AsyncClient(timeout=30, limits=httpx.Limits(
     max_connections=30, max_keepalive_connections=20))
 
+# Shared across all queries and requests: once a backend has failed
+# `failure_threshold` times in a row, skip it for `cooldown_seconds` instead
+# of attempting (and paying the timeout cost of) another call that's very
+# likely to fail - and, more importantly, stop hammering a backend that may
+# already be rate-limiting or blocking this deployment's IP.
+_backend_circuit_breaker = CircuitBreaker(failure_threshold=3, cooldown_seconds=60.0)
+
 # ===================== Optional API key protection =====================
 # Unset by default, which keeps the API exactly as open as before. Set
 # SERPENT_API_KEY on the deployment to require every request (REST and MCP
@@ -97,6 +109,32 @@ app = FastAPI(lifespan=api_lifespan, docs_url="/",
               title="SERPent", description=_load_docs())
 
 
+# ============================ service dependencies ============================
+# The orchestration itself lives in services.py; these just wire the app's
+# collaborators into it. Overriding one of these via
+# `app.dependency_overrides` is how a test supplies its own circuit breaker
+# or OPS credentials, rather than reassigning module globals.
+
+
+def get_search_service() -> SearchService:
+    return SearchService(
+        http_client=httpx_client,
+        # A provider, not the browser itself: the lifespan starts it after
+        # import, and leaves it None when Playwright fails to start.
+        browser_provider=lambda: pw_browser,
+        circuit_breaker=_backend_circuit_breaker,
+        ops_tokens=ops_token_manager,
+    )
+
+
+def get_patent_service() -> PatentService:
+    return PatentService(http_client=httpx_client, ops_tokens=ops_token_manager)
+
+
+SearchServiceDep = Annotated[SearchService, Depends(get_search_service)]
+PatentServiceDep = Annotated[PatentService, Depends(get_patent_service)]
+
+
 @app.middleware("http")
 async def api_key_guard(request: Request, call_next):
     """No-op unless SERPENT_API_KEY is set; then gates every path but the docs."""
@@ -114,261 +152,101 @@ async def api_key_guard(request: Request, call_next):
             )
     return await call_next(request)
 
-# Router for scrapping related endpoints
-scrap_router = APIRouter(prefix="/scrap", tags=["scrapping"])
-# Router for SERP-scrapping related endpoints
-serp_router = APIRouter(prefix="/serp", tags=["serp scrapping"])
-# Router for EPO OPS (official patent API) endpoints
-ops_router = APIRouter(prefix="/ops", tags=["EPO OPS"])
 
-# ===================== Search endpoints =====================
+# ========================= domain errors -> status codes =========================
+# 404 is a claim that the patent does not exist, and MCP_INSTRUCTIONS tells
+# agents to believe it and move on without retrying - so the services raise
+# PatentNotFound only when a backend positively said so, and everything else
+# arrives here as UpstreamUnavailable.
 
 
-def _shape_serp_results(results: list) -> SerpResults:
-    """Flatten a list of per-query result-lists (or Exceptions, from a
-    `return_exceptions=True` gather) into one SerpResults, surfacing the
-    last error only when every query failed.
-    """
-    if not results:
-        # SerpQuery bounds the query list, so this is unreachable from the
-        # endpoints; keep the helper total anyway rather than indexing into
-        # an empty list, since every search endpoint shares it.
-        return SerpResults(results=[], error="No queries were provided.")
+@app.exception_handler(PatentNotFound)
+async def _patent_not_found_handler(request: Request, exc: PatentNotFound):
+    return JSONResponse({"detail": str(exc)}, status_code=404)
 
-    filtered_results = [r for r in results if not isinstance(r, Exception)]
-    flattened_results = [
-        item for sublist in filtered_results for item in sublist]
 
-    if len(filtered_results) == 0:
-        return SerpResults(results=[], error=str(results[-1]))
+@app.exception_handler(UpstreamUnavailable)
+async def _upstream_unavailable_handler(request: Request, exc: UpstreamUnavailable):
+    return JSONResponse({"detail": str(exc)}, status_code=504 if exc.timeout else 502)
 
-    return SerpResults(results=flattened_results, error=None)
 
+@app.exception_handler(OPSUnconfigured)
+async def _ops_unconfigured_handler(request: Request, exc: OPSUnconfigured):
+    return JSONResponse({"detail": str(exc)}, status_code=503)
 
-async def _run_serp_queries(fn, params: SerpQuery, context: str) -> SerpResults:
-    """Run `fn(query, n_results)` concurrently for every query in `params`,
-    log any failures, and shape the result the way every simple /serp and
-    /ops search endpoint below expects.
-    """
-    results = await asyncio.gather(
-        *[fn(q, params.n_results) for q in params.queries], return_exceptions=True)
-    log_gathered_exceptions(results, context, params.queries)
-    return _shape_serp_results(results)
+
+# Router for scrapping related endpoints
+scrap_router = APIRouter(prefix="/scrap", tags=["scrapping"])
+# Router for SERP-scrapping related endpoints
+serp_router = APIRouter(prefix="/serp", tags=["serp scrapping"])
+# Router for EPO OPS (official patent API) endpoints
+ops_router = APIRouter(prefix="/ops", tags=["EPO OPS"])
+
+# ===================== Search endpoints =====================
 
 
 @serp_router.post("/search_scholar")
-async def search_google_scholar(params: SerpQuery) -> SerpResults:
+async def search_google_scholar(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Queries google scholar for the specified query"""
     logging.info(f"Searching Google Scholar for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: query_google_scholar(pw_browser, q, n), params, "google scholar search")
+    return await service.google_scholar(params)
 
 
 @serp_router.post("/search_arxiv")
-async def search_arxiv(params: SerpQuery) -> SerpResults:
+async def search_arxiv(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Searches arxiv for the specified queries and returns the found documents."""
     logging.info(f"Searching Arxiv for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: query_arxiv(httpx_client, q, n), params, "arxiv search")
+    return await service.arxiv(params)
 
 
 @serp_router.post("/search_patents")
-async def search_patents(params: SerpQuery) -> SerpResults:
+async def search_patents(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Searches google patents for the specified queries and returns the found documents.
 
     Falls back to the EPO OPS API for any query Google Patents returns nothing
     for, when OPS credentials are configured.
     """
     logging.info(f"Searching Google Patents for queries: {params.queries}")
-    results = await asyncio.gather(*[query_google_patents(pw_browser, q, params.n_results) for q in params.queries], return_exceptions=True)
-    log_gathered_exceptions(results, "google patent search", params.queries)
-
-    # Fall back to OPS for queries that errored or returned no results.
-    # Gathered rather than awaited one at a time: this path exists for when
-    # Google Patents is unavailable, so it is exactly when a request is
-    # least able to afford N sequential round-trips to the slower backend.
-    if ops_token_manager.configured:
-        needs_fallback = [
-            i for i, res in enumerate(results)
-            if isinstance(res, Exception) or not res]
-        if needs_fallback:
-            logging.info(
-                f"Google Patents empty for {len(needs_fallback)} quer(y/ies), trying OPS.")
-            fallback_results = await asyncio.gather(
-                *[ops_search(httpx_client, params.queries[i], params.n_results)
-                  for i in needs_fallback],
-                return_exceptions=True)
-            # strict: gather returns exactly one result per index, so a
-            # length mismatch here would be a bug worth surfacing.
-            for i, res in zip(needs_fallback, fallback_results, strict=True):
-                if isinstance(res, Exception):
-                    logging.warning(f"OPS fallback failed for `{params.queries[i]}`: {res}")
-                else:
-                    results[i] = res
-
-    return _shape_serp_results(results)
+    return await service.patents(params)
 
 
 @serp_router.post("/search_brave")
-async def search_brave(params: SerpQuery) -> SerpResults:
+async def search_brave(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Searches brave search for the specified queries and returns the found documents."""
     logging.info(f"Searching Brave Search for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: query_brave_search(pw_browser, q, n), params, "brave search")
+    return await service.brave(params)
 
 
 @serp_router.post("/search_bing")
-async def search_bing(params: SerpQuery) -> SerpResults:
+async def search_bing(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Searches Bing search for the specified queries and returns the found documents."""
     logging.info(f"Searching Bing Search for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: query_bing_search(pw_browser, q, n), params, "bing search")
+    return await service.bing(params)
 
 
 @serp_router.post("/search_duck")
-async def search_duck(params: SerpQuery) -> SerpResults:
+async def search_duck(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Searches duckduckgo for the specified queries and returns the found documents"""
     logging.info(f"Searching DuckDuckGo for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: query_ddg_search(q, n), params, "duckduckgo search")
-
-
-# Shared across all queries and requests: once a backend has failed
-# `failure_threshold` times in a row, skip it for `cooldown_seconds` instead
-# of attempting (and paying the timeout cost of) another call that's very
-# likely to fail - and, more importantly, stop hammering a backend that may
-# already be rate-limiting or blocking this deployment's IP.
-_backend_circuit_breaker = CircuitBreaker(failure_threshold=3, cooldown_seconds=60.0)
-
-
-async def _search_one(q: str, n_results: int) -> tuple[str, list[dict], Optional[str]]:
-    """Try DDG, then Brave, then Bing for a single query; stop at the first success."""
-    backends = [
-        ("DuckDuckGo", lambda: query_ddg_search(q, n_results)),
-        ("Brave Search", lambda: query_brave_search(pw_browser, q, n_results)),
-        ("Bing", lambda: query_bing_search(pw_browser, q, n_results)),
-    ]
-    last_error: Optional[Exception] = None
-    for name, call in backends:
-        try:
-            _backend_circuit_breaker.before_call(name)
-        except CircuitOpenError as e:
-            logging.info(f"Skipping {name} for query `{q}`: {e}")
-            last_error = e
-            continue
-
-        try:
-            logging.info(f"Querying {name} with query: `{q}`")
-            result = await call()
-            _backend_circuit_breaker.record_success(name)
-            return q, result, None
-        except EmptyResultsError as e:
-            # Zero results is ambiguous - no hits, or a soft block that
-            # parsed to nothing. Move on to the next backend, but don't
-            # hold it against this one: the breaker is process-wide, so
-            # counting it would let a few unusual-but-legitimate queries
-            # disable the primary backend for every user. A hard block
-            # normally raises a real error, which is handled below.
-            logging.info(f"{name} returned no results for query `{q}`")
-            last_error = e
-        except Exception as e:
-            logging.error(f"Failed to query {name} with query `{q}`: {e}")
-            _backend_circuit_breaker.record_failure(name)
-            last_error = e
-
-    return q, [], f"All backends failed for query '{q}': {last_error}"
+    return await service.duckduckgo(params)
 
 
 @serp_router.post("/search")
-async def search(params: SerpQuery) -> SerpResults:
+async def search(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Attempts to search the specified queries using ALL backends"""
-    outcomes = await asyncio.gather(*[_search_one(q, params.n_results) for q in params.queries])
-
-    results: list[dict] = []
-    errors: list[str] = []
-    for _q, res, err in outcomes:
-        results.extend(res)
-        if err:
-            errors.append(err)
-
-    if len(results) == 0:
-        return SerpResults(results=[], error="; ".join(errors) if errors else "All backends are rate-limited.")
-
-    return SerpResults(results=results, error="; ".join(errors) if errors else None)
+    return await service.search(params)
 
 # =========================== Scrapping endpoints ===========================
 
 
-def _is_not_found(exc: Exception) -> bool:
-    """True only when a backend positively said the document is absent.
-
-    Anything else - a 5xx, a rate-limit, a timeout, an unparseable page -
-    is a failure to answer, not an answer.
-    """
-    return isinstance(exc, HTTPStatusError) and exc.response.status_code == 404
-
-
-def _upstream_status(exc: Exception) -> int:
-    """The status to report for a failed upstream call. Never 404.
-
-    404 is a claim that the patent does not exist, and MCP_INSTRUCTIONS
-    tells agents to believe it and move on without retrying - so it has to
-    be reserved for a backend actually saying so. A transient outage
-    reported as 404 teaches an agent that a real patent is absent.
-    """
-    return 504 if isinstance(exc, httpx.TimeoutException) else 502
-
-
 @scrap_router.get("/scrap_patent/{patent_id}")
-async def scrap_patent(patent_id: PatentId) -> PatentScrapResult:
+async def scrap_patent(patent_id: PatentId, service: PatentServiceDep) -> PatentScrapResult:
     """Scraps the specified patent from Google Patents.
 
     Falls back to the EPO OPS API (which covers patents missing from Google
     Patents) when the scrape fails and OPS credentials are configured.
     """
-    google_error: Exception
-    try:
-        return await scrap_patent_async(httpx_client, f"https://patents.google.com/patent/{patent_id}/en")
-    except HTTPStatusError as e:
-        google_error = e
-        logging.warning(
-            f"Google Patents returned {e.response.status_code} for {patent_id}.")
-    except Exception as e:
-        google_error = e
-        logging.warning(f"Failed to scrap patent {patent_id}: {e}")
-
-    if not ops_token_manager.configured:
-        if _is_not_found(google_error):
-            raise HTTPException(
-                status_code=404,
-                detail=f"Patent '{patent_id}' not found on Google Patents (EPO OPS fallback not configured).")
-        raise HTTPException(
-            status_code=_upstream_status(google_error),
-            detail=f"Google Patents request failed for '{patent_id}' and the EPO OPS fallback is not configured: {google_error}")
-
-    try:
-        logging.info(f"Trying OPS for patent {patent_id}.")
-        return await ops_scrap_patent(httpx_client, patent_id)
-    except Exception as e:
-        logging.warning(f"OPS fallback failed for {patent_id}: {e}")
-        # Only claim the patent doesn't exist when *both* backends said so.
-        if _is_not_found(google_error) and _is_not_found(e):
-            raise HTTPException(
-                status_code=404,
-                detail=f"Patent '{patent_id}' not found on Google Patents or EPO OPS.") from e
-        if isinstance(e, HTTPStatusError):
-            raise HTTPException(
-                status_code=_upstream_status(e),
-                detail=f"EPO OPS returned {e.response.status_code} for '{patent_id}'.") from e
-        raise HTTPException(
-            status_code=_upstream_status(e),
-            detail=f"EPO OPS request failed for '{patent_id}': {e}") from e
-
-
-# Same reasoning as MAX_QUERIES_PER_REQUEST in serp.py: one accepted
-# request must not be able to queue unbounded outbound work. The OPS
-# variant is the expensive one - three requests per id.
-MAX_BULK_PATENT_IDS = 50
+    return await service.scrap(patent_id)
 
 
 class ScrapPatentsRequest(BaseModel):
@@ -380,51 +258,32 @@ class ScrapPatentsRequest(BaseModel):
 
 
 @scrap_router.post("/scrap_patents_bulk", response_model=PatentScrapBulkResponse)
-async def scrap_patents(params: ScrapPatentsRequest) -> PatentScrapBulkResponse:
+async def scrap_patents(params: ScrapPatentsRequest,
+                        service: PatentServiceDep) -> PatentScrapBulkResponse:
     """Scraps multiple patents from Google Patents."""
-    patents = await scrap_patent_bulk_async(httpx_client, params.patent_ids)
-    return patents
+    return await service.scrap_bulk(params.patent_ids)
 
 # =========================== EPO OPS endpoints ===========================
 
 
 @ops_router.post("/search")
-async def ops_keyword_search(params: SerpQuery) -> SerpResults:
+async def ops_keyword_search(params: SerpQuery, service: SearchServiceDep) -> SerpResults:
     """Keyword-searches patents via the official EPO OPS API."""
     logging.info(f"Searching EPO OPS for queries: {params.queries}")
-    return await _run_serp_queries(
-        lambda q, n: ops_search(httpx_client, q, n), params, "OPS search")
+    return await service.ops_keyword_search(params)
 
 
 @ops_router.get("/scrap_patent/{patent_id}")
-async def ops_get_patent(patent_id: PatentId) -> PatentScrapResult:
+async def ops_get_patent(patent_id: PatentId, service: PatentServiceDep) -> PatentScrapResult:
     """Retrieves a patent (biblio + abstract + claims + description) via EPO OPS."""
-    if not ops_token_manager.configured:
-        raise HTTPException(
-            status_code=503,
-            detail="EPO OPS is not configured (OPS_CONSUMER_KEY / OPS_CONSUMER_SECRET missing).")
-    try:
-        return await ops_scrap_patent(httpx_client, patent_id)
-    except OPSNotConfigured as e:
-        raise HTTPException(status_code=503, detail="EPO OPS is not configured.") from e
-    except HTTPStatusError as e:
-        if e.response.status_code == 404:
-            raise HTTPException(
-                status_code=404, detail=f"Patent '{patent_id}' not found in EPO OPS.") from e
-        raise HTTPException(
-            status_code=_upstream_status(e),
-            detail=f"EPO OPS returned {e.response.status_code} for '{patent_id}'.") from e
-    except Exception as e:
-        logging.warning(f"Failed to retrieve patent {patent_id} from OPS: {e}")
-        raise HTTPException(
-            status_code=_upstream_status(e),
-            detail=f"EPO OPS request failed for '{patent_id}': {e}") from e
+    return await service.ops_scrap(patent_id)
 
 
 @ops_router.post("/scrap_patents_bulk", response_model=OPSBulkResponse)
-async def ops_get_patents_bulk(params: ScrapPatentsRequest) -> OPSBulkResponse:
+async def ops_get_patents_bulk(params: ScrapPatentsRequest,
+                               service: PatentServiceDep) -> OPSBulkResponse:
     """Retrieves multiple patents via EPO OPS."""
-    return await ops_scrap_patent_bulk(httpx_client, params.patent_ids)
+    return await service.ops_scrap_bulk(params.patent_ids)
 
 # ===============================================================================
 

services.py

@@ -0,0 +1,337 @@
+"""Backend orchestration, separated from HTTP wiring.
+
+The policy in here - which backend to try, in what order, when to fall back
+to another, what counts as evidence a backend is unhealthy, and when a
+patent is genuinely absent rather than merely unreachable - is domain
+policy. It would be equally true behind a CLI or a queue consumer, and it
+was previously written inline in FastAPI route handlers, which meant
+exercising any of it cost an ASGI round-trip.
+
+The stateful collaborators (HTTP client, browser, circuit breaker, OPS
+credentials) are constructor arguments rather than module globals reached
+into at call time. That is what lets a test build a service with its own
+circuit breaker instead of resetting a process-wide singleton between
+tests, and hand in a stand-in for the OPS credentials instead of assigning
+to private attributes on the real token manager.
+
+The stateless backend functions (`query_arxiv` and friends) stay
+module-level imports: they hold no state, so a test that wants to replace
+one can monkeypatch it here without any of the problems shared mutable
+state causes.
+
+Services raise domain errors - `PatentNotFound`, `UpstreamUnavailable` -
+rather than `HTTPException`. Mapping those onto status codes is the HTTP
+layer's job, and lives in app.py.
+"""
+
+import asyncio
+import logging
+from typing import Callable, Optional
+
+import httpx
+from httpx import AsyncClient, HTTPStatusError
+from playwright.async_api import Browser
+
+from circuit_breaker import CircuitBreaker, CircuitOpenError
+from ops import (OPSBulkResponse, ops_scrap_patent, ops_scrap_patent_bulk,
+                 ops_search)
+from scrap import (PatentScrapBulkResponse, PatentScrapResult,
+                   scrap_patent_async, scrap_patent_bulk_async)
+from serp import (EmptyResultsError, SerpQuery, SerpResults, query_arxiv,
+                  query_bing_search, query_brave_search, query_ddg_search,
+                  query_google_patents, query_google_scholar)
+from utils import log_gathered_exceptions
+
+logger = logging.getLogger(__name__)
+
+
+# ================================ domain errors ================================
+
+
+class PatentNotFound(Exception):
+    """Every backend consulted positively said the document is absent.
+
+    Distinct from UpstreamUnavailable on purpose: MCP_INSTRUCTIONS tells an
+    agent that a not-found patent is genuinely absent everywhere and to
+    move on without retrying, so this must never stand in for "we couldn't
+    reach anyone".
+    """
+
+
+class UpstreamUnavailable(Exception):
+    """A backend failed to answer. Says nothing about whether the document
+    exists."""
+
+    def __init__(self, message: str, *, timeout: bool = False):
+        super().__init__(message)
+        self.timeout = timeout
+
+
+class OPSUnconfigured(Exception):
+    """An OPS-only operation was requested without credentials configured."""
+
+
+def _is_not_found(exc: BaseException) -> bool:
+    """True only when a backend positively said the document is absent."""
+    return isinstance(exc, HTTPStatusError) and exc.response.status_code == 404
+
+
+def _as_upstream(exc: BaseException, message: str) -> UpstreamUnavailable:
+    return UpstreamUnavailable(message, timeout=isinstance(exc, httpx.TimeoutException))
+
+
+# ================================ result shaping ================================
+
+
+def shape_serp_results(results: list) -> SerpResults:
+    """Flatten a list of per-query result-lists (or Exceptions, from a
+    `return_exceptions=True` gather) into one SerpResults, surfacing the
+    last error only when every query failed.
+    """
+    if not results:
+        # The request models bound the query list, so this is unreachable
+        # from the endpoints; keep the helper total anyway rather than
+        # indexing into an empty list, since every search path shares it.
+        return SerpResults(results=[], error="No queries were provided.")
+
+    filtered_results = [r for r in results if not isinstance(r, Exception)]
+    flattened_results = [
+        item for sublist in filtered_results for item in sublist]
+
+    if len(filtered_results) == 0:
+        return SerpResults(results=[], error=str(results[-1]))
+
+    return SerpResults(results=flattened_results, error=None)
+
+
+# ================================= search service =================================
+
+
+class SearchService:
+    """Runs SERP queries across the available backends."""
+
+    def __init__(self, *, http_client: AsyncClient,
+                 browser_provider: Callable[[], Optional[Browser]],
+                 circuit_breaker: CircuitBreaker, ops_tokens):
+        self._http = http_client
+        # A provider rather than the browser itself: the browser is started
+        # by the app's lifespan, after this service may already exist, and
+        # is None when Playwright failed to start.
+        self._browser_provider = browser_provider
+        self._breaker = circuit_breaker
+        self._ops_tokens = ops_tokens
+
+    @property
+    def browser(self) -> Optional[Browser]:
+        return self._browser_provider()
+
+    async def _run_queries(self, fn, params: SerpQuery, context: str) -> SerpResults:
+        """Run `fn(query, n_results)` concurrently for every query, log any
+        failures, and shape the result the way every simple search path
+        expects.
+        """
+        results = await asyncio.gather(
+            *[fn(q, params.n_results) for q in params.queries], return_exceptions=True)
+        log_gathered_exceptions(results, context, params.queries)
+        return shape_serp_results(results)
+
+    # ------------------------------ single backend ------------------------------
+
+    async def google_scholar(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: query_google_scholar(self.browser, q, n), params,
+            "google scholar search")
+
+    async def arxiv(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: query_arxiv(self._http, q, n), params, "arxiv search")
+
+    async def brave(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: query_brave_search(self.browser, q, n), params, "brave search")
+
+    async def bing(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: query_bing_search(self.browser, q, n), params, "bing search")
+
+    async def duckduckgo(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: query_ddg_search(q, n), params, "duckduckgo search")
+
+    async def ops_keyword_search(self, params: SerpQuery) -> SerpResults:
+        return await self._run_queries(
+            lambda q, n: ops_search(self._http, q, n), params, "OPS search")
+
+    # -------------------------------- patents --------------------------------
+
+    async def patents(self, params: SerpQuery) -> SerpResults:
+        """Google Patents, falling back to EPO OPS for any query it returns
+        nothing for (when OPS credentials are configured)."""
+        results = await asyncio.gather(
+            *[query_google_patents(self.browser, q, params.n_results)
+              for q in params.queries],
+            return_exceptions=True)
+        log_gathered_exceptions(results, "google patent search", params.queries)
+
+        # Gathered rather than awaited one at a time: this path exists for
+        # when Google Patents is unavailable, so it is exactly when a
+        # request can least afford N sequential round-trips to the slower
+        # backend.
+        if self._ops_tokens.configured:
+            needs_fallback = [
+                i for i, res in enumerate(results)
+                if isinstance(res, Exception) or not res]
+            if needs_fallback:
+                logger.info(
+                    f"Google Patents empty for {len(needs_fallback)} quer(y/ies), trying OPS.")
+                fallback = await asyncio.gather(
+                    *[ops_search(self._http, params.queries[i], params.n_results)
+                      for i in needs_fallback],
+                    return_exceptions=True)
+                # strict: gather returns exactly one result per index, so a
+                # length mismatch here would be a bug worth surfacing.
+                for i, res in zip(needs_fallback, fallback, strict=True):
+                    if isinstance(res, Exception):
+                        logger.warning(f"OPS fallback failed for `{params.queries[i]}`: {res}")
+                    else:
+                        results[i] = res
+
+        return shape_serp_results(results)
+
+    # ----------------------------- all backends -----------------------------
+
+    async def _search_one(self, q: str, n_results: int) -> tuple[str, list[dict], Optional[str]]:
+        """Try DDG, then Brave, then Bing for a single query; stop at the
+        first success."""
+        backends = [
+            ("DuckDuckGo", lambda: query_ddg_search(q, n_results)),
+            ("Brave Search", lambda: query_brave_search(self.browser, q, n_results)),
+            ("Bing", lambda: query_bing_search(self.browser, q, n_results)),
+        ]
+        last_error: Optional[Exception] = None
+        for name, call in backends:
+            try:
+                self._breaker.before_call(name)
+            except CircuitOpenError as e:
+                logger.info(f"Skipping {name} for query `{q}`: {e}")
+                last_error = e
+                continue
+
+            try:
+                logger.info(f"Querying {name} with query: `{q}`")
+                result = await call()
+                self._breaker.record_success(name)
+                return q, result, None
+            except EmptyResultsError as e:
+                # Zero results is ambiguous - no hits, or a soft block that
+                # parsed to nothing. Move on to the next backend, but don't
+                # hold it against this one: the breaker is shared across
+                # every request, so counting it would let a few
+                # unusual-but-legitimate queries disable the primary backend
+                # for everyone. A hard block normally raises a real error,
+                # which is handled below.
+                logger.info(f"{name} returned no results for query `{q}`")
+                last_error = e
+            except Exception as e:
+                logger.error(f"Failed to query {name} with query `{q}`: {e}")
+                self._breaker.record_failure(name)
+                last_error = e
+
+        return q, [], f"All backends failed for query '{q}': {last_error}"
+
+    async def search(self, params: SerpQuery) -> SerpResults:
+        """Search every query across the full backend fallback chain."""
+        outcomes = await asyncio.gather(
+            *[self._search_one(q, params.n_results) for q in params.queries])
+
+        results: list[dict] = []
+        errors: list[str] = []
+        for _q, res, err in outcomes:
+            results.extend(res)
+            if err:
+                errors.append(err)
+
+        if len(results) == 0:
+            return SerpResults(
+                results=[],
+                error="; ".join(errors) if errors else "All backends are rate-limited.")
+
+        return SerpResults(results=results, error="; ".join(errors) if errors else None)
+
+
+# ================================= patent service =================================
+
+
+class PatentService:
+    """Retrieves patent full text, from Google Patents or EPO OPS."""
+
+    def __init__(self, *, http_client: AsyncClient, ops_tokens):
+        self._http = http_client
+        self._ops_tokens = ops_tokens
+
+    async def scrap(self, patent_id: str) -> PatentScrapResult:
+        """Scrape from Google Patents, falling back to EPO OPS.
+
+        Raises PatentNotFound only when every backend consulted said the
+        document is absent; anything else raises UpstreamUnavailable.
+        """
+        google_error: BaseException
+        try:
+            return await scrap_patent_async(
+                self._http, f"https://patents.google.com/patent/{patent_id}/en")
+        except HTTPStatusError as e:
+            google_error = e
+            logger.warning(
+                f"Google Patents returned {e.response.status_code} for {patent_id}.")
+        except Exception as e:
+            google_error = e
+            logger.warning(f"Failed to scrap patent {patent_id}: {e}")
+
+        if not self._ops_tokens.configured:
+            if _is_not_found(google_error):
+                raise PatentNotFound(
+                    f"Patent '{patent_id}' not found on Google Patents "
+                    "(EPO OPS fallback not configured).")
+            raise _as_upstream(
+                google_error,
+                f"Google Patents request failed for '{patent_id}' and the EPO OPS "
+                f"fallback is not configured: {google_error}")
+
+        try:
+            logger.info(f"Trying OPS for patent {patent_id}.")
+            return await ops_scrap_patent(self._http, patent_id)
+        except Exception as e:
+            logger.warning(f"OPS fallback failed for {patent_id}: {e}")
+            # Only claim the patent doesn't exist when *both* backends said so.
+            if _is_not_found(google_error) and _is_not_found(e):
+                raise PatentNotFound(
+                    f"Patent '{patent_id}' not found on Google Patents or EPO OPS.") from e
+            if isinstance(e, HTTPStatusError):
+                raise _as_upstream(
+                    e, f"EPO OPS returned {e.response.status_code} for '{patent_id}'.") from e
+            raise _as_upstream(e, f"EPO OPS request failed for '{patent_id}': {e}") from e
+
+    async def scrap_bulk(self, patent_ids: list[str]) -> PatentScrapBulkResponse:
+        return await scrap_patent_bulk_async(self._http, patent_ids)
+
+    async def ops_scrap(self, patent_id: str) -> PatentScrapResult:
+        """Retrieve via EPO OPS only, with no Google Patents fallback."""
+        if not self._ops_tokens.configured:
+            raise OPSUnconfigured(
+                "EPO OPS is not configured (OPS_CONSUMER_KEY / OPS_CONSUMER_SECRET missing).")
+        try:
+            return await ops_scrap_patent(self._http, patent_id)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                # OPS is the only backend asked here, so its 404 is the
+                # whole answer.
+                raise PatentNotFound(
+                    f"Patent '{patent_id}' not found in EPO OPS.") from e
+            raise _as_upstream(
+                e, f"EPO OPS returned {e.response.status_code} for '{patent_id}'.") from e
+        except Exception as e:
+            logger.warning(f"Failed to retrieve patent {patent_id} from OPS: {e}")
+            raise _as_upstream(e, f"EPO OPS request failed for '{patent_id}': {e}") from e
+
+    async def ops_scrap_bulk(self, patent_ids: list[str]) -> OPSBulkResponse:
+        return await ops_scrap_patent_bulk(self._http, patent_ids)

tests/test_app.py

@@ -1,12 +1,10 @@
-"""Characterization tests for app.py's search endpoints.
-
-These monkeypatch the underlying query_*/ops_search functions rather than
-hitting real search engines - app.py's own job here is just wiring
-(gather queries concurrently, log failures, flatten results, decide when to
-report an error), which is exactly what's being tested. The app's lifespan
-(which starts a real Playwright browser) is never triggered: ASGITransport
-doesn't run it, and these tests don't need it since pw_browser is never
-actually used once the query functions are patched out.
+"""app.py: HTTP wiring only.
+
+The orchestration these endpoints used to contain now lives in
+services.py and is tested in test_search_service.py and
+test_patent_fallback.py without an HTTP layer. What's left here is what
+app.py is actually responsible for: request validation, dependency wiring,
+the lifespan, and turning domain results into responses.
 """
 
 import httpx
@@ -14,9 +12,8 @@ import pytest
 from httpx import ASGITransport
 
 import app as app_module
-from circuit_breaker import CircuitBreaker
-from scrap import PatentScrapResult
-from serp import SerpQuery
+from scrap import PatentScrapBulkResponse, PatentScrapResult
+from serp import SerpResults
 
 
 @pytest.fixture
@@ -26,151 +23,134 @@ async def client():
         yield c
 
 
-@pytest.fixture(autouse=True)
-def _fresh_backend_circuit_breaker(monkeypatch):
-    """`_backend_circuit_breaker` is a module-level singleton shared across
-    every request in production, which is the point - but it means a
-    backend failure recorded by one test would otherwise leak into the
-    next. Give every test its own instance.
-    """
-    monkeypatch.setattr(app_module, "_backend_circuit_breaker", CircuitBreaker())
-
-
-# ------------------------- _shape_serp_results / _run_serp_queries -------------------------
+@pytest.fixture
+def override_services():
+    """Install stand-in services for the duration of one test."""
+    def _install(*, search=None, patent=None):
+        if search is not None:
+            app_module.app.dependency_overrides[app_module.get_search_service] = lambda: search
+        if patent is not None:
+            app_module.app.dependency_overrides[app_module.get_patent_service] = lambda: patent
 
+    yield _install
+    app_module.app.dependency_overrides.clear()
 
-def test_shape_serp_results_flattens_successful_lists():
-    result = app_module._shape_serp_results([[{"a": 1}], [{"b": 2}, {"c": 3}]])
-    assert result.results == [{"a": 1}, {"b": 2}, {"c": 3}]
-    assert result.error is None
 
+class _RecordingSearchService:
+    """Records which service method each endpoint dispatched to."""
 
-def test_shape_serp_results_surfaces_last_error_when_all_failed():
-    result = app_module._shape_serp_results([ValueError("first"), RuntimeError("second")])
-    assert result.results == []
-    assert "second" in result.error
+    def __init__(self):
+        self.calls = []
 
+    def _record(self, name):
+        async def _fn(params):
+            self.calls.append((name, list(params.queries), params.n_results))
+            return SerpResults(results=[{"title": name}], error=None)
+        return _fn
 
-def test_shape_serp_results_ignores_failures_when_some_succeed():
-    result = app_module._shape_serp_results([[{"a": 1}], RuntimeError("boom")])
-    assert result.results == [{"a": 1}]
-    assert result.error is None
+    def __getattr__(self, name):
+        return self._record(name)
 
 
-async def test_run_serp_queries_calls_fn_per_query_and_shapes_result():
-    params = SerpQuery(queries=["x", "y"], n_results=5)
-    calls = []
+class _StubPatentService:
+    def __init__(self):
+        self.calls = []
 
-    async def fn(q, n):
-        calls.append((q, n))
-        return [{"q": q}]
+    async def scrap(self, patent_id):
+        self.calls.append(("scrap", patent_id))
+        return PatentScrapResult(title="Widget apparatus")
 
-    result = await app_module._run_serp_queries(fn, params, "test context")
+    async def scrap_bulk(self, patent_ids):
+        self.calls.append(("scrap_bulk", patent_ids))
+        return PatentScrapBulkResponse(patents=[], failed_ids=list(patent_ids))
 
-    assert sorted(calls) == [("x", 5), ("y", 5)]
-    assert sorted(result.results, key=str) == sorted([{"q": "x"}, {"q": "y"}], key=str)
+    async def ops_scrap(self, patent_id):
+        self.calls.append(("ops_scrap", patent_id))
+        return PatentScrapResult(title="From OPS")
 
+    async def ops_scrap_bulk(self, patent_ids):
+        self.calls.append(("ops_scrap_bulk", patent_ids))
+        return PatentScrapBulkResponse(patents=[], failed_ids=list(patent_ids))
 
-# ------------------------------------- endpoints -------------------------------------
 
+# ------------------------------- endpoint dispatch -------------------------------
 
-async def test_search_arxiv_flattens_results_from_all_queries(client, monkeypatch):
-    async def fake_query_arxiv(client_arg, q, n):
-        return [{"title": f"paper about {q}", "href": "x", "body": "y", "id": "1"}]
 
-    monkeypatch.setattr(app_module, "query_arxiv", fake_query_arxiv)
+@pytest.mark.parametrize("path, expected_method", [
+    ("/serp/search_scholar", "google_scholar"),
+    ("/serp/search_arxiv", "arxiv"),
+    ("/serp/search_patents", "patents"),
+    ("/serp/search_brave", "brave"),
+    ("/serp/search_bing", "bing"),
+    ("/serp/search_duck", "duckduckgo"),
+    ("/serp/search", "search"),
+    ("/ops/search", "ops_keyword_search"),
+])
+async def test_each_search_endpoint_dispatches_to_its_service_method(
+        client, override_services, path, expected_method):
+    """Guards the wiring itself: every endpoint reaching the right method
+    with the request's queries and result count intact."""
+    service = _RecordingSearchService()
+    override_services(search=service)
 
-    resp = await client.post("/serp/search_arxiv", json={"queries": ["a", "b"], "n_results": 5})
+    resp = await client.post(path, json={"queries": ["a", "b"], "n_results": 25})
 
     assert resp.status_code == 200
-    data = resp.json()
-    assert data["error"] is None
-    assert {r["title"] for r in data["results"]} == {"paper about a", "paper about b"}
-
+    assert service.calls == [(expected_method, ["a", "b"], 25)]
+    assert resp.json()["results"] == [{"title": expected_method}]
 
-async def test_search_arxiv_all_queries_failing_returns_error(client, monkeypatch):
-    async def failing_query_arxiv(client_arg, q, n):
-        raise RuntimeError(f"boom for {q}")
 
-    monkeypatch.setattr(app_module, "query_arxiv", failing_query_arxiv)
+@pytest.mark.parametrize("method, path, expected_call", [
+    ("get", "/scrap/scrap_patent/US11930446B2", ("scrap", "US11930446B2")),
+    ("get", "/ops/scrap_patent/US11930446B2", ("ops_scrap", "US11930446B2")),
+])
+async def test_patent_endpoints_dispatch_to_their_service_method(
+        client, override_services, method, path, expected_call):
+    service = _StubPatentService()
+    override_services(patent=service)
 
-    resp = await client.post("/serp/search_arxiv", json={"queries": ["a"], "n_results": 5})
+    resp = await getattr(client, method)(path)
 
     assert resp.status_code == 200
-    data = resp.json()
-    assert data["results"] == []
-    assert "boom for a" in data["error"]
-
-
-async def test_search_patents_does_not_fall_back_when_google_patents_succeeds(client, monkeypatch):
-    async def fake_google_patents(browser, q, n):
-        return [{"id": "US1", "href": "h", "title": "t", "body": "b"}]
-
-    ops_search_called = False
-
-    async def fake_ops_search(client_arg, q, n):
-        nonlocal ops_search_called
-        ops_search_called = True
-        return []
-
-    monkeypatch.setattr(app_module, "query_google_patents", fake_google_patents)
-    monkeypatch.setattr(app_module, "ops_search", fake_ops_search)
-    monkeypatch.setattr(app_module.ops_token_manager, "_key", "k")
-    monkeypatch.setattr(app_module.ops_token_manager, "_secret", "s")
-
-    resp = await client.post("/serp/search_patents", json={"queries": ["widget"], "n_results": 5})
-
-    data = resp.json()
-    assert data["results"] == [{"id": "US1", "href": "h", "title": "t", "body": "b"}]
-    assert ops_search_called is False
-
+    assert service.calls == [expected_call]
 
-async def test_search_patents_falls_back_to_ops_when_google_patents_empty(client, monkeypatch):
-    async def fake_google_patents(browser, q, n):
-        return []
 
-    async def fake_ops_search(client_arg, q, n):
-        return [{"title": "OPS result", "body": "", "href": "", "id": "US123"}]
+@pytest.mark.parametrize("path, expected_method", [
+    ("/scrap/scrap_patents_bulk", "scrap_bulk"),
+    ("/ops/scrap_patents_bulk", "ops_scrap_bulk"),
+])
+async def test_bulk_endpoints_dispatch_to_their_service_method(
+        client, override_services, path, expected_method):
+    service = _StubPatentService()
+    override_services(patent=service)
 
-    monkeypatch.setattr(app_module, "query_google_patents", fake_google_patents)
-    monkeypatch.setattr(app_module, "ops_search", fake_ops_search)
-    monkeypatch.setattr(app_module.ops_token_manager, "_key", "k")
-    monkeypatch.setattr(app_module.ops_token_manager, "_secret", "s")
+    resp = await client.post(path, json={"patent_ids": ["US11930446B2"]})
 
-    resp = await client.post("/serp/search_patents", json={"queries": ["widget"], "n_results": 5})
-
-    data = resp.json()
-    assert data["results"] == [{"title": "OPS result", "body": "", "href": "", "id": "US123"}]
-
-
-async def test_search_patents_no_fallback_when_ops_not_configured(client, monkeypatch):
-    async def fake_google_patents(browser, q, n):
-        return []
-
-    monkeypatch.setattr(app_module, "query_google_patents", fake_google_patents)
-    monkeypatch.setattr(app_module.ops_token_manager, "_key", None)
-    monkeypatch.setattr(app_module.ops_token_manager, "_secret", None)
-
-    resp = await client.post("/serp/search_patents", json={"queries": ["widget"], "n_results": 5})
-
-    data = resp.json()
-    assert data["results"] == []
-    assert data["error"] is None
+    assert resp.status_code == 200
+    assert service.calls == [(expected_method, ["US11930446B2"])]
 
 
 # ------------------------------- patent_id validation -------------------------------
 
 
-async def test_scrap_patent_rejects_malformed_patent_id(client):
-    resp = await client.get("/scrap/scrap_patent/not-a-patent-id")
+@pytest.mark.parametrize("path", [
+    "/scrap/scrap_patent/not-a-patent-id",
+    "/ops/scrap_patent/not-a-patent-id",
+])
+async def test_malformed_patent_id_is_rejected(client, path):
+    resp = await client.get(path)
     assert resp.status_code == 422
 
 
-async def test_scrap_patent_accepts_well_formed_patent_id(client, monkeypatch):
-    async def fake_scrap(client_arg, url):
-        return PatentScrapResult(title="Widget apparatus")
+@pytest.mark.parametrize("path", [
+    "/scrap/scrap_patents_bulk", "/ops/scrap_patents_bulk"])
+async def test_malformed_patent_id_in_a_bulk_list_is_rejected(client, path):
+    resp = await client.post(path, json={"patent_ids": ["US11930446B2", "garbage!!"]})
+    assert resp.status_code == 422
 
-    monkeypatch.setattr(app_module, "scrap_patent_async", fake_scrap)
+
+async def test_well_formed_patent_id_is_accepted(client, override_services):
+    override_services(patent=_StubPatentService())
 
     resp = await client.get("/scrap/scrap_patent/US11930446B2")
 
@@ -178,38 +158,47 @@ async def test_scrap_patent_accepts_well_formed_patent_id(client, monkeypatch):
     assert resp.json()["title"] == "Widget apparatus"
 
 
-async def test_ops_get_patent_rejects_malformed_patent_id(client):
-    resp = await client.get("/ops/scrap_patent/not-a-patent-id")
-    assert resp.status_code == 422
+# ---------------------------- default dependency wiring ----------------------------
 
 
-async def test_scrap_patents_bulk_rejects_malformed_id_in_list(client):
-    resp = await client.post(
-        "/scrap/scrap_patents_bulk", json={"patent_ids": ["US11930446B2", "garbage!!"]})
-    assert resp.status_code == 422
+def test_the_default_search_service_gets_the_apps_collaborators():
+    """The providers exist so tests can override them; this pins that the
+    un-overridden ones still hand the service the real collaborators."""
+    service = app_module.get_search_service()
 
+    assert service._http is app_module.httpx_client
+    assert service._breaker is app_module._backend_circuit_breaker
+    assert service._ops_tokens is app_module.ops_token_manager
 
-async def test_ops_scrap_patents_bulk_rejects_malformed_id_in_list(client):
-    resp = await client.post("/ops/scrap_patents_bulk", json={"patent_ids": ["garbage!!"]})
-    assert resp.status_code == 422
 
+def test_the_search_service_reads_the_browser_lazily(monkeypatch):
+    """The browser is started by the lifespan, after the service may already
+    exist, and stays None when Playwright fails to start - so the service
+    has to read it per call rather than capture it at construction."""
+    service = app_module.get_search_service()
+    monkeypatch.setattr(app_module, "pw_browser", "a-browser")
 
-async def test_ops_keyword_search_flattens_results(client, monkeypatch):
-    async def fake_ops_search(client_arg, q, n):
-        return [{"title": f"OPS {q}", "body": "", "href": "", "id": "1"}]
+    assert service.browser == "a-browser"
 
-    monkeypatch.setattr(app_module, "ops_search", fake_ops_search)
 
-    resp = await client.post("/ops/search", json={"queries": ["a", "b"], "n_results": 5})
+def test_the_default_patent_service_gets_the_apps_collaborators():
+    service = app_module.get_patent_service()
 
-    data = resp.json()
-    assert data["error"] is None
-    assert {r["title"] for r in data["results"]} == {"OPS a", "OPS b"}
+    assert service._http is app_module.httpx_client
+    assert service._ops_tokens is app_module.ops_token_manager
 
 
 # ------------------------------------- api_lifespan -------------------------------------
 
 
+class _RecordingClient:
+    def __init__(self):
+        self.closed = False
+
+    async def aclose(self):
+        self.closed = True
+
+
 async def test_api_lifespan_launches_chromium_without_a_sandbox(monkeypatch):
     """The container runs as a non-root user (see the Dockerfile), and
     Chromium's own internal sandbox needs privileges a non-root container
@@ -255,24 +244,10 @@ async def test_api_lifespan_launches_chromium_without_a_sandbox(monkeypatch):
     assert "--no-sandbox" in launch_calls[0].get("args", [])
 
 
-class _RecordingClient:
-    def __init__(self):
-        self.closed = False
-
-    async def aclose(self):
-        self.closed = True
-
-
 async def test_api_lifespan_closes_the_http_client_on_shutdown(monkeypatch):
     """The client was created at import and never closed - the browser was
     torn down on shutdown but its connection pool was not.
     """
-    class FakePlaywright:
-        chromium = None
-
-        async def stop(self):
-            pass
-
     recording_client = _RecordingClient()
     monkeypatch.setattr(app_module, "pw_browser", None)
     monkeypatch.setattr(app_module, "playwright", None)
@@ -301,257 +276,3 @@ async def test_api_lifespan_survives_playwright_failing_to_start(monkeypatch):
 
     async with app_module.api_lifespan(app_module.app):
         assert app_module.pw_browser is None
-
-
-# --------------------------------- _search_one fallback ---------------------------------
-
-
-async def test_search_one_returns_first_backend_that_succeeds(monkeypatch):
-    calls = []
-
-    async def fake_ddg(q, n):
-        calls.append("ddg")
-        return [{"title": "from ddg"}]
-
-    async def fake_brave(browser, q, n):
-        calls.append("brave")
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", fake_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    q, results, err = await app_module._search_one("widget", 5)
-
-    assert calls == ["ddg"]
-    assert results == [{"title": "from ddg"}]
-    assert err is None
-
-
-async def test_search_one_falls_through_to_the_next_backend_on_failure(monkeypatch):
-    calls = []
-
-    async def failing_ddg(q, n):
-        calls.append("ddg")
-        raise RuntimeError("ddg blocked")
-
-    async def fake_brave(browser, q, n):
-        calls.append("brave")
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    q, results, err = await app_module._search_one("widget", 5)
-
-    assert calls == ["ddg", "brave"]
-    assert results == [{"title": "from brave"}]
-    assert err is None
-
-
-async def test_search_one_reports_an_error_when_every_backend_fails(monkeypatch):
-    async def failing(*args):
-        raise RuntimeError("blocked")
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing)
-    monkeypatch.setattr(app_module, "query_brave_search", failing)
-    monkeypatch.setattr(app_module, "query_bing_search", failing)
-
-    q, results, err = await app_module._search_one("widget", 5)
-
-    assert results == []
-    assert "All backends failed for query 'widget'" in err
-    assert "blocked" in err
-
-
-async def test_search_one_skips_a_backend_whose_circuit_is_open(monkeypatch):
-    """A backend that's failed `failure_threshold` times in a row shouldn't
-    be attempted again until its cooldown elapses - repeatedly hammering a
-    backend that's already rate-limiting us only makes that worse.
-    """
-    from circuit_breaker import CircuitBreaker
-
-    fresh_breaker = CircuitBreaker(failure_threshold=1, cooldown_seconds=60)
-    monkeypatch.setattr(app_module, "_backend_circuit_breaker", fresh_breaker)
-
-    ddg_calls = []
-
-    async def failing_ddg(q, n):
-        ddg_calls.append(q)
-        raise RuntimeError("ddg blocked")
-
-    async def fake_brave(browser, q, n):
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    # First call: DDG fails, opening its circuit (threshold=1); Brave picks it up.
-    await app_module._search_one("first query", 5)
-    assert ddg_calls == ["first query"]
-
-    # Second call: DDG's circuit is now open, so it should be skipped
-    # entirely (not called again) and go straight to Brave.
-    q, results, err = await app_module._search_one("second query", 5)
-    assert ddg_calls == ["first query"]  # unchanged - DDG was skipped
-    assert results == [{"title": "from brave"}]
-
-
-# ------------------------------- /serp/search endpoint -------------------------------
-# `_search_one` is covered above; this is the aggregation wrapped around it,
-# which had no coverage - dropping every per-query error left the suite green.
-
-
-async def test_search_endpoint_merges_results_from_every_query(client, monkeypatch):
-    async def fake_ddg(q, n):
-        return [{"title": f"result for {q}"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", fake_ddg)
-
-    resp = await client.post("/serp/search", json={"queries": ["a", "b"], "n_results": 5})
-
-    data = resp.json()
-    assert {r["title"] for r in data["results"]} == {"result for a", "result for b"}
-    assert data["error"] is None
-
-
-async def test_search_endpoint_reports_partial_failure_alongside_results(client, monkeypatch):
-    """A query that no backend could answer must be reported even when
-    another query succeeded - otherwise the caller silently receives fewer
-    results than they asked for with no indication why.
-    """
-    async def selective_ddg(q, n):
-        if q == "bad":
-            raise RuntimeError("blocked")
-        return [{"title": f"result for {q}"}]
-
-    async def failing(*args):
-        raise RuntimeError("blocked")
-
-    monkeypatch.setattr(app_module, "query_ddg_search", selective_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", failing)
-    monkeypatch.setattr(app_module, "query_bing_search", failing)
-
-    resp = await client.post("/serp/search", json={"queries": ["good", "bad"], "n_results": 5})
-
-    data = resp.json()
-    assert [r["title"] for r in data["results"]] == ["result for good"]
-    assert "bad" in data["error"]
-
-
-async def test_search_endpoint_reports_an_error_when_everything_fails(client, monkeypatch):
-    async def failing(*args):
-        raise RuntimeError("blocked")
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing)
-    monkeypatch.setattr(app_module, "query_brave_search", failing)
-    monkeypatch.setattr(app_module, "query_bing_search", failing)
-
-    resp = await client.post("/serp/search", json={"queries": ["a", "b"], "n_results": 5})
-
-    data = resp.json()
-    assert data["results"] == []
-    # Both failed queries are named, not just the last one.
-    assert "'a'" in data["error"] and "'b'" in data["error"]
-
-
-async def test_search_endpoint_falls_through_backends_per_query(client, monkeypatch):
-    """The fallback chain is per query, so one blocked backend shouldn't
-    cost results for queries the next backend can answer."""
-    async def failing_ddg(q, n):
-        raise RuntimeError("ddg blocked")
-
-    async def fake_brave(browser, q, n):
-        return [{"title": f"brave has {q}"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    resp = await client.post("/serp/search", json={"queries": ["a"], "n_results": 5})
-
-    data = resp.json()
-    assert data["results"] == [{"title": "brave has a"}]
-    assert data["error"] is None
-
-
-# --------------------- what counts as a backend failure ---------------------
-
-
-async def test_a_zero_result_query_does_not_open_the_backends_circuit(monkeypatch):
-    """An empty result is ambiguous - it can mean the query genuinely has
-    no hits, or that the backend served an anti-bot page that parsed to
-    nothing. The circuit breaker is a process-wide singleton, so counting
-    the ambiguous case meant three unusual-but-legitimate queries in a row
-    could disable the primary backend for every user of the deployment for
-    a full cooldown.
-    """
-    from circuit_breaker import CircuitBreaker
-    from serp import DuckDuckGoBlockedException
-
-    breaker = CircuitBreaker(failure_threshold=1, cooldown_seconds=60)
-    monkeypatch.setattr(app_module, "_backend_circuit_breaker", breaker)
-
-    ddg_calls = []
-
-    async def empty_ddg(q, n):
-        ddg_calls.append(q)
-        raise DuckDuckGoBlockedException()
-
-    async def fake_brave(browser, q, n):
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", empty_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    await app_module._search_one("obscure query", 5)
-    await app_module._search_one("another obscure query", 5)
-
-    # Still being tried: an empty result is not evidence the backend is down.
-    assert ddg_calls == ["obscure query", "another obscure query"]
-
-
-async def test_an_empty_result_still_falls_through_to_the_next_backend(monkeypatch):
-    """Not counting it against the backend must not stop the fallback: the
-    caller still needs results from somewhere."""
-    from serp import DuckDuckGoBlockedException
-
-    async def empty_ddg(q, n):
-        raise DuckDuckGoBlockedException()
-
-    async def fake_brave(browser, q, n):
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", empty_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    _q, results, err = await app_module._search_one("widget", 5)
-
-    assert results == [{"title": "from brave"}]
-    assert err is None
-
-
-async def test_a_real_backend_error_still_opens_the_circuit(monkeypatch):
-    """The distinction has to cut both ways: a backend that raises a
-    genuine error (a rate limit, a transport failure) is still evidence,
-    and must still trip the breaker.
-    """
-    from circuit_breaker import CircuitBreaker
-
-    breaker = CircuitBreaker(failure_threshold=1, cooldown_seconds=60)
-    monkeypatch.setattr(app_module, "_backend_circuit_breaker", breaker)
-
-    ddg_calls = []
-
-    async def failing_ddg(q, n):
-        ddg_calls.append(q)
-        raise RuntimeError("rate limited")
-
-    async def fake_brave(browser, q, n):
-        return [{"title": "from brave"}]
-
-    monkeypatch.setattr(app_module, "query_ddg_search", failing_ddg)
-    monkeypatch.setattr(app_module, "query_brave_search", fake_brave)
-
-    await app_module._search_one("first", 5)
-    await app_module._search_one("second", 5)
-
-    assert ddg_calls == ["first"]  # skipped the second time

tests/test_auth.py

@@ -15,6 +15,7 @@ import pytest
 from httpx import ASGITransport
 
 import app as app_module
+import services as services_module
 
 
 @pytest.fixture
@@ -47,7 +48,7 @@ async def test_no_key_configured_leaves_the_api_open(client, monkeypatch):
     """The middleware is a no-op unless SERPENT_API_KEY is set - this keeps
     the default deployment exactly as open as it was before it existed.
     """
-    monkeypatch.setattr(app_module, "query_arxiv", _stub_arxiv)
+    monkeypatch.setattr(services_module, "query_arxiv", _stub_arxiv)
 
     resp = await client.post("/serp/search_arxiv", json={"queries": ["a"]})
 
@@ -76,7 +77,7 @@ async def test_wrong_key_is_rejected(client, api_key):
 
 
 async def test_correct_key_via_x_api_key_header_is_accepted(client, api_key, monkeypatch):
-    monkeypatch.setattr(app_module, "query_arxiv", _stub_arxiv)
+    monkeypatch.setattr(services_module, "query_arxiv", _stub_arxiv)
 
     resp = await client.post(
         "/serp/search_arxiv", json={"queries": ["a"]}, headers={"X-API-Key": api_key})
@@ -85,7 +86,7 @@ async def test_correct_key_via_x_api_key_header_is_accepted(client, api_key, mon
 
 
 async def test_correct_key_via_bearer_header_is_accepted(client, api_key, monkeypatch):
-    monkeypatch.setattr(app_module, "query_arxiv", _stub_arxiv)
+    monkeypatch.setattr(services_module, "query_arxiv", _stub_arxiv)
 
     resp = await client.post(
         "/serp/search_arxiv", json={"queries": ["a"]},
@@ -95,7 +96,7 @@ async def test_correct_key_via_bearer_header_is_accepted(client, api_key, monkey
 
 
 async def test_bearer_scheme_match_is_case_insensitive(client, api_key, monkeypatch):
-    monkeypatch.setattr(app_module, "query_arxiv", _stub_arxiv)
+    monkeypatch.setattr(services_module, "query_arxiv", _stub_arxiv)
 
     resp = await client.post(
         "/serp/search_arxiv", json={"queries": ["a"]},

tests/test_input_bounds.py

@@ -16,6 +16,7 @@ import app as app_module
 import scrap as scrap_module
 from app import MAX_BULK_PATENT_IDS, ScrapPatentsRequest
 from serp import MAX_QUERIES_PER_REQUEST, SerpQuery
+from services import shape_serp_results
 
 
 @pytest.fixture
@@ -57,9 +58,9 @@ async def test_oversized_query_list_returns_422(client):
 
 def test_shape_serp_results_is_total_for_an_empty_list():
     """Defence in depth: the helper must not depend on its caller having
-    validated the query list, since it is shared by every search endpoint.
+    validated the query list, since it is shared by every search path.
     """
-    result = app_module._shape_serp_results([])
+    result = shape_serp_results([])
 
     assert result.results == []
     assert result.error is not None

tests/test_patent_fallback.py

@@ -1,13 +1,14 @@
-"""The Google Patents -> EPO OPS fallback chain in app.py.
+"""The Google Patents -> EPO OPS fallback chain.
 
-This is the most heavily-branched code in the module - scrape, catch,
-check whether OPS is configured, fall back, then map OPS's own failures
-onto status codes - and it had no test coverage at all.
+The policy lives in services.PatentService, so most of this is plain unit
+testing with no ASGI client involved. Only the last section goes through
+the app, and only to check that the domain errors the service raises map
+onto the right status codes.
 
-The distinction these tests exist to protect: a 404 means "this patent
-does not exist", and an agent is explicitly told by MCP_INSTRUCTIONS to
-believe it and move on without retrying. Anything else - an upstream
-outage, a timeout, a blocked scrape - must not be reported that way.
+The distinction these tests exist to protect: a 404 means "this patent does
+not exist", and an agent is explicitly told by MCP_INSTRUCTIONS to believe
+it and move on without retrying. Anything else - an upstream outage, a
+timeout, a blocked scrape - must not be reported that way.
 """
 
 import httpx
@@ -15,28 +16,26 @@ import pytest
 from httpx import ASGITransport, HTTPStatusError, Request, Response
 
 import app as app_module
+import services as services_module
 from scrap import PatentScrapResult
+from services import (OPSUnconfigured, PatentNotFound, PatentService,
+                      UpstreamUnavailable)
 
 PATENT_ID = "US11930446B2"
 
 
-@pytest.fixture
-async def client():
-    transport = ASGITransport(app=app_module.app)
-    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
-        yield c
-
+class FakeOPSTokens:
+    """Stand-in for the OPS token manager. Tests only care whether
+    credentials are configured, and this avoids assigning to private
+    attributes on the real module-level singleton.
+    """
 
-@pytest.fixture
-def ops_configured(monkeypatch):
-    monkeypatch.setattr(app_module.ops_token_manager, "_key", "k")
-    monkeypatch.setattr(app_module.ops_token_manager, "_secret", "s")
+    def __init__(self, configured: bool):
+        self.configured = configured
 
 
-@pytest.fixture
-def ops_unconfigured(monkeypatch):
-    monkeypatch.setattr(app_module.ops_token_manager, "_key", None)
-    monkeypatch.setattr(app_module.ops_token_manager, "_secret", None)
+def make_service(*, ops_configured: bool) -> PatentService:
+    return PatentService(http_client=None, ops_tokens=FakeOPSTokens(ops_configured))
 
 
 def _http_error(status: int) -> HTTPStatusError:
@@ -51,10 +50,16 @@ def _raises(exc):
     return _fn
 
 
+def _returns(value):
+    async def _fn(*args, **kwargs):
+        return value
+    return _fn
+
+
 # ------------------------------- the happy path -------------------------------
 
 
-async def test_successful_scrape_never_touches_ops(client, ops_configured, monkeypatch):
+async def test_successful_scrape_never_touches_ops(monkeypatch):
     ops_called = False
 
     async def fake_ops(*args, **kwargs):
@@ -63,133 +68,165 @@ async def test_successful_scrape_never_touches_ops(client, ops_configured, monke
         return PatentScrapResult(title="from OPS")
 
     monkeypatch.setattr(
-        app_module, "scrap_patent_async",
-        lambda c, url: _ok(PatentScrapResult(title="from Google Patents")))
-    monkeypatch.setattr(app_module, "ops_scrap_patent", fake_ops)
+        services_module, "scrap_patent_async",
+        _returns(PatentScrapResult(title="from Google Patents")))
+    monkeypatch.setattr(services_module, "ops_scrap_patent", fake_ops)
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    result = await make_service(ops_configured=True).scrap(PATENT_ID)
 
-    assert resp.status_code == 200
-    assert resp.json()["title"] == "from Google Patents"
+    assert result.title == "from Google Patents"
     assert ops_called is False
 
 
-async def _ok(value):
-    return value
-
-
 # ------------------------- genuine miss vs upstream failure -------------------------
 
 
-async def test_a_real_404_from_google_patents_is_a_404(client, ops_unconfigured, monkeypatch):
+async def test_a_real_404_from_google_patents_is_not_found(monkeypatch):
     """The one case where "not found" is the truth."""
-    monkeypatch.setattr(app_module, "scrap_patent_async", _raises(_http_error(404)))
-
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    monkeypatch.setattr(services_module, "scrap_patent_async", _raises(_http_error(404)))
 
-    assert resp.status_code == 404
+    with pytest.raises(PatentNotFound):
+        await make_service(ops_configured=False).scrap(PATENT_ID)
 
 
 @pytest.mark.parametrize("status", [429, 500, 502, 503])
-async def test_an_upstream_failure_is_not_reported_as_not_found(
-        client, ops_unconfigured, monkeypatch, status):
+async def test_an_upstream_failure_is_not_reported_as_not_found(monkeypatch, status):
     """MCP_INSTRUCTIONS tells the model a "not found" patent is genuinely
     absent everywhere and to move on rather than retrying. Reporting a
     transient upstream failure that way teaches an agent - with the
     server's explicit encouragement - that a real patent does not exist.
     """
-    monkeypatch.setattr(app_module, "scrap_patent_async", _raises(_http_error(status)))
+    monkeypatch.setattr(services_module, "scrap_patent_async", _raises(_http_error(status)))
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    with pytest.raises(UpstreamUnavailable) as exc_info:
+        await make_service(ops_configured=False).scrap(PATENT_ID)
 
-    assert resp.status_code == 502, f"upstream {status} was reported as {resp.status_code}"
+    assert exc_info.value.timeout is False
 
 
-async def test_a_timeout_is_reported_as_a_gateway_timeout(client, ops_unconfigured, monkeypatch):
+async def test_a_timeout_is_flagged_as_a_timeout(monkeypatch):
     monkeypatch.setattr(
-        app_module, "scrap_patent_async", _raises(httpx.ConnectTimeout("timed out")))
+        services_module, "scrap_patent_async", _raises(httpx.ConnectTimeout("timed out")))
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    with pytest.raises(UpstreamUnavailable) as exc_info:
+        await make_service(ops_configured=False).scrap(PATENT_ID)
 
-    assert resp.status_code == 504
+    assert exc_info.value.timeout is True
 
 
-async def test_an_unparseable_page_is_reported_as_a_bad_gateway(
-        client, ops_unconfigured, monkeypatch):
+async def test_an_unparseable_page_is_an_upstream_failure(monkeypatch):
     """parse_patent_html raises ValueError when the page isn't a patent page
     (an interstitial, or a markup change). That is our problem or theirs,
     but it is not evidence the patent doesn't exist.
     """
     monkeypatch.setattr(
-        app_module, "scrap_patent_async", _raises(ValueError("no DC.title")))
-
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+        services_module, "scrap_patent_async", _raises(ValueError("no DC.title")))
 
-    assert resp.status_code == 502
+    with pytest.raises(UpstreamUnavailable):
+        await make_service(ops_configured=False).scrap(PATENT_ID)
 
 
 # --------------------------------- the OPS fallback ---------------------------------
 
 
-async def test_falls_back_to_ops_when_google_patents_fails(client, ops_configured, monkeypatch):
-    monkeypatch.setattr(app_module, "scrap_patent_async", _raises(_http_error(503)))
+async def test_falls_back_to_ops_when_google_patents_fails(monkeypatch):
+    monkeypatch.setattr(services_module, "scrap_patent_async", _raises(_http_error(503)))
     monkeypatch.setattr(
-        app_module, "ops_scrap_patent",
-        lambda c, pid: _ok(PatentScrapResult(title="from OPS")))
+        services_module, "ops_scrap_patent", _returns(PatentScrapResult(title="from OPS")))
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    result = await make_service(ops_configured=True).scrap(PATENT_ID)
 
-    assert resp.status_code == 200
-    assert resp.json()["title"] == "from OPS"
+    assert result.title == "from OPS"
 
 
-async def test_missing_from_both_backends_is_a_404(client, ops_configured, monkeypatch):
-    monkeypatch.setattr(app_module, "scrap_patent_async", _raises(_http_error(404)))
-    monkeypatch.setattr(app_module, "ops_scrap_patent", _raises(_http_error(404)))
+async def test_missing_from_both_backends_is_not_found(monkeypatch):
+    monkeypatch.setattr(services_module, "scrap_patent_async", _raises(_http_error(404)))
+    monkeypatch.setattr(services_module, "ops_scrap_patent", _raises(_http_error(404)))
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    with pytest.raises(PatentNotFound):
+        await make_service(ops_configured=True).scrap(PATENT_ID)
 
-    assert resp.status_code == 404
-    assert "not found" in resp.json()["detail"].lower()
 
-
-async def test_ops_failing_after_a_google_patents_404_is_not_a_404(
-        client, ops_configured, monkeypatch):
+async def test_ops_failing_after_a_google_patents_404_is_not_a_miss(monkeypatch):
     """Google Patents says the patent is missing, but OPS - the backend that
     covers what Google Patents doesn't - never answered. That is unknown,
     not absent.
     """
-    monkeypatch.setattr(app_module, "scrap_patent_async", _raises(_http_error(404)))
-    monkeypatch.setattr(app_module, "ops_scrap_patent", _raises(_http_error(500)))
+    monkeypatch.setattr(services_module, "scrap_patent_async", _raises(_http_error(404)))
+    monkeypatch.setattr(services_module, "ops_scrap_patent", _raises(_http_error(500)))
 
-    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
+    with pytest.raises(UpstreamUnavailable):
+        await make_service(ops_configured=True).scrap(PATENT_ID)
+
+
+# ------------------------------ the OPS-only path ------------------------------
+
+
+async def test_ops_only_retrieval_requires_credentials():
+    with pytest.raises(OPSUnconfigured):
+        await make_service(ops_configured=False).ops_scrap(PATENT_ID)
 
-    assert resp.status_code == 502
 
+async def test_ops_only_retrieval_reports_a_real_miss(monkeypatch):
+    """Here OPS is the only backend asked, so its 404 is the whole answer."""
+    monkeypatch.setattr(services_module, "ops_scrap_patent", _raises(_http_error(404)))
 
-# ------------------------------ the direct /ops endpoint ------------------------------
+    with pytest.raises(PatentNotFound):
+        await make_service(ops_configured=True).ops_scrap(PATENT_ID)
 
 
-async def test_ops_endpoint_reports_a_timeout_as_a_gateway_timeout(
-        client, ops_configured, monkeypatch):
+async def test_ops_only_retrieval_flags_a_timeout(monkeypatch):
     monkeypatch.setattr(
-        app_module, "ops_scrap_patent", _raises(httpx.ConnectTimeout("timed out")))
+        services_module, "ops_scrap_patent", _raises(httpx.ConnectTimeout("timed out")))
 
-    resp = await client.get(f"/ops/scrap_patent/{PATENT_ID}")
+    with pytest.raises(UpstreamUnavailable) as exc_info:
+        await make_service(ops_configured=True).ops_scrap(PATENT_ID)
 
-    assert resp.status_code == 504
+    assert exc_info.value.timeout is True
 
 
-async def test_ops_endpoint_reports_a_real_miss_as_404(client, ops_configured, monkeypatch):
-    """Here OPS is the only backend asked, so its 404 is the whole answer."""
-    monkeypatch.setattr(app_module, "ops_scrap_patent", _raises(_http_error(404)))
+# ---------------------------- domain error -> status code ----------------------------
 
-    resp = await client.get(f"/ops/scrap_patent/{PATENT_ID}")
 
-    assert resp.status_code == 404
+@pytest.fixture
+async def client():
+    transport = ASGITransport(app=app_module.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        yield c
+
+
+@pytest.fixture
+def override_patent_service():
+    """Swap the app's patent service for one the test controls, then put the
+    real provider back."""
+    def _install(service):
+        app_module.app.dependency_overrides[app_module.get_patent_service] = lambda: service
+
+    yield _install
+    app_module.app.dependency_overrides.clear()
+
 
+class _StubService:
+    def __init__(self, error):
+        self._error = error
 
-async def test_ops_endpoint_is_503_when_not_configured(client, ops_unconfigured):
-    resp = await client.get(f"/ops/scrap_patent/{PATENT_ID}")
+    async def scrap(self, patent_id):
+        raise self._error
+
+    ops_scrap = scrap
+
+
+@pytest.mark.parametrize("error, expected_status", [
+    (PatentNotFound("gone"), 404),
+    (UpstreamUnavailable("upstream broke"), 502),
+    (UpstreamUnavailable("slow", timeout=True), 504),
+    (OPSUnconfigured("no credentials"), 503),
+])
+async def test_domain_errors_map_onto_status_codes(
+        client, override_patent_service, error, expected_status):
+    override_patent_service(_StubService(error))
+
+    resp = await client.get(f"/scrap/scrap_patent/{PATENT_ID}")
 
-    assert resp.status_code == 503
+    assert resp.status_code == expected_status
+    assert resp.json()["detail"] == str(error)

tests/test_scrap.py

@@ -89,3 +89,15 @@ async def test_scrap_patent_bulk_async_separates_successes_from_failures():
     assert len(result.patents) == 1
     assert result.patents[0].title == "Widget with improved gadget mechanism"
     assert result.failed_ids == ["US_FAIL"]
+
+
+def test_parse_patent_html_strips_whitespace_around_the_title():
+    """Google Patents' DC.title meta content is frequently padded with
+    newlines and indentation from the surrounding markup, which would
+    otherwise end up in the API response and in every downstream citation.
+    """
+    html = '<html><head><meta name="DC.title" content="  Widget apparatus\n  "></head><body></body></html>'
+
+    result = parse_patent_html(html, "https://patents.google.com/patent/US1/en")
+
+    assert result.title == "Widget apparatus"

tests/test_search_service.py

@@ -0,0 +1,390 @@
+"""SearchService: the backend orchestration policy.
+
+Which backend to try, in what order, when to fall back, and what counts as
+evidence a backend is unhealthy. None of this needs an HTTP layer, so none
+of these tests use one.
+
+Each test builds a service with its own circuit breaker. That replaces the
+autouse fixture that used to reset a process-wide singleton between tests -
+the breaker being shared across every request is correct in production and
+was only a problem because tests had no way to opt out of it.
+"""
+
+
+import services as services_module
+from circuit_breaker import CircuitBreaker
+from serp import DuckDuckGoBlockedException, SerpQuery
+from services import SearchService, shape_serp_results
+
+
+class FakeOPSTokens:
+    def __init__(self, configured: bool):
+        self.configured = configured
+
+
+def make_service(*, ops_configured: bool = False, breaker: CircuitBreaker = None,
+                 browser=None) -> SearchService:
+    return SearchService(
+        http_client=None,
+        browser_provider=lambda: browser,
+        circuit_breaker=breaker or CircuitBreaker(),
+        ops_tokens=FakeOPSTokens(ops_configured),
+    )
+
+
+# --------------------------------- result shaping ---------------------------------
+
+
+class TestShapeSerpResults:
+    def test_flattens_successful_lists(self):
+        result = shape_serp_results([[{"a": 1}], [{"b": 2}, {"c": 3}]])
+        assert result.results == [{"a": 1}, {"b": 2}, {"c": 3}]
+        assert result.error is None
+
+    def test_surfaces_last_error_when_all_failed(self):
+        result = shape_serp_results([ValueError("first"), RuntimeError("second")])
+        assert result.results == []
+        assert "second" in result.error
+
+    def test_ignores_failures_when_some_succeed(self):
+        result = shape_serp_results([[{"a": 1}], RuntimeError("boom")])
+        assert result.results == [{"a": 1}]
+        assert result.error is None
+
+    def test_is_total_for_an_empty_list(self):
+        """Defence in depth: the request models bound the query list, but
+        this helper is shared by every search path and must not depend on
+        its caller having validated anything."""
+        result = shape_serp_results([])
+        assert result.results == []
+        assert result.error is not None
+
+
+# ------------------------------- per-query dispatch -------------------------------
+
+
+async def test_every_query_is_dispatched_with_the_result_count():
+    calls = []
+
+    async def fn(q, n):
+        calls.append((q, n))
+        return [{"q": q}]
+
+    result = await make_service()._run_queries(
+        fn, SerpQuery(queries=["x", "y"], n_results=5), "test context")
+
+    assert sorted(calls) == [("x", 5), ("y", 5)]
+    assert sorted(result.results, key=str) == sorted([{"q": "x"}, {"q": "y"}], key=str)
+
+
+async def test_arxiv_flattens_results_from_all_queries(monkeypatch):
+    async def fake_query_arxiv(client, q, n):
+        return [{"title": f"paper about {q}"}]
+
+    monkeypatch.setattr(services_module, "query_arxiv", fake_query_arxiv)
+
+    result = await make_service().arxiv(SerpQuery(queries=["a", "b"], n_results=5))
+
+    assert {r["title"] for r in result.results} == {"paper about a", "paper about b"}
+    assert result.error is None
+
+
+async def test_arxiv_reports_an_error_when_every_query_fails(monkeypatch):
+    async def failing(client, q, n):
+        raise RuntimeError(f"boom for {q}")
+
+    monkeypatch.setattr(services_module, "query_arxiv", failing)
+
+    result = await make_service().arxiv(SerpQuery(queries=["a"], n_results=5))
+
+    assert result.results == []
+    assert "boom for a" in result.error
+
+
+# ------------------------------ patents + OPS fallback ------------------------------
+
+
+async def test_patents_does_not_fall_back_when_google_patents_succeeds(monkeypatch):
+    ops_called = False
+
+    async def fake_ops(client, q, n):
+        nonlocal ops_called
+        ops_called = True
+        return []
+
+    monkeypatch.setattr(
+        services_module, "query_google_patents",
+        lambda b, q, n: _ok([{"id": "US1", "title": "t"}]))
+    monkeypatch.setattr(services_module, "ops_search", fake_ops)
+
+    result = await make_service(ops_configured=True).patents(
+        SerpQuery(queries=["widget"], n_results=5))
+
+    assert result.results == [{"id": "US1", "title": "t"}]
+    assert ops_called is False
+
+
+async def _ok(value):
+    return value
+
+
+async def test_patents_falls_back_to_ops_when_google_patents_is_empty(monkeypatch):
+    monkeypatch.setattr(services_module, "query_google_patents", lambda b, q, n: _ok([]))
+    monkeypatch.setattr(
+        services_module, "ops_search", lambda c, q, n: _ok([{"id": "US123", "title": "OPS"}]))
+
+    result = await make_service(ops_configured=True).patents(
+        SerpQuery(queries=["widget"], n_results=5))
+
+    assert result.results == [{"id": "US123", "title": "OPS"}]
+
+
+async def test_patents_does_not_fall_back_when_ops_is_unconfigured(monkeypatch):
+    monkeypatch.setattr(services_module, "query_google_patents", lambda b, q, n: _ok([]))
+
+    result = await make_service(ops_configured=False).patents(
+        SerpQuery(queries=["widget"], n_results=5))
+
+    assert result.results == []
+    assert result.error is None
+
+
+async def test_ops_fallback_runs_concurrently_not_one_query_at_a_time(monkeypatch):
+    """This path exists for when Google Patents is unavailable, which is
+    exactly when a request can least afford N sequential round-trips to the
+    slower backend."""
+    import asyncio
+
+    in_flight = 0
+    peak = 0
+
+    async def slow_ops(client, q, n):
+        nonlocal in_flight, peak
+        in_flight += 1
+        peak = max(peak, in_flight)
+        await asyncio.sleep(0.02)
+        in_flight -= 1
+        return [{"id": q}]
+
+    monkeypatch.setattr(services_module, "query_google_patents", lambda b, q, n: _ok([]))
+    monkeypatch.setattr(services_module, "ops_search", slow_ops)
+
+    await make_service(ops_configured=True).patents(
+        SerpQuery(queries=["a", "b", "c", "d"], n_results=5))
+
+    assert peak > 1, "OPS fallback queries were issued one at a time"
+
+
+async def test_a_failing_ops_fallback_does_not_lose_other_queries_results(monkeypatch):
+    async def selective_ops(client, q, n):
+        if q == "bad":
+            raise RuntimeError("OPS down")
+        return [{"id": q}]
+
+    monkeypatch.setattr(services_module, "query_google_patents", lambda b, q, n: _ok([]))
+    monkeypatch.setattr(services_module, "ops_search", selective_ops)
+
+    result = await make_service(ops_configured=True).patents(
+        SerpQuery(queries=["good", "bad"], n_results=5))
+
+    assert result.results == [{"id": "good"}]
+
+
+# -------------------------------- the fallback chain --------------------------------
+
+
+async def test_returns_the_first_backend_that_succeeds(monkeypatch):
+    calls = []
+
+    async def fake_ddg(q, n):
+        calls.append("ddg")
+        return [{"title": "from ddg"}]
+
+    async def fake_brave(browser, q, n):
+        calls.append("brave")
+        return [{"title": "from brave"}]
+
+    monkeypatch.setattr(services_module, "query_ddg_search", fake_ddg)
+    monkeypatch.setattr(services_module, "query_brave_search", fake_brave)
+
+    q, results, err = await make_service()._search_one("widget", 5)
+
+    assert calls == ["ddg"]
+    assert results == [{"title": "from ddg"}]
+    assert err is None
+
+
+async def test_falls_through_to_the_next_backend_on_failure(monkeypatch):
+    calls = []
+
+    async def failing_ddg(q, n):
+        calls.append("ddg")
+        raise RuntimeError("ddg blocked")
+
+    async def fake_brave(browser, q, n):
+        calls.append("brave")
+        return [{"title": "from brave"}]
+
+    monkeypatch.setattr(services_module, "query_ddg_search", failing_ddg)
+    monkeypatch.setattr(services_module, "query_brave_search", fake_brave)
+
+    q, results, err = await make_service()._search_one("widget", 5)
+
+    assert calls == ["ddg", "brave"]
+    assert results == [{"title": "from brave"}]
+    assert err is None
+
+
+async def test_reports_an_error_when_every_backend_fails(monkeypatch):
+    async def failing(*args):
+        raise RuntimeError("blocked")
+
+    for name in ("query_ddg_search", "query_brave_search", "query_bing_search"):
+        monkeypatch.setattr(services_module, name, failing)
+
+    q, results, err = await make_service()._search_one("widget", 5)
+
+    assert results == []
+    assert "All backends failed for query 'widget'" in err
+    assert "blocked" in err
+
+
+# ------------------------------ the circuit breaker ------------------------------
+
+
+async def test_skips_a_backend_whose_circuit_is_open(monkeypatch):
+    """A backend that's failed `failure_threshold` times in a row shouldn't
+    be attempted again until its cooldown elapses - repeatedly hammering a
+    backend that's already rate-limiting us only makes that worse.
+    """
+    ddg_calls = []
+
+    async def failing_ddg(q, n):
+        ddg_calls.append(q)
+        raise RuntimeError("ddg blocked")
+
+    async def fake_brave(browser, q, n):
+        return [{"title": "from brave"}]
+
+    monkeypatch.setattr(services_module, "query_ddg_search", failing_ddg)
+    monkeypatch.setattr(services_module, "query_brave_search", fake_brave)
+
+    service = make_service(breaker=CircuitBreaker(failure_threshold=1, cooldown_seconds=60))
+
+    await service._search_one("first query", 5)
+    assert ddg_calls == ["first query"]
+
+    q, results, err = await service._search_one("second query", 5)
+
+    assert ddg_calls == ["first query"]  # unchanged - DDG was skipped
+    assert results == [{"title": "from brave"}]
+
+
+async def test_a_zero_result_query_does_not_open_the_circuit(monkeypatch):
+    """An empty result is ambiguous - it can mean the query genuinely has no
+    hits, or that the backend served an anti-bot page that parsed to
+    nothing. The breaker is shared across every request, so counting the
+    ambiguous case meant a few unusual-but-legitimate queries could disable
+    the primary backend for everyone for a full cooldown.
+    """
+    ddg_calls = []
+
+    async def empty_ddg(q, n):
+        ddg_calls.append(q)
+        raise DuckDuckGoBlockedException()
+
+    monkeypatch.setattr(services_module, "query_ddg_search", empty_ddg)
+    monkeypatch.setattr(
+        services_module, "query_brave_search", lambda b, q, n: _ok([{"title": "brave"}]))
+
+    service = make_service(breaker=CircuitBreaker(failure_threshold=1, cooldown_seconds=60))
+
+    await service._search_one("obscure", 5)
+    await service._search_one("another obscure", 5)
+
+    assert ddg_calls == ["obscure", "another obscure"]
+
+
+async def test_an_empty_result_still_falls_through_to_the_next_backend(monkeypatch):
+    """Not counting it against the backend must not stop the fallback: the
+    caller still needs results from somewhere."""
+    async def empty_ddg(q, n):
+        raise DuckDuckGoBlockedException()
+
+    monkeypatch.setattr(services_module, "query_ddg_search", empty_ddg)
+    monkeypatch.setattr(
+        services_module, "query_brave_search", lambda b, q, n: _ok([{"title": "from brave"}]))
+
+    _q, results, err = await make_service()._search_one("widget", 5)
+
+    assert results == [{"title": "from brave"}]
+    assert err is None
+
+
+async def test_a_real_backend_error_still_opens_the_circuit(monkeypatch):
+    """The distinction has to cut both ways: a backend raising a genuine
+    error (a rate limit, a transport failure) is still evidence."""
+    ddg_calls = []
+
+    async def failing_ddg(q, n):
+        ddg_calls.append(q)
+        raise RuntimeError("rate limited")
+
+    monkeypatch.setattr(services_module, "query_ddg_search", failing_ddg)
+    monkeypatch.setattr(
+        services_module, "query_brave_search", lambda b, q, n: _ok([{"title": "brave"}]))
+
+    service = make_service(breaker=CircuitBreaker(failure_threshold=1, cooldown_seconds=60))
+
+    await service._search_one("first", 5)
+    await service._search_one("second", 5)
+
+    assert ddg_calls == ["first"]
+
+
+# ------------------------------- search aggregation -------------------------------
+
+
+async def test_search_merges_results_from_every_query(monkeypatch):
+    monkeypatch.setattr(
+        services_module, "query_ddg_search", lambda q, n: _ok([{"title": f"result for {q}"}]))
+
+    result = await make_service().search(SerpQuery(queries=["a", "b"], n_results=5))
+
+    assert {r["title"] for r in result.results} == {"result for a", "result for b"}
+    assert result.error is None
+
+
+async def test_search_reports_partial_failure_alongside_results(monkeypatch):
+    """A query no backend could answer must be reported even when another
+    query succeeded - otherwise the caller silently receives fewer results
+    than they asked for with no indication why."""
+    async def selective_ddg(q, n):
+        if q == "bad":
+            raise RuntimeError("blocked")
+        return [{"title": f"result for {q}"}]
+
+    async def failing(*args):
+        raise RuntimeError("blocked")
+
+    monkeypatch.setattr(services_module, "query_ddg_search", selective_ddg)
+    monkeypatch.setattr(services_module, "query_brave_search", failing)
+    monkeypatch.setattr(services_module, "query_bing_search", failing)
+
+    result = await make_service().search(SerpQuery(queries=["good", "bad"], n_results=5))
+
+    assert [r["title"] for r in result.results] == ["result for good"]
+    assert "bad" in result.error
+
+
+async def test_search_names_every_failed_query_not_just_the_last(monkeypatch):
+    async def failing(*args):
+        raise RuntimeError("blocked")
+
+    for name in ("query_ddg_search", "query_brave_search", "query_bing_search"):
+        monkeypatch.setattr(services_module, name, failing)
+
+    result = await make_service().search(SerpQuery(queries=["a", "b"], n_results=5))
+
+    assert result.results == []
+    assert "'a'" in result.error and "'b'" in result.error

tests/test_serp_navigation.py

@@ -0,0 +1,156 @@
+"""The glue holding each scraper together.
+
+Every Playwright scraper is now: build a URL, open a page, block
+decorative resources, navigate, extract. The builders are tested in
+test_serp_urls.py and the extractors in test_serp_playwright.py; this
+covers the composition - specifically that each scraper navigates to the
+URL its own builder produced.
+
+That link is the one the old goto-patching harness could not test, because
+the stand-in it installed accepted the navigation URL and discarded it.
+These use a recording stand-in browser instead: no real Chromium, and the
+URL is the thing being asserted on.
+"""
+
+import pytest
+
+import serp
+from serp import (bing_search_url, brave_search_url, google_patents_search_url,
+                  google_scholar_url, playwright_open_page,
+                  query_bing_search, query_brave_search, query_google_patents,
+                  query_google_scholar)
+
+SENTINEL = [{"title": "extracted"}]
+
+
+class _RecordingPage:
+    def __init__(self):
+        self.goto_urls = []
+        self.route_patterns = []
+        self.closed = False
+
+    async def route(self, pattern, handler):
+        self.route_patterns.append(pattern)
+
+    async def goto(self, url, **kwargs):
+        self.goto_urls.append(url)
+        return None
+
+    async def close(self):
+        self.closed = True
+
+
+class _RecordingContext:
+    def __init__(self, page):
+        self._page = page
+        self.closed = False
+
+    async def new_page(self):
+        return self._page
+
+    async def close(self):
+        self.closed = True
+
+
+class _RecordingBrowser:
+    def __init__(self):
+        self.page = _RecordingPage()
+        self.context = _RecordingContext(self.page)
+
+    async def new_context(self, **kwargs):
+        return self.context
+
+
+async def _sentinel_extractor(page, n_results):
+    return SENTINEL
+
+
+SCRAPERS = [
+    ("query_google_scholar", query_google_scholar,
+     "_extract_google_scholar_results", google_scholar_url),
+    ("query_google_patents", query_google_patents,
+     "_extract_google_patents_results", google_patents_search_url),
+    ("query_brave_search", query_brave_search,
+     "_extract_brave_results", brave_search_url),
+    ("query_bing_search", query_bing_search,
+     "_extract_bing_results", bing_search_url),
+]
+
+
+@pytest.mark.parametrize("name, scraper, extractor_attr, builder",
+                         SCRAPERS, ids=[s[0] for s in SCRAPERS])
+async def test_scraper_navigates_to_the_url_its_builder_produced(
+        monkeypatch, name, scraper, extractor_attr, builder):
+    monkeypatch.setattr(serp, extractor_attr, _sentinel_extractor)
+    browser = _RecordingBrowser()
+
+    await scraper(browser, "agentic ai", 25)
+
+    assert browser.page.goto_urls == [builder("agentic ai", 25)]
+
+
+@pytest.mark.parametrize("name, scraper, extractor_attr, builder",
+                         SCRAPERS, ids=[s[0] for s in SCRAPERS])
+async def test_scraper_returns_what_its_extractor_produced(
+        monkeypatch, name, scraper, extractor_attr, builder):
+    monkeypatch.setattr(serp, extractor_attr, _sentinel_extractor)
+
+    results = await scraper(_RecordingBrowser(), "widgets", 10)
+
+    assert results == SENTINEL
+
+
+@pytest.mark.parametrize("name, scraper, extractor_attr, builder",
+                         SCRAPERS, ids=[s[0] for s in SCRAPERS])
+async def test_scraper_blocks_decorative_resources(
+        monkeypatch, name, scraper, extractor_attr, builder):
+    """Skipping stylesheets and images meaningfully speeds up navigation,
+    and every scraper is supposed to do it."""
+    monkeypatch.setattr(serp, extractor_attr, _sentinel_extractor)
+    browser = _RecordingBrowser()
+
+    await scraper(browser, "widgets", 10)
+
+    assert browser.page.route_patterns == ["**/*"]
+
+
+@pytest.mark.parametrize("name, scraper, extractor_attr, builder",
+                         SCRAPERS, ids=[s[0] for s in SCRAPERS])
+async def test_scraper_closes_its_page_and_context(
+        monkeypatch, name, scraper, extractor_attr, builder):
+    monkeypatch.setattr(serp, extractor_attr, _sentinel_extractor)
+    browser = _RecordingBrowser()
+
+    await scraper(browser, "widgets", 10)
+
+    assert browser.page.closed and browser.context.closed
+
+
+async def test_page_and_context_are_closed_even_when_extraction_raises(monkeypatch):
+    async def exploding_extractor(page, n_results):
+        raise RuntimeError("selectors changed")
+
+    monkeypatch.setattr(serp, "_extract_bing_results", exploding_extractor)
+    browser = _RecordingBrowser()
+
+    with pytest.raises(RuntimeError):
+        await query_bing_search(browser, "widgets", 10)
+
+    assert browser.page.closed and browser.context.closed
+
+
+async def test_context_is_closed_even_when_closing_the_page_raises():
+    """A crashed renderer can make page.close() throw; the context still has
+    to be released or it leaks for the process's lifetime."""
+    browser = _RecordingBrowser()
+
+    async def exploding_close():
+        raise RuntimeError("renderer gone")
+
+    browser.page.close = exploding_close
+
+    with pytest.raises(RuntimeError):
+        async with playwright_open_page(browser):
+            pass
+
+    assert browser.context.closed