# TEST KNOWLEDGE BASE

## OVERVIEW
Executable spec for repo behavior. Coverage is strongest around auth, Prometheus client behavior, DuckDB SQL safety, and the in-memory stores.

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Auth service flow | `test_auth_forwarding.py`, `test_auth.py`, `test_token_cache.py` | Largest behavior surface; all patch `src.services.auth.*` |
| Prometheus client limits | `test_prometheus.py` | Time-series/data-point truncation rules |
| Delta SQL and secret setup | `test_duckdb_delta.py`, `test_read_delta.py` | Safe-query and cloud secret expectations; auto-resolves vendor/region via `get_cluster_info` |
| Cache/store behavior | `test_token_cache.py`, `test_cloud_access_store.py`, `test_gcp_parquet.py` | Per-provider auth cache, per-cluster metrics URL cache, and GCP parquet partition cache semantics |
| Observability resolve | `test_observability_resolve.py` | Patches at import site: `src.services.observability_resolve.*`; includes `get_cluster_info` tests |
| Pure helper behavior | `test_redaction.py`, `test_tool_response.py` | Small fast unit tests |
| Real MCP startup validation | `test_mcp_stdio_integration.py` | Starts the real stdio server and calls tools over FastMCP client transport |
| Example client only | `test_client.py` | HTTP-targeted example for manual checks against `fastmcp run server.py:mcp` |

## CONVENTIONS
- Patch where a dependency is imported, not where it originally lives.
- Use `AsyncMock` for async clients and `MagicMock` for sync collaborators.
- Reset module-level stores with `autouse` fixtures; no shared `conftest.py` yet.
- For DuckDB tests, inspect `mock_conn.execute.call_args_list` instead of asserting abstract behavior only.
- For HTTP tests, build real `httpx.Response` objects and return them from mocks.
- For MCP integration tests, prefer a real started server via FastMCP stdio/http transports over mocked tool wrappers.

## ANTI-PATTERNS
- Do not add tests that depend on prior store state.
- Do not treat mocked tool-wrapper tests as MCP validation; start the real server and call tools through a real FastMCP client transport.
- Do not treat `test_client.py` as proof that stdio startup is exercised; it targets `http://localhost:8000/mcp` and is for manual HTTP checks.
- Do not patch the wrong import site; existing tests explicitly call this out.
- Do not overfit exact full error strings when substring assertions are enough.

## COVERAGE HOTSPOTS
- `src/services/auth.py`
- `src/services/duckdb_delta.py`
- `src/services/prometheus.py`
- `src/services/observability_resolve.py`