Twungeon/docs/testing.md

Testing Twungeon

Automated gates

From a clean checkout:

npm install
npm run lint
npm run typecheck
npm test
npm run test:integration
npm run build

npm test covers deterministic domain rules and 500 generated floors. npm run test:integration covers the HTTP/session boundary and independent viewer authority. Tests use injected clocks, IDs, random rolls, and synthetic Twitch identities; they do not require credentials.

Local gameplay verification

1. Run npm run dev and open http://localhost:3000.
2. Confirm the exact dormant banner appears and no timer runs.
3. Use Local viewer login to spawn and bind a viewer.
4. Confirm 3 HP, 2 AP, no Guard, a ready heal, and a 25-second phase.
5. Exercise movement, invalid walls, Attack, Heal, and Pass. Invalid actions must not consume AP.
6. Open a second browser/private window with a different ID. Confirm both characters share the dungeon but each controller spends only its own AP.
7. Refresh during a phase. Confirm a snapshot restores the map/log and no command replays.
8. Run npm run build && npm start and repeat the smoke test against the built server.

The local-only endpoints /api/dev/spawn and /api/dev/redemption exist only while TWITCH_ENABLED is false.

Local video-overlay verification

The production viewer path is /extension. It is safe to open directly, but it waits for Twitch authorization when it is not inside Twitch. While running the synthetic local backend, open:

http://localhost:3000/extension?dev=1&debug=1

dev=1 exposes the existing Local viewer login inside the overlay so the same controller and API flow can be exercised without Twitch. debug=1 draws a cyan control-region boundary and a pink controller boundary. Both switches are accepted only on localhost, 127.0.0.1, or [::1], so the diagnostics cannot be enabled on the deployed Extension origin.

Verify at 1920×1080, 1280×720, and a narrower or 4:3 viewport:

• the document and empty overlay canvas remain transparent;
• controls stay within the upper-left debug boundary and remain readable;
• the dungeon, log, branding, and status tiles are absent from /extension;
• only buttons (and the local-only login form) accept pointer events;
• Up, Down, Left, Right, Attack, Heal, and Pass reach the same backend routes;
• missing character, dead character, non-player phase, and zero-AP states still disable the controls; and
• loading / still presents the full local game and controller.

Remove the query string for the production-shaped local view. Twitch-hosted testing still must cover identity sharing, player ownership, theater mode, fullscreen, embeds, ads/pauses, and Twitch player-control safe zones.

Live-channel campaign

After completing docs/twitch-setup.md, use two follower accounts and one non-follower account. Capture redacted evidence for:

• eligible, ineligible, and duplicate !spawn attempts;
• matching and mismatched Extension identities;
• independent commands from two viewers;
• phase expiry and AutoGuard while one viewer is disconnected;
• death and a configured Channel Points reward redemption from the same user;
• escape with the Goblin alive, floor revival, and a total-party wipe;
• refresh/reconnect during a phase and transition; and
• repeated floors and a short soak session.

Do not record tokens, JWTs, secrets, or complete authorization headers. Use the acceptance matrix in Twungeon_MVP_Acceptance_Test_and_Build_Checklist.md for AT-001 through AT-033 evidence. Automated passing tests do not substitute for the clean-operator, live Twitch, first-time-viewer, or concept-validation gates.

Fault injection

Test each failure separately: expired Extension JWT, wrong channel claim, unlinked identity, invalid broadcaster token, missing follower scope, Twitch chat disconnect, wrong/duplicate Channel Points redemption, WebSocket interruption, and stale run/floor/phase command. Expected behavior is a stable rejection or a fresh snapshot without partial game-state mutation.