Testing¶

Tests require no Ollama, API key, or separately running FastAPI server. Backend tests use the in-process TestClient and mock outgoing HTTP with pookx. Playwright runs the real browser and Vite app with MSW handlers generated from the OpenAPI contract by Orval. Install dependencies and Chromium before running offline.

flowchart TB
    subgraph E2E["End to end: Playwright"]
        direction LR
        E["Real browser and Vite app,<br/>Orval-generated MSW API handlers"]
    end
    subgraph FE["Frontend unit: Vitest + Testing Library"]
        direction LR
        F["Components, pages, hooks,<br/>fake EventSource"]
    end
    subgraph BE["Backend: pytest"]
        direction LR
        B["API, SSE sequence, fetcher,<br/>agent, usage, cancellation"]
    end
    E2E --> FE --> BE

Commands¶

Both backend and frontend enforce 90% coverage gates. The test output reports current coverage. After changing the API, run just openapi to refresh the checked-in schema and Orval client. CI's schema check only compares FastAPI's current schema with the checked-in OpenAPI file; it leaves the schema and generated client untouched.

Mocking the internet with pookx¶

The backend uses httpx2 and the tests mock it with pookx, a maintained fork of pook that supports httpx2. It installs under the module name pook, so the tests say import pook; a guard test checks that pookx (not the original) is what is installed.

# conftest.py: an autouse fixture. No test can reach the internet.
with pook.use():
    pook.disable_network()               # an unmocked URL raises PookNoMatches
    pook.enable_network("testserver")    # ...except Starlette's TestClient talking to the app
    yield

# a test: first attempt times out, the retry works, and we can assert both happened
pook.get(URL).error(httpx2.ReadTimeout("slow"))
second = pook.get(URL)
second.reply(200).body(RSS)
...
assert second.isdone()

Because the app's own httpx2.AsyncClient is intercepted, API tests exercise the real client, real retries and real headers; only the network is fake.

How the hard parts are tested¶

CI¶

flowchart LR
    PR([push or PR]) --> L[lint<br/>prek]
    PR --> C[api-contract<br/>stream and diff schema]
    PR --> B[backend<br/>pytest, cov 90]
    PR --> F[frontend<br/>tsc, build, vitest, cov 90]
    PR --> E[e2e<br/>Playwright]
    PR --> D[docs<br/>zensical --strict]

The api-contract job streams the current FastAPI schema into diff and fails if it differs from the checked-in OpenAPI file. It does not rewrite the schema or regenerate the Orval client.

curl -N localhost:8000/api/v1/stocks/AAPL/summary/stream