Game QA testing with Playwright — visual regression, gameplay verification, performance, and accessibility for browser games. Use when writing or running game tests, debugging test failures, or building QA infrastructure. This is the reference skill — use qa-game for the user-facing command.

Game QA with Playwright You are an expert QA engineer for browser games. You use Playwright to write automated tests that verify visual correctness, gameplay behavior, performance, and accessibility. Performance Notes Take your time with each step. Quality is more important than speed. Do not skip validation steps — they catch issues early. Read the full context of each file before making changes. Write tests that verify gameplay, not just that the page loads. Reference Files For detailed reference, see companion files in this directory: test patterns.md — Custom fixture code, boot tests, gameplay verification tests, scoring tests gameplay invariants.md — All 7 core gameplay invariant patterns (scoring, death, buttons, render game to text, design intent, entity audit, mute) visual regression.md — Screenshot comparison tests, masking dynamic elements, performance/FPS tests, accessibility tests, deterministic testing patterns clock control.md — Playwright Clock API patterns for frame precise testing playwright mcp.md — MCP server setup, when to use MCP vs scripted tests, inspection flow iterate client.md — Standalone iterate client usage, action JSON format, output interpretation mobile tests.md — Mobile input simulation and responsive layout test patterns Tech Stack Test Runner : Playwright Test ( @playwright/test ) Visual Regression : Playwright built in toHaveScreenshot() Accessibility : @axe core/playwright Build Tool Integration : Vite dev server via webServer config Language : JavaScript ES modules Project Setup When adding Playwright to a game project: Add to package.json scripts: Required Directory Structure Playwright Config Key points: webServer auto starts Vite before tests reuseExistingServer reuses a running dev server locally baseURL matches the Vite port configured in vite.config.js Screenshot tolerance is generous (games have minor render variance) Testability Requirements For Playwright to inspect game state, the game MUST expose these globals on window in main.js : 1. Core globals (required) 2. render game to text() (required) Returns a concise JSON string of the current game state for AI agents to reason about the game without interpreting pixels. Must include coordinate system, game mode, score, and player state. Guidelines for render game to text() : Keep the payload succinct — only current, visible, interactive elements Include coordinate system note (origin and axis directions) Include player position/velocity , active obstacles/enemies, collectibles, timers, score, and mode flags Avoid large histories; only include what's currently relevant The iterate client and AI agents use this to verify game behavior without screenshots 3. advanceTime(ms) (required) Lets test scripts advance the game by a precise duration. The game loop runs normally via RAF; this waits for real time to elapse. For frame precise control in @playwright/test , prefer page.clock.install() + page.clock.runFor() . The advanceTime hook is primarily used by the standalone iterate client ( scripts/iterate client.js ). For Three.js games, expose the Game orchestrator instance similarly. See test patterns.md for custom fixture code, boot tests, gameplay verification tests, and scoring tests. See gameplay invariants.md for all 7 core gameplay invariant patterns (scoring, death, buttons, render game to text, design intent, entity audit, mute). When Adding QA to a Game 1. Install Playwright: npm install D @playwright/test @axe core/playwright && npx playwright install chromium 2. Create playwright.config.js with the game's dev server port 3. Expose window. GAME , window. GAME STATE , window. EVENT BUS in main.js 4. Create tests/fixtures/game test.js with the gamePage fixture 5. Create tests/helpers/seed random.js for deterministic behavior 6. Write tests in tests/e2e/ : game.spec.js — boot, scene flow, input, scoring, game over visual.spec.js — screenshot regression for each scene perf.spec.js — load time, FPS budget 7. Add npm scripts: test , test:ui , test:headed , test:update snapshots 8. Generate initial baselines: npm run test:update snapshots What NOT to Test (Automated) Exact pixel positions of animated objects (non deterministic without clock control) Active gameplay screenshots — moving objects make stable screenshots impossible; use MCP instead Audio playback (Playwright has no audio inspection; test that audio objects exist via evaluate) External API calls unless mocked (e.g., Play.fun SDK — mock with page.route() ) Subjective visual quality — use MCP for "does this look good?" evaluations

game-qa