transcription/docs/tests.md

Testing

The greenfield test structure mirrors the source tree at a high level and keeps the first pass shallow and easy to extend.

Source To Test Map

• src/handwriting/bootstrap.py, src/handwriting/config.py, src/handwriting/logging_buffer.py, src/handwriting/main.py -> tests/handwriting/test_core.py
• src/handwriting/ai/** -> tests/handwriting/ai/
• src/handwriting/api/** -> tests/handwriting/api/
• src/handwriting/db/** -> tests/handwriting/db/
• src/handwriting/services/** -> tests/handwriting/services/
• src/handwriting/ui/components/** and src/handwriting/ui/pages/** -> tests/handwriting/ui/
• Shared test helpers and fixtures -> tests/conftest.py plus subtree conftest.py files where needed

Major Sections

• tests/handwriting/test_core.py: bootstrap, config, logging, and entrypoint coverage.
• tests/handwriting/ai/: AI contracts, runtime orchestration, graph wiring, and node behavior.
• tests/handwriting/api/: HTTP routes and request/response contract checks.
• tests/handwriting/db/: session setup, models, and repositories.
• tests/handwriting/services/: service-layer orchestration and domain logic.
• tests/handwriting/ui/: NiceGUI components and pages.
• tests/conftest.py: shared lightweight fixtures and deterministic defaults.
• tests/handwriting/**/conftest.py: subtree-specific fixtures only where a package needs its own setup.

Implemented In This Pass (Core + DB)

Created Files

• tests/handwriting/test_core.py
• tests/handwriting/conftest.py
• tests/handwriting/db/conftest.py
• tests/handwriting/db/test_session.py
• tests/handwriting/db/test_models.py
• tests/handwriting/db/test_job_repo.py
• tests/handwriting/db/test_service_job.py

Updated Files

• tests/conftest.py: added shared settings_factory fixture.
• pyproject.toml: registered strict markers and async pytest mode.

Marker Taxonomy

• unit: fast deterministic unit tests.
• db: database-backed tests against PostgreSQL-backed fixtures.
• document: document-store tests for MongoDB-backed persistence behavior.
• integration: cross-layer integration tests (reserved for expanded next pass).
• smoke: high-value end-to-end surface checks.
• slow: long-running tests.
• external: tests that require external services/credentials.

Fixture Ownership

• tests/conftest.py: global lightweight fixtures used across all sections.
• tests/handwriting/conftest.py: core package-level environment fixtures.
• tests/handwriting/db/conftest.py:
  • PostgreSQL fixtures (postgres_engine, db_session) for default data-layer tests.
  • optional MongoDB fixture (mongo_client) gated by PYTEST_MONGO_URL for document-store integration checks.

Initial Coverage Added

• tests/handwriting/test_core.py
  • settings identity and URL validation behavior.
  • logging UI buffer wiring.
  • buffer incremental read behavior.
  • minimal main module export smoke check.
• tests/handwriting/db/test_session.py
  • session scope, factory, and engine helper behavior.
• tests/handwriting/db/test_models.py
  • model defaults and enum/value shape checks.
• tests/handwriting/db/test_job_repo.py
  • repository list/detail happy path and not-found/missing-image edges.
• tests/handwriting/db/test_service_job.py
  • job creation happy path and validation errors for unsupported type / oversized payload.

Run Commands

• Collect only: uv run pytest --collect-only -q
• Fast local path: uv run pytest -m unit -q
• DB path: uv run pytest -m "db or integration" -q
• Full path: uv run pytest -q

Current Verification Snapshot

• uv run pytest --collect-only -q -> 19 tests collected.
• uv run pytest -m unit -q -> 11 passed, 8 deselected.
• uv run pytest -m "db or integration" -q -> 7 passed, 12 deselected.

Jobs Page Diagnostics

To investigate cases where /jobs renders without a table, the scaffold now includes focused service and UI coverage:

• tests/handwriting/services/test_ui_jobs.py
  • verifies the list_jobs_for_ui contract used by the page.
  • includes the join edge case where a job with a missing image relation does not appear in list output.
• tests/handwriting/ui/test_jobs_page_runtime.py
  • verifies runtime guard behavior for missing app state (settings, session_factory).
• tests/handwriting/ui/test_jobs_page_rendering.py
  • includes a detector test for initial render behavior on /jobs.
  • verifies empty, table, and error rendering branches after refresh.
• tests/handwriting/ui/test_jobs_page_smoke.py
  • confirms route registration and refresh button wiring.

Targeted commands:

• uv run pytest tests/handwriting/ui/test_jobs_page_rendering.py -q
• uv run pytest -m "unit or integration" -q
• uv run pytest -m smoke -k jobs -q
• HANDWRITING_E2E_BASE_URL=http://localhost uv run pytest tests/handwriting/ui/test_jobs_page_browser_smoke.py -q

Next Pass

The next pass can expand each major section into markers, fixtures, and test case placeholders.

Glossary

• Contract mapping: Verifying that adapter input/output shapes match expected boundaries.
• Document-store tests: Tests that validate behavior against document-oriented persistence components.
• Marker taxonomy: The test marker classification scheme used to select test slices.