generated from john/python-template
122 lines
5.2 KiB
Markdown
122 lines
5.2 KiB
Markdown
# 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.
|
|
|