brain-of-reese/.agents/phases/todo/122_image_documents/06_image_tests.md

Task 06 — Image tests: unit + integration + isolated E2E

Phase: 122_image_documents · Source: TODO.md:6 — "Need to support images …"

Objective

Pin the whole image-document contract: the off-by-default byte-identity, the ingest/description/serve pipeline, the RAG display, and the end-to-end user path (upload → Sources → viewer → chat) as an isolated Playwright suite.

Work

1. tests/unit/test_image_documents.py (new) — consolidates the per-task unit cases (the tasks ship code; this task ships the full pin):
   • settings: defaults (images False, six-extension frozenset, dir default), env overrides, case-insensitive parse (task 01);
   • the walk: image accepted iff images=True; off → the file is ignored (the default byte-identity);
   • _index_file image branch: digest over BYTES, copy to image_dir, is_image/image_path set, changed-image stale-copy delete, prune guard (off → survives; on + gone → pruned + copy deleted), images_failed in the log line (task 02);
   • describe_image: mock-client prompt shape (multimodal parts, chat model), cap, None on error/empty, the importer skip path (no row, no orphan, counter, warning) and the success path (content == summary == description; embedding called with the description only) (task 03);
   • the ext→mime map (task 04);
   • the source-frame image_url helper (present/absent) + the agent read marker + house-style frontend assertions (viewer img + alt + fallback; sources thumbnail fallback; chat sources inline image + alt) (task 05).
2. tests/integration/test_docs_api.py (extend, task 04's cases) — the image route (200 + Content-Type per ext; 404 text doc / missing id / missing file), the content endpoint's is_image/image_url omission rules; tests/integration/test_chat_api.py (extend, task 05's case) — the SSE image_url frame; tests/integration/ (new file test_image_import.py or the existing import test file — follow whichever exists) — import_sources end-to-end: images=True + mock vision → the fixture PNG becomes a doc (description content, is_summary chunk, one content chunk); images=False → ignored + a pre-seeded image doc survives prune; a failing mock → images_failed == 1, no row, other docs indexed.
   • Fixtures: a tiny valid PNG (a few bytes, generated in-test or a committed fixture under tests/ — check the existing fixture conventions), a mock vision client (the existing mock-LLM test patterns in tests/).
3. tests/e2e/test_image_documents.py (new — isolated run per AGENTS.md §4: uv run pytest tests/e2e/test_image_documents.py -v --no-cov). The suite's app instance runs with BOR_IMAGES=true (env override in the E2E fixture — the conftest.py pattern for per-suite app env):
   • upload a fixture PNG (the Sources-page upload flow or page.request against the upload endpoint, then trigger the sync through the UI as the Sources page does);
   • the Sources page lists the image doc (thumbnail or icon fallback);
   • open the document viewer → the image renders + the description text below it;
   • ask a question the mock LLM grounds on the image doc (the existing mock-LLM grounding pattern) → the chat's sources block shows the inline image with its caption;
   • negative: with the DEFAULT env (BOR_IMAGES unset/false), the same upload produces NO image doc (the default-off contract).
4. Run the full gate: uv run pytest, uv run pytest --cov=app --cov-report=term-missing (TOTAL >90%), the isolated E2E file, uv run ruff check . && uv run pyright.

Testing & Quality

• This task IS the phase's test suite (see Work).
• Coverage: >90% on app/ — the phase's app/ surface (config, importer, summarizer, docs API, chat frames, agent marker) is fully exercised.

Completion Criteria

• All test artifacts exist and pass; the isolated E2E file passes standalone.
• The default-off byte-identity is asserted (unit + integration + the E2E negative case).
• uv run pytest --cov=app TOTAL >90%; lint + types clean.