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

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.
CI job: once a runner exists, add a minimal pipeline (install → lint → test) — no CI config exists today (.github/workflows/, etc. absent).
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

5.3 KiB Raw Blame History