# 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.