QA Game
Add automated QA testing with Playwright to an existing game project. Tests verify your game boots, scenes work, scoring functions, and visuals haven't broken — like a safety net for your game.
Instructions
Analyze the game at $ARGUMENTS (or the current directory if no path given).
First, load the game-qa skill to get the full testing patterns and fixtures.
Step 1: Audit testability
- Read
package.json to identify the engine and dev server port
- Read
vite.config.js for the server port
- Read
src/main.js to check if window.__GAME__, window.__GAME_STATE__, window.__EVENT_BUS__ are exposed
- Read
src/core/GameState.js to understand what state is available
- Read
src/core/EventBus.js to understand what events exist
- Read
src/core/Constants.js to understand game parameters (rates, speeds, durations, max values)
- Read all scene files to understand the game flow
- Read
design-brief.md if it exists — it documents expected mechanics, magnitudes, and win/lose reachability
Step 2: Setup Playwright
- Install dependencies:
npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium
- Create
playwright.config.js with the correct dev server port and webServer config
- Expose
window.__GAME__, window.__GAME_STATE__, window.__EVENT_BUS__, window.__EVENTS__ in src/main.js if not already present
- Create the test directory structure:
tests/
├── e2e/
│ ├── game.spec.js
│ ├── visual.spec.js
│ └── perf.spec.js
├── fixtures/
│ └── game-test.js
└── helpers/
└── seed-random.js
- Add npm scripts:
test, test:ui, test:headed, test:update-snapshots
Step 3: Generate tests
Write tests based on what the game actually does:
- game.spec.js: Boot test, scene transitions, input handling, scoring, game over, restart
- visual.spec.js: Screenshot regression for stable scenes (gameplay initial state, game over). Skip active gameplay screenshots — moving objects make them unstable.
- perf.spec.js: Load time budget, FPS during gameplay, canvas dimensions
Follow the game-qa skill patterns. Use gamePage fixture. Use page.evaluate() to read game state. Use page.keyboard.press() for input.
Step 4: Design-intent tests
Add a test.describe('Design Intent') block to game.spec.js. These tests catch
mechanics that technically exist but are too weak to matter.
Lose condition: Detect deterministically whether the game has a lose state.
Read GameState.js — if it has a won, result, or similar boolean/enum
field, the game distinguishes win from loss. Also check render_game_to_text()
in main.js — if it returns distinct outcome modes (e.g., 'win' vs
'game_over'), the game has a lose state.
If a lose state exists: start the game, provide NO input, let it run to
completion (use page.waitForFunction with the round duration from
Constants.js). Assert the outcome is the losing one (e.g., won === false,
mode === 'game_over').
This assertion is non-negotiable. Do NOT write a test that passes when the
player wins by doing nothing. If the current game behavior is "player wins
with no input," that is a bug — write the test to catch it.
Opponent/AI pressure: If an AI-driven mechanic exists (auto-climbing bar,
enemy spawning, difficulty ramp), test that it produces substantial state
changes. Run the game for half its duration without player input. Assert the
opponent's state reaches at least 25% of its maximum. If design-brief.md
exists, use its expected magnitudes for thresholds. Otherwise, derive from
Constants.js: calculate rate * duration and assert it reaches meaningful
levels.
Win condition: Test that active player input leads to a win. Provide rapid
input throughout the round and assert the outcome is a win.
Step 5: Entity interaction audit
Audit collision and interaction logic for asymmetries that would confuse a
first-time player.
If design-brief.md has an "Entity Interactions" section, use it as the
checklist. Otherwise, audit GameScene.js directly:
- Find all collision handlers, overlap checks, or distance-based interactions
- Map which entities interact with which others
- Flag any visible moving entity that interacts with one side (player OR
opponent) but not the other — add a
// QA FLAG: asymmetric interaction
comment in the test file noting the entity name and the asymmetry
This is a flag, not a hard fail. Some asymmetries are intentional (e.g.,
hazards that only affect the player). The flag ensures the asymmetry is a
conscious design choice, not an oversight.
Step 6: Run and verify
- Run
npx playwright test to execute all tests
- If visual tests fail on first run, that's expected — generate baselines with
npx playwright test --update-snapshots
- Run again to verify all tests pass
- Summarize results
Step 7: Report
Tell the user in plain English:
- How many tests were created and what they check
- How to run them:
npm test (headless), npm run test:headed (see the browser), npm run test:ui (interactive dashboard)
- "These tests are your safety net. Run them after making changes to make sure nothing broke."
Example Usage
/qa-game examples/flappy-bird
Result: Installs Playwright → creates 15 tests (boot, scene transitions, input, scoring, restart, game-over, visual regression, FPS, load time) → generates tests/ directory with fixtures and helpers → all tests pass. Run npm test anytime after changes.
Next Step
Tell the user:
Your game now has automated tests! Finally, run /game-creator:review-game for a full architecture review — it checks your code structure, performance patterns, and gives you a score with specific improvement suggestions.
Pipeline progress: /viral-game → /design-game → /add-audio → /qa-game → /review-game
(This is the /viral-game one-shot pipeline — not the /make-game multi-session, milestone-driven workflow.)
1---2name: qa-game3description: Add Playwright QA tests to a game — visual regression, gameplay verification, and performance. Use when the user says "add tests", "test my game", "add QA", "check for bugs", or "add visual regression tests". Do NOT use for manual playtesting or gameplay design.4argument-hint: "[path-to-game]"5license: MIT6metadata:7 source: https://skillmd.com/skills/playableintelligence/qa-game8 author: OpusGameLabs9 version: 1.3.010 tags: [game, qa, testing, playwright, visual-regression]11---1213# QA Game1415Add automated QA testing with Playwright to an existing game project. Tests verify your game boots, scenes work, scoring functions, and visuals haven't broken — like a safety net for your game.1617## Instructions1819Analyze the game at `$ARGUMENTS` (or the current directory if no path given).2021First, load the game-qa skill to get the full testing patterns and fixtures.2223### Step 1: Audit testability2425- Read `package.json` to identify the engine and dev server port26- Read `vite.config.js` for the server port27- Read `src/main.js` to check if `window.__GAME__`, `window.__GAME_STATE__`, `window.__EVENT_BUS__` are exposed28- Read `src/core/GameState.js` to understand what state is available29- Read `src/core/EventBus.js` to understand what events exist30- Read `src/core/Constants.js` to understand game parameters (rates, speeds, durations, max values)31- Read all scene files to understand the game flow32- Read `design-brief.md` if it exists — it documents expected mechanics, magnitudes, and win/lose reachability3334### Step 2: Setup Playwright35361. Install dependencies: `npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium`372. Create `playwright.config.js` with the correct dev server port and webServer config383. Expose `window.__GAME__`, `window.__GAME_STATE__`, `window.__EVENT_BUS__`, `window.__EVENTS__` in `src/main.js` if not already present394. Create the test directory structure:40 ```41 tests/42 ├── e2e/43 │ ├── game.spec.js44 │ ├── visual.spec.js45 │ └── perf.spec.js46 ├── fixtures/47 │ └── game-test.js48 └── helpers/49 └── seed-random.js50 ```515. Add npm scripts: `test`, `test:ui`, `test:headed`, `test:update-snapshots`5253### Step 3: Generate tests5455Write tests based on what the game actually does:5657- **game.spec.js**: Boot test, scene transitions, input handling, scoring, game over, restart58- **visual.spec.js**: Screenshot regression for stable scenes (gameplay initial state, game over). Skip active gameplay screenshots — moving objects make them unstable.59- **perf.spec.js**: Load time budget, FPS during gameplay, canvas dimensions6061Follow the game-qa skill patterns. Use `gamePage` fixture. Use `page.evaluate()` to read game state. Use `page.keyboard.press()` for input.6263### Step 4: Design-intent tests6465Add a `test.describe('Design Intent')` block to game.spec.js. These tests catch66mechanics that technically exist but are too weak to matter.67681. **Lose condition**: Detect deterministically whether the game has a lose state.69 Read `GameState.js` — if it has a `won`, `result`, or similar boolean/enum70 field, the game distinguishes win from loss. Also check `render_game_to_text()`71 in `main.js` — if it returns distinct outcome modes (e.g., `'win'` vs72 `'game_over'`), the game has a lose state.7374 If a lose state exists: start the game, provide NO input, let it run to75 completion (use `page.waitForFunction` with the round duration from76 Constants.js). Assert the outcome is the losing one (e.g., `won === false`,77 `mode === 'game_over'`).7879 **This assertion is non-negotiable.** Do NOT write a test that passes when the80 player wins by doing nothing. If the current game behavior is "player wins81 with no input," that is a bug — write the test to catch it.82832. **Opponent/AI pressure**: If an AI-driven mechanic exists (auto-climbing bar,84 enemy spawning, difficulty ramp), test that it produces substantial state85 changes. Run the game for half its duration without player input. Assert the86 opponent's state reaches at least 25% of its maximum. If `design-brief.md`87 exists, use its expected magnitudes for thresholds. Otherwise, derive from88 Constants.js: calculate `rate * duration` and assert it reaches meaningful89 levels.90913. **Win condition**: Test that active player input leads to a win. Provide rapid92 input throughout the round and assert the outcome is a win.9394### Step 5: Entity interaction audit9596Audit collision and interaction logic for asymmetries that would confuse a97first-time player.9899If `design-brief.md` has an "Entity Interactions" section, use it as the100checklist. Otherwise, audit `GameScene.js` directly:1011021. Find all collision handlers, overlap checks, or distance-based interactions1032. Map which entities interact with which others1043. Flag any visible moving entity that interacts with one side (player OR105 opponent) but not the other — add a `// QA FLAG: asymmetric interaction`106 comment in the test file noting the entity name and the asymmetry107108This is a flag, not a hard fail. Some asymmetries are intentional (e.g.,109hazards that only affect the player). The flag ensures the asymmetry is a110conscious design choice, not an oversight.111112### Step 6: Run and verify1131141. Run `npx playwright test` to execute all tests1152. If visual tests fail on first run, that's expected — generate baselines with `npx playwright test --update-snapshots`1163. Run again to verify all tests pass1174. Summarize results118119### Step 7: Report120121Tell the user in plain English:122123- How many tests were created and what they check124- How to run them: `npm test` (headless), `npm run test:headed` (see the browser), `npm run test:ui` (interactive dashboard)125- "These tests are your safety net. Run them after making changes to make sure nothing broke."126127## Example Usage128129```130/qa-game examples/flappy-bird131```132Result: Installs Playwright → creates 15 tests (boot, scene transitions, input, scoring, restart, game-over, visual regression, FPS, load time) → generates `tests/` directory with fixtures and helpers → all tests pass. Run `npm test` anytime after changes.133134## Next Step135136Tell the user:137138> Your game now has automated tests! Finally, run `/game-creator:review-game` for a full architecture review — it checks your code structure, performance patterns, and gives you a score with specific improvement suggestions.139>140> **Pipeline progress:** ~~/viral-game~~ → ~~/design-game~~ → ~~/add-audio~~ → ~~/qa-game~~ → `/review-game`141>142> *(This is the `/viral-game` one-shot pipeline — not the `/make-game` multi-session, milestone-driven workflow.)*