tests/codemap.md

backend/tests/

Responsibility

Python regression and contract tests for backend routes, services, RAG retrieval/ingestion, and startup behavior.

Design

• Pytest test modules use focused test functions/classes and unittest.mock fixtures to isolate external boundaries.
• conftest.py provides Firebase auth/Firebase Admin test doubles so tests do not require production credentials, plus an isolated-auth fixture that binds student/teacher claims per test module (suite-wide auth mocks previously leaked teacher claims into student cases — always apply the isolated fixture to auth-sensitive modules).
• Route tests use FastAPI TestClient and main.app; unit tests import service/RAG symbols directly.
• Representative coverage: test_rag_pipeline.py, test_160_rag_lesson_retrieval.py, test_rag_scoped_retrieval.py (bounded windows, server-side filters, dedupe, chat gating), test_chat_context_regression.py (chat prompt layering, history budget, sanitized quiz output), test_llm_text.py, test_video_routes.py, test_admin_model_routes.py, test_wri_service.py, and test_memory_health.py.
• Auth/authorization regression coverage: test_role_policies_regression.py (matrix over ROLE_POLICIES, expectations in role_policy_expectations.py), test_diagnostic_iar_states.py, test_intervention_pipeline.py, test_quiz_battle_api.py, test_quiz_generation_regression.py, test_rag_regression.py, test_risk_wri_regression.py — all assert 403-first rejection for unauthorized roles.

Flow

• Test setup → conftest.py patches Firebase boundaries → imports route/service modules or constructs TestClient(app).
• Requests exercise route → handler → mocked or real-in-process service contracts; assertions cover status, response shape, authorization, and persistence behavior.
• RAG tests call retrieval/parsing helpers directly and validate filters, exact-file behavior, lesson context, and ingestion transformations.
• Service tests validate deterministic logic such as WRI, email configuration, model profiles, caching, and memory health.

Integration

• Tests mirror /api/... route → handler → service → Firestore/Claude/RAG Chroma boundaries while mocking external dependencies as appropriate.
• Test modules are consumers of backend/main.py, backend/routes/, backend/services/, and backend/rag/; they do not define production APIs.