109 lines
5.3 KiB
Markdown
109 lines
5.3 KiB
Markdown
# Testing Patterns
|
|
|
|
**Analysis Date:** 2026-10-21
|
|
|
|
> **Status: No tests exist yet.** There are no test files, no test runner configuration,
|
|
> no package manifest, and no CI pipeline in this repository. This document records what
|
|
> is verifiably absent today and prescribes the testing conventions the project should
|
|
> adopt when real implementation code begins, based on the stack targets declared in
|
|
> `IDEAS.md`.
|
|
|
|
## Test Framework
|
|
|
|
**Runner:**
|
|
- None installed. No `package.json`, no `vitest.config.*` / `jest.config.*` /
|
|
`playwright.config.*` exists anywhere in the repository.
|
|
- Run commands: Not applicable — nothing to run.
|
|
|
|
**Assertion Library:** None.
|
|
|
|
**Application code under test:** None. The only executable artifacts are inline scripts
|
|
inside the generated mockup files (`stitch_minimalist_route_navigator/*/code.html`),
|
|
which are demonstration-only and not structured for testing.
|
|
|
|
## Test File Organization
|
|
|
|
**Current state:** Not established. No `tests/`, `__tests__/`, `*.test.*`, or `*.spec.*`
|
|
files exist.
|
|
|
|
**Prescribed convention (for future code):**
|
|
- Place tests adjacent to the code they cover (`*.test.ts` next to the module) once a
|
|
source directory exists.
|
|
- There are no `--paths` subtrees pinned yet; the whole repo is effectively design docs +
|
|
mockups (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/`).
|
|
|
|
## Recommended Stack Mapping (targets from `IDEAS.md`)
|
|
|
|
The planned architecture in `IDEAS.md:55-73` implies these test layers when implemented:
|
|
|
|
| Planned component | Where it's described | Suggested test approach |
|
|
|---|---|---|
|
|
| Telegram bot commands (`/report`, `/navigate`, `/accident`) | `IDEAS.md:19-27`, `DESIGN.md:67-73` | Unit tests on command parsing/state machines; integration tests against a Telegram Bot API test token or a stubbed client |
|
|
| OSRM route fetch + traffic weighting | `IDEAS.md:63`, `DESIGN.md:71` | Contract tests against a recorded/stubbed OSRM response; regenerate fixtures when branching logic changes |
|
|
| Neon Postgres + PostGIS report storage & nearby broadcast | `IDEAS.md:61`, `DESIGN.md:69` | Integration tests against an ephemeral Postgres + PostGIS extension (e.g., testcontainers-style setup in CI) |
|
|
| Map snapshot generation (Maptiler tiles, R2 storage) | `IDEAS.md:64-69` | Golden-image tests only if snapshots are rendered locally; otherwise HTTP-mock the tile/R2 clients |
|
|
| RabbitMQ queue consumers | `IDEAS.md:67` | Unit-test handlers with in-memory queue; defer broker-level tests to a single CI integration job |
|
|
|
|
## Mocking
|
|
|
|
**Framework:** None (no tooling yet).
|
|
|
|
**Prescribed patterns for future code:**
|
|
- Mock only true boundaries: Telegram Bot API client, OSRM HTTP client, Maptiler tile
|
|
fetcher, RabbitMQ producer, R2 uploader. Do **not** mock internal handlers, parsers,
|
|
or design-token usage.
|
|
- Prefer injectable clients over module-level singletons so tests can pass fakes;
|
|
when the bot entry point is created, keep a thin wiring layer and a pure core.
|
|
|
|
## Fixtures and Factories
|
|
|
|
**Test Data:** None exists.
|
|
|
|
**Prescribed convention:**
|
|
- Create a `fixtures/` (or `test/fixtures/`) directory for recorded OSRM responses,
|
|
Telegram update payloads, and tile responses. Store raw payloads, not hand-typed
|
|
paraphrases, so contract drift is catchable.
|
|
- Use small factory functions (e.g., `makeIncidentReport(overrides)`) over large literal
|
|
blocks once domain types exist.
|
|
|
|
## Coverage
|
|
|
|
**Requirements:** None enforced (no runner, therefore no coverage tooling).
|
|
|
|
**View Coverage:** Not applicable until a runner is configured; when it is, wire coverage
|
|
into the runner config rather than a separate tool.
|
|
|
|
## Manual Verification (what exists today)
|
|
|
|
Since there is no automated checking, the only "testing" currently possible is manual:
|
|
|
|
- **Visual review:** each mockup has a rendered screenshot pair
|
|
(`stitch_minimalist_route_navigator/<screen>/code.html` + `<screen>/screen.png`) —
|
|
four screens: `active_route_guidance`, `navigate_map_overview`,
|
|
`community_incident_reporter`, `telegram_live_traffic_feed`. Compare `code.html`
|
|
rendering against `screen.png` after any token or config edit (the inline
|
|
`tailwind.config` block is duplicated across all four files and must stay in sync).
|
|
- **Interactivity smoke check:** mockups contain small inline JS handlers — e.g.,
|
|
`reportHazardModal`, `confirmDispatch`, `triggerQuickDispatch`
|
|
(`stitch_minimalist_route_navigator/navigate_map_overview/code.html:288-314`) and
|
|
`insertCommand`
|
|
(`stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html:235`).
|
|
These are demo-only; verifying them means opening the HTML in a browser and clicking
|
|
through buttons. Do not invest in automated tests for these scripts; they will be
|
|
replaced by real implementation code.
|
|
|
|
## Gaps That Should Become Early Phases
|
|
|
|
1. **Test scaffold phase:** first real-code phase should add a package manifest with a
|
|
test runner + lint config in the same commit, before business logic.
|
|
2. **CI job:** once a runner exists, add a minimal pipeline (install → lint → test) — no
|
|
CI config exists today (`.github/workflows/`, etc. absent).
|
|
3. **Design-token regression:** consider a lightweight check that the four `code.html`
|
|
`tailwind.config` blocks match the token table in
|
|
`stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (a snapshot/diff test is
|
|
sufficient; heavy visual-diff tooling is disproportionate for a mockup repo).
|
|
|
|
---
|
|
|
|
*Testing analysis: 2026-10-21*
|