From 7069f15b9538403a2ae753f879956f5be48e0191 Mon Sep 17 00:00:00 2001
From: Woody <woody.ck.tse@gmail.com>
Date: Mon, 27 Apr 2026 10:55:43 +0800
Subject: [PATCH] docs: update testing rules to integration-first approach

- Prefer integration tests (TestClient + real DB) over mocked unit tests
- Never mock database or internal services; only mock external APIs (LLM/ASR)
- Rename 'unit tests' to 'integration tests' throughout for consistency
---
 AGENTS.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 95acee1..044ebe1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,11 +125,13 @@ test_phase<N>_<module_or_feature>.py
 - `test_integration_phase1.py` — End-to-end text → RAG → answer
 - `test_integration_phase2.py` — End-to-end video → ASR → RAG → answer
 
-**Rules**:
-- Use `pytest` + `pytest-asyncio` for async tests
-- Mock all external LLM/ASR calls (do not hit live APIs in tests)
-- Use `tmp_path` fixture for ChromaDB test instances
-- Each test file must have a module-level docstring describing coverage
+**Testing Rules (Python Backend)**:
+- **Prefer integration tests** over unit tests with mocks for all backend features and API routes.
+- Use real application via `TestClient` (FastAPI). Never mock the database or internal services.
+- Use existing test database fixtures and `conftest.py`. Only mock truly external third-party APIs (LLM, ASR).
+- Match the exact style and imports of existing tests in the `tests/` directory.
+- Always run `pytest` after writing tests and iterate until they pass against the real system.
+- Each test file must have a module-level docstring describing coverage.
 
 ## SUB-PHASE DEVELOPMENT
 
@@ -154,7 +156,7 @@ Every sub-phase follows **test-driven delivery**:
 
 1. **Write test first** — Before writing implementation code, write the test that defines "done"
 2. **Implement** — Write the minimum code to make the test pass
-3. **Run test** — Verify test passes (both unit and acceptance where applicable)
+3. **Run test** — Verify test passes (both integration and acceptance where applicable)
 4. **Commit** — Only commit after tests pass. Never commit broken tests.
 5. **Next sub-phase** — Only start next sub-phase after current is committed
 
@@ -174,7 +176,7 @@ Each sub-phase plan (stored in `.plans/`) must include:
 
 ### Acceptance Testing Rules
 
-**Unit tests** (`test_phase*.py`) — mocked, fast, CI-safe
+**Integration tests** (`test_phase*.py`) — TestClient + real DB, only external APIs mocked, CI-safe
 **Acceptance tests** (`test_acceptance_*.py`) — real environment, actual LLM/ASR calls
 
 **Acceptance test requirements**:
@@ -206,8 +208,8 @@ def test_query_with_real_llm():
 ```
 
 **Sub-phase completion checklist**:
-- [ ] All unit tests written BEFORE implementation
-- [ ] All unit tests pass (`pytest app/test/test_phase*.py -v`)
+- [ ] All integration tests written BEFORE implementation
+- [ ] All integration tests pass (`pytest app/test/test_phase*.py -v`)
 - [ ] All acceptance tests pass (`pytest app/test/acceptance/ -v -m acceptance`)
 - [ ] Code reviewed (self or peer)
 - [ ] Sub-phase plan marked complete in `.plans/`
@@ -219,7 +221,7 @@ def test_query_with_real_llm():
 backend:  uvicorn app.main:app --reload --port 8000
 frontend: npm run dev
 
-# Unit tests (mocked, CI-safe)
+# Integration tests (TestClient, real DB, only external APIs mocked)
 backend:  cd backend && pytest app/test/test_phase*.py -v
 
 # Acceptance tests (real LLM/ASR/ChromaDB)