Gameplay Verification

Gameplay changes are checked by a shared verification suite instead of one-off checks. Run the full gate with one command after the local game is already started:

./scripts/game.sh start
npm run gameplay:verify
./scripts/game.sh stop

The command probes http://localhost:3000/health and http://localhost:5173/, runs the focused Vitest suite at src/game/verification/gameplay-verification-suite.test.ts, and writes Markdown result files for that run into your checkout. The focused suite also runs in CI as part of npm run test:run; the runtime probes need the local game and only run through this command.

For local runtime smoke, use the full start/verify/browser/stop sequence:

./scripts/game.sh start
./scripts/game.sh status
npm run gameplay:verify
# Browser verification at http://localhost:5173 when Browser tooling is available
./scripts/game.sh stop

The gameplay result file separates current-run suite defects from gate assignments. Current-run defects cause the command to exit non-zero. Assigned follow-up defects record known gaps with rationale, reproduction steps, and acceptance criteria.

What A Full Gameplay Check Covers

A full check of normal gameplay consists of: local runtime start and status, npm test, client lint, typecheck, npm run gameplay:verify, the docs build, a live browser check at http://localhost:5173, and a final runtime stop and status.

Production Readiness Sequence

Use this sequence when a change touches gameplay, websocket contracts, or Table V2 behavior:

npm run typecheck
npm run lint
npm test -- src/game/verification/gameplay-verification-suite.test.ts
npm test -- src/game/integration/fixed-limit-stud-flow.test.ts src/game/integration/betting-structure-variations.test.ts
npm test
./scripts/game.sh start
./scripts/game.sh status
curl -sS http://localhost:3000/health/live
curl -sS http://localhost:3000/health
npm run gameplay:verify
# Browser verification at http://localhost:5173
./scripts/game.sh stop

The focused test commands above are the stable variant-oriented checks. Add more targeted commands only when a change introduces a new reusable verification surface.

Core Files

• src/game/verification/types.ts: stable scenario, snapshot, Table V2 observation, and defect types.
• src/game/verification/seeded-deck.ts: deterministic variant-aware deck builder.
• src/game/verification/bot-script.ts: scripted bot action plans for fold, call, check, bet, raise, and all-in paths.
• src/game/verification/invariants.ts: server-side invariant assertions for cards, street/action order, visibility, pot math, rake, winners, and cleanup.
• src/game/verification/browser-table-v2.ts: DOM-level Table V2 and animation/timing assertions.
• src/game/verification/edge-case-certification.ts: deterministic certification matrix for all-in runouts, side pots, split/tie/odd-chip results, no-low/scoop/no-flop-no-drop, deck/card behavior, winner/reveal behavior, stale/duplicate/resync handling, cleanup, and the CI/local-runtime gate.
• src/game/verification/scenarios.ts: bundled fixtures and templates for later variant stories.
• src/game/verification/variant-simulation.ts: deterministic end-to-end simulations that drive real Table hands, translate game events through the WebSocket contract, and assert shared client-state transitions.
• src/game/verification/tournament-compliance.ts: tournament compliance matrix for mixed-game button policy, table balancing/breaking, dead button, heads-up transition, hand-for-hand, simultaneous eliminations, entry flows, absence, showdown, deck procedure, Stud history labels, admin floor audit, Table V2, Browser, and animation/timing release gates.
• src/game/verification/rules.ts: accepted behavior notes for disputed rules.
• src/game/verification/report.ts: categorized defect report rendering.
• src/game/verification/gate-analysis.ts: focus-area analysis and follow-up defect assignments.

Adding A Scenario

1. Build a known deck with buildSeededDeck(variant, seed, stackedTop).
2. Define scripted human and bot actions in street order.
3. Add one or more VerificationSnapshot objects from engine/WebSocket/TableManager state.
4. Set expectedActionOrder, expectedStreetOrder, expected pots, and expected winners.
5. Call verifyGameplayScenario(scenario) in the focused test or your own test.
6. For Table V2, collect desktop and mobile TableV2Observation objects and call assertTableV2Viewports(expected, observations).

Adding An End-To-End Variant Simulation

Use src/game/verification/variant-simulation.ts when you need a completed hand through the engine/Table/WebSocket/client-state path instead of a static fixture.

1. Add a VariantSimulationSpec entry to END_TO_END_VARIANT_SIMULATION_SPECS.
2. Keep riggedDeck in the exact order the local dealing pattern consumes cards; this engine deals all hole cards to one player before moving to the next player.
3. Prefer mode: 'all-in-runout' for completed-hand proofs and add a focused auxiliary spec only when a rule like no-flop-no-drop cannot happen in an all-in hand.
4. Run npm test -- src/game/verification/gameplay-verification-suite.test.ts.
5. Run ./scripts/game.sh start, then npm run gameplay:verify, then ./scripts/game.sh stop.

Browser Evidence

For UI and gameplay changes, start the game with ./scripts/game.sh start, check the table in a browser at http://localhost:5173, and record structured observations or screenshots. The suite’s Table V2 helper expects observations for:

• seats, dealer/blind/bring-in markers, active player, and winner state;
• face-down/face-up card counts, community cards, and Stud up-card visibility;
• betting controls, action prompts, pot display, winner banners, and Hi-Lo display;
• dealing, card flip, collect, payout, winner highlight, and cleanup animation events with bounded timing.

Browser Availability Rules

• Table V2, lobby, gameplay, animation, and other visual changes need a browser check.
• A visual change cannot be signed off without a browser, unless equivalent browser automation is used and recorded.
• Backend-only changes can skip the browser check only when they do not affect anything visual or gameplay-related.
• Runtime socket automation should wait for connection_established before emitting gameplay events; raw Socket.IO connect is too early for authenticated gameplay handlers.

The deterministic edge-case and tournament compliance matrices are part of npm run gameplay:verify, so there is no separate runner for them. The full local gate is:

./scripts/game.sh start
./scripts/game.sh status
npm run gameplay:verify
# Browser verification at http://localhost:5173
./scripts/game.sh stop

Use a browser for live Table V2, lobby, tournament status, and timing checks.

Variant Expectations

The suite encodes the repo’s current accepted behavior:

• Hold’em: best 5 of 7, private hole cards until showdown, odd chips first clockwise from the button.
• Omaha/Omaha Hi-Lo: exactly 2 hole cards and 3 board cards for high and low; Hi-Lo uses 8-or-better.
• Short Deck: 36-card deck, 2-5 removed, ante/button blind, repo default ranking notes in rules.ts.
• Stud/Stud Hi-Lo: third street is 2 down plus 1 up, fourth-sixth up, seventh down; bring-in is lowest door card with suit tie.
• Mixed Game: variant changes only at hand boundaries and must record active/next game metadata.

New gameplay and UI work should extend these helpers and reports rather than adding parallel verification harnesses.