# 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*