docs(01-design-tokens-rams-foundation): create phase plan (4 plans, 3 waves)
This commit is contained in:
araharah-planner
@@ -0,0 +1,108 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user