ttrpg-initiative-tracker/docs/TESTING.md

# Testing & Automation — Operating Guide

How to run tests, demos, audits, docker stack, and understand the test layers. For any LLM session picking up this repo.

## Test commands

```bash
npm run test:all        # shared + server (fast, ~2s) — pre-push gate
npm run shared:test     # pure turn logic (shared/turn.js)
npm run server:test     # ws adapter vs live backend
npm test                # CRA frontend (src/tests/, slow w/ scenario)
```

Pre-push hook (`.githooks/pre-push`) runs `npm run test:all`. Frontend not gated (slow). Skip: `git push --no-verify`.

Setup hook once per clone:
```bash
git config core.hooksPath .githooks
```

## Test suites

| Suite | Location | What | Count |
|---|---|---|---|
| Unit (turn logic) | `shared/tests/` | pure nextTurn, rotation, pause-add, dead-skip, reorder, round, invariant, dry | 90 |
| Integration (adapter vs backend) | `server/tests/` | ws adapter through live REST/WS | 24 |
| Characterization (UI) | `src/tests/` | locks current App.js behavior | 66 |
| ESM guard | `src/tests/StorageEsm.test.js` | no CJS in adapters | 4 |

Total: ~184. 1 known RED (BUG-4 HideHpToggle, backlog).

### Run one file / pattern

```bash
npm test --workspace shared -- --testPathPattern=round-rotation
npm run server:test -- tests/ws-reconnect
CI=true npx react-scripts test --watchAll=false --testPathPattern="DisplayView.drag-order"
```

Frontend uses `react-scripts test` (CRA). Always set `CI=true` + `--watchAll=false` for single runs.

## Test layers (important)

Two layers, both required:

- **Layer 1**: App vs firebase mock (`src/__mocks__/firebase/`). Proves adapter call shape. Never exercises ws adapter.
- **Layer 2**: ws adapter vs live backend (`server/tests/`). Proves translation + path identity.

Layer 1 alone misses adapter bugs (path mismatch, no-op players, ws event handler bugs). Layer 2 catches those.

## Test types

| Type | Purpose |
|---|---|
| **Unit** | pure logic, fast, no I/O. Locks single function behavior. |
| **Integration** | real backend per test (port 0 = OS picks free). Adapter translation verified. |
| **Characterization** | render App via mock, assert current UI behavior (buggy or not). NOT desired-state. |
| **Contract** | same spec run against every storage impl (memory, ws, firebase). Catches adapter drift. |
| **Scenario** | end-to-end flow through rendered App. `Combat.scenario.test.js` = 100 rounds, ~240s. Pre-existing crash (BUG-11). |

## TDD discipline

RED first → fix → GREEN. Never change functional code to pass tests for existing state without test driving it.

- Find bug → write failing test (RED)
- Fix code → test passes (GREEN)
- Log confirmed bug in `TODO.md`
- One bug at a time, commit with evidence

## Replay tool (demo, NOT unit test)

`scripts/replay-combat.js` — drives full combat via ws adapter (same contract as App) against live backend. UI updates in real-time if frontend running.

```bash
# start backend + frontend first
node scripts/replay-combat.js [rounds] [delayMs]
# defaults: 100 rounds, 200ms/step
# faster: 20 400 = 20 rounds, 400ms each

# against docker stack:
BACKEND_URL=http://127.0.0.1:8080 node scripts/replay-combat.js 20 400
```

Coverage per round: damage, heal, all 22 conditions, toggleActive, removeParticipant, addParticipant (reinforcements), updateParticipant, pause/resume, reorderParticipants, endEncounter. Revives dead each round to sustain count.

Output → log file, then analyze:

```bash
node scripts/replay-combat.js 20 400 > tmp/run.log 2>&1
node scripts/analyze-turns.js tmp/run.log
```

Exit 0 = clean. Reports skips, double-acts, order shifts.

### analyze-turns.js

Parses replay log. Detects:
- **real skips**: active participant not acted in a round
- **double-acts**: same participant twice in a round
- **order shifts**: turnOrderIds changed unexpectedly

Handles `[pointer X→Y wrap]` events (mutation-driven advance) and `[reorder A→before B]`. Logs `order=[Name:init,...]` + `parts=[Name:init,...]` per turn. Parser blind to DisplayView render (separate concern — FE test covers that).

Round marker: `--- round N starting ---` (top of loop, post-fix).

## Audit tools (NOT unit tests)

`tests/audit/` — exploratory, `Math.random`, non-deterministic. Manual run. NOT jest.

### audit-rotation.js
Pure turn.js simulation of replay op sequence. Detects rotation violations. Found BUG-1.

```bash
node tests/audit/audit-rotation.js
```

### audit-state.js
Runs pure turn.js combat. Audits 9 invariant classes per round:
1. rotation integrity (skip/dupe)
2. HP bounds (0 ≤ hp ≤ max, no NaN)
3. isActive consistency (dead = inactive)
4. turnOrder no dup ids
5. turnOrder ids all active
6. currentTurn valid + active
7. deathSave range (0-3, reset on revive)
8. removeParticipant orphans
9. undo support

```bash
node tests/audit/audit-state.js [rounds]   # default 100
```

Current state: 0 violations / 100 rounds (post BUG-1/2 fix).

## Docker stack

Single container: caddy (front, static + proxy) + node backend (internal :4001).

```bash
# build + run (from repo root)
docker compose -f docker/docker-compose.yml up --build -d
# → http://127.0.0.1:8080

# logs
docker compose -f docker/docker-compose.yml logs app --tail 20

# stop
docker compose -f docker/docker-compose.yml down

# rebuild after code change
docker compose -f docker/docker-compose.yml up -d --build
```

Files:
- `docker/Dockerfile` — build FE + BE, runtime caddy+node
- `docker/Caddyfile` — proxy /api + /ws to node, static SPA fallback
- `docker/entrypoint.sh` — runs node bg + caddy fg
- `docker/docker-compose.yml` — one `app` service, volume for sqlite

### Verify docker stack

```bash
# REST roundtrip
curl -s -X PUT http://127.0.0.1:8080/api/doc -H 'Content-Type: application/json' \
  -d '{"path":"campaigns/test","data":{"name":"X"}}' >/dev/null
curl -s "http://127.0.0.1:8080/api/doc?path=campaigns/test"

# WS subscribe + push (node one-liner, see scripts)
# Full combat: replay against docker
BACKEND_URL=http://127.0.0.1:8080 node scripts/replay-combat.js 20 400 > tmp/docker.log 2>&1
node scripts/analyze-turns.js tmp/docker.log
```

### Inspect docker sqlite

```bash
docker exec docker-app-1 sh -c 'node -e "
const db=require(\"better-sqlite3\")(\"/data/tracker.sqlite\");
const rows=db.prepare(\"SELECT path, substr(data,1,50) as d FROM docs\").all();
console.log(\"count=\"+rows.length);
rows.forEach(r=>console.log(r.path+\" => \"+r.d));
"'
```

## Dev servers (non-docker)

### Backend
```bash
npm run server:dev        # :4001, db: ./data/tracker.sqlite
# or:
DB_PATH=./data/tracker.sqlite PORT=4001 node server/index.js
curl http://127.0.0.1:4001/health   # → {"ok":true}
```

Never db in `/tmp` (wipe risk). Use `./data/` (gitignored) or docker volume.

### Frontend (ws mode)
```bash
REACT_APP_STORAGE=ws \
REACT_APP_BACKEND_URL=http://127.0.0.1:4001 \
REACT_APP_BACKEND_WS=ws://127.0.0.1:4001/ws \
BROWSER=none PORT=3999 \
npm start
```
→ http://127.0.0.1:3999/. Admin `/`, player `/display`.

Firebase mode (default): set `REACT_APP_FIREBASE_*` in `.env.local` (copy `env.example`).

## Storage modes

`STORAGE_MODE = getStorageMode()` reads `REACT_APP_STORAGE`:
- `firebase` (default) → real SDK
- `ws` → backend (docker/prod)
- `memory` → in-process (test seed)

All adapters ESM. Adapter contract: `src/storage/contract.js` — same spec vs memory/ws/firebase.

## Known RED / backlog

- BUG-4: HideHpToggle RED (setDoc→updateDoc, clobbers activeDisplay)
- BUG-10: deact+reactivate double-act
- BUG-11: Combat.scenario test crash
- BUG-13: reorder cross-pointer semantics
- BUG-14: addParticipant init-insert post-drag

See `TODO.md` for full list + status.

## Scratch

`scratch/` — gitignored throwaway. Repro scripts, exploration, debug. Not committed. Use freely, delete anytime.

## Status

See `docs/REWORK_PLAN.md` for milestones, `TODO.md` for bugs, `docs/DEVELOPMENT.md` for setup, `docs/GLOSSARY.md` for terms, `docs/ENCOUNTER_BUILDER.md` for DM interface.