Update docs

docs/tests.md

@@ -0,0 +1,121 @@
+# 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.
+