Game Qa

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:

npm install -D @playwright/test @axe-core/playwright
npx playwright install chromium

Add to package.json scripts:

{
  "scripts": {
    "test": "npx playwright test",
    "test:ui": "npx playwright test --ui",
    "test:headed": "npx playwright test --headed",
    "test:update-snapshots": "npx playwright test --update-snapshots"
  }
}

Required Directory Structure

tests/
├── e2e/
│   ├── game.spec.js       # Core game tests (boot, scenes, input, score)
│   ├── visual.spec.js     # Visual regression screenshots
│   └── perf.spec.js       # Performance and FPS tests
├── fixtures/
│   ├── game-test.js       # Custom test fixture with game helpers
│   └── screenshot.css     # CSS to mask dynamic elements for visual tests
├── helpers/
│   └── seed-random.js     # Seeded PRNG for deterministic game behavior
playwright.config.js

Playwright Config

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html', { open: 'never' }], ['list']],

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 200,
      threshold: 0.3,
    },
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
  ],

  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 30000,
  },
});

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)

// Expose for Playwright QA
window.__GAME__ = game;
window.__GAME_STATE__ = gameState;
window.__EVENT_BUS__ = eventBus;
window.__EVENTS__ = Events;

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.

window.render_game_to_text = () => {
  if (!game || !gameState) return JSON.stringify({ error: 'not_ready' });

  const activeScenes = game.scene.getScenes(true).map(s => s.scene.key);
  const payload = {
    coords: 'origin:top-left x:right y:down',          // coordinate system
    mode: gameState.gameOver ? 'game_over' : 'playing',
    scene: activeScenes[0] || null,
    score: gameState.score,
    bestScore: gameState.bestScore,
  };

  // Add player info when in gameplay
  const gameScene = game.scene.getScene('GameScene');
  if (gameState.started && gameScene?.player?.sprite) {
    const s = gameScene.player.sprite;
    const body = s.body;
    payload.player = {
      x: Math.round(s.x), y: Math.round(s.y),
      vx: Math.round(body.velocity.x), vy: Math.round(body.velocity.y),
      onGround: body.blocked.down,
    };
  }

  // Extend with visible entities as you add them:
  // payload.entities = obstacles.map(o => ({ x: o.x, y: o.y, type: o.type }));

  return JSON.stringify(payload);
};

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.

window.advanceTime = (ms) => {
  return new Promise((resolve) => {
    const start = performance.now();
    function step() {
      if (performance.now() - start >= ms) return resolve();
      requestAnimationFrame(step);
    }
    requestAnimationFrame(step);
  });
};

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

Clock Control for Frame-Precise Testing

Playwright's Clock API controls requestAnimationFrame, giving you frame-precise game control.

Playwright Clock API Pattern

test('bird falls after 1 second without input', async ({ page }) => {
  await page.clock.install();
  await page.goto('/');
  await page.waitForFunction(() => window.__GAME__?.isBooted);

  // Start game
  await page.keyboard.press('Space');
  await page.waitForFunction(() => window.__GAME_STATE__.started);

  const yBefore = await page.evaluate(() => {
    return window.__GAME__.scene.getScene('GameScene').bird.y;
  });

  // Advance exactly 1 second
  await page.clock.runFor(1000);

  const yAfter = await page.evaluate(() => {
    return window.__GAME__.scene.getScene('GameScene').bird.y;
  });

  expect(yAfter).toBeGreaterThan(yBefore); // bird fell
});

When to Use Clock Control

• When you need exact frame timing (e.g., "after exactly 1 second")
• For deterministic physics tests where real-time variance would cause flakes
• To test time-based mechanics (cooldowns, spawn timers, delays)

Notes

• page.clock.install() must be called before page.goto()
• page.clock.runFor(ms) advances both Date.now() and requestAnimationFrame callbacks
• The standalone iterate client (scripts/iterate-client.js) uses advanceTime(ms) instead, which is real-time based

Gameplay Invariants

Every game built through the pipeline must pass these minimum gameplay checks. These verify the game is actually playable, not just renders without errors.

1. Scoring works

The player must be able to earn at least 1 point through normal gameplay actions:

test('player can score at least 1 point', async ({ gamePage }) => {
  // Start the game (space/tap)
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started, null, { timeout: 5000 });

  // Perform gameplay actions — keep the player alive
  const actionInterval = setInterval(async () => {
    await gamePage.keyboard.press('Space').catch(() => {});
  }, 400);

  // Wait for score > 0
  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.score > 0,
    null,
    { timeout: 20000 }
  );
  clearInterval(actionInterval);

  const score = await gamePage.evaluate(() => window.__GAME_STATE__.score);
  expect(score).toBeGreaterThan(0);
});

2. Death/fail condition triggers

The player must be able to die or lose through inaction or collision:

test('game over triggers through normal gameplay', async ({ gamePage }) => {
  // Start the game
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started, null, { timeout: 5000 });

  // Do nothing — let the fail condition trigger naturally (fall, timer, collision)
  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.gameOver === true,
    null,
    { timeout: 15000 }
  );

  const isOver = await gamePage.evaluate(() => window.__GAME_STATE__.gameOver);
  expect(isOver).toBe(true);
});

3. Game-over buttons have visible text

After game over, restart/play-again buttons must show their text labels:

test('game over buttons display text labels', async ({ gamePage }) => {
  // Trigger game over
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started, null, { timeout: 5000 });
  await gamePage.waitForFunction(() => window.__GAME_STATE__.gameOver, null, { timeout: 15000 });

  // Wait for GameOverScene to render
  await gamePage.waitForFunction(() => {
    const scenes = window.__GAME__.scene.getScenes(true);
    return scenes.some(s => s.scene.key === 'GameOverScene');
  }, null, { timeout: 5000 });
  await gamePage.waitForTimeout(500);

  // Check that text objects exist and are visible in the scene
  const hasVisibleText = await gamePage.evaluate(() => {
    const scene = window.__GAME__.scene.getScene('GameOverScene');
    if (!scene) return false;
    const textObjects = scene.children.list.filter(
      child => child.type === 'Text' && child.visible && child.alpha > 0
    );
    // Should have at least: title ("GAME OVER"), score, and button label ("PLAY AGAIN")
    return textObjects.length >= 3;
  });
  expect(hasVisibleText).toBe(true);
});

4. render_game_to_text() returns valid state

The AI-readable state function must return parseable JSON with required fields:

test('render_game_to_text returns valid game state', async ({ gamePage }) => {
  const stateStr = await gamePage.evaluate(() => window.render_game_to_text());
  const state = JSON.parse(stateStr);

  expect(state).toHaveProperty('mode');
  expect(state).toHaveProperty('score');
  expect(['playing', 'game_over']).toContain(state.mode);
  expect(typeof state.score).toBe('number');
});

5. Design Intent

Tests that catch mechanics which technically exist but are too weak to affect gameplay. These use values from Constants.js to set meaningful thresholds instead of trivial > 0 checks.

Detecting win/lose state: Read GameState.js for won, result, or similar boolean/enum fields. Check render_game_to_text() in main.js for distinct outcome modes ('win' vs 'game_over'). If either exists, the game has a lose state — write lose-condition tests.

Using design-brief.md: If design-brief.md exists in the project root, read it for expected magnitudes, rates, and win/lose reachability. Use these values to set test thresholds instead of deriving from Constants.js alone.

Non-negotiable assertion: The no-input lose test must assert the losing outcome. Never write a passing test for a no-input win — if the player wins by doing nothing, that is a bug, and the test exists to catch it.

Lose condition — verify the player can actually lose:

test('player loses when providing no input', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.gameOver,
    null,
    { timeout: 45000 }
  );

  const result = await gamePage.evaluate(() => window.__GAME_STATE__.result);
  expect(result).toBe('lose');
});

Opponent/AI pressure — verify AI mechanics produce substantial state changes:

test('opponent reaches 25% within half the round duration', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  const { halfDuration, maxValue } = await gamePage.evaluate(() => {
    return {
      halfDuration: window.Constants?.ROUND_DURATION_MS / 2 || 15000,
      maxValue: window.Constants?.MAX_VALUATION || 100,
    };
  });

  await gamePage.waitForTimeout(halfDuration);

  const opponentValue = await gamePage.evaluate(() => {
    return window.__GAME_STATE__.opponentScore;
  });

  expect(opponentValue).toBeGreaterThanOrEqual(maxValue * 0.25);
});

Win condition — verify active input leads to a win:

test('player wins with active input', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  const inputInterval = setInterval(async () => {
    await gamePage.keyboard.press('Space').catch(() => {});
  }, 100);

  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.gameOver,
    null,
    { timeout: 45000 }
  );

  clearInterval(inputInterval);

  const result = await gamePage.evaluate(() => window.__GAME_STATE__.result);
  expect(result).toBe('win');
});

Adapt field names (result, opponentScore, constant names) to match the specific game's GameState and Constants. The patterns above are templates — read the actual game code to determine the correct fields and thresholds.

6. Entity Interaction Audit

Audit collision and interaction logic for asymmetries. A first-time player expects consistent rules: if visible objects interact with some entities, they expect them to interact with all relevant entities.

What to check: Read all collision handlers in GameScene.js. Map entity->entity interactions. Flag any visible moving entity that interacts with one side but not the other.

Using design-brief.md: If an "Entity Interactions" section exists, verify each documented interaction matches the code. Flag any entity documented as "no player interaction" that isn't clearly background/decoration.

Output: Add // QA FLAG: asymmetric interaction comments in game.spec.js for any flagged entity. This is informational — the flag surfaces the issue for human review, it doesn't fail the test suite.

7. Mute Button Exists and Toggles

Every game with audio must have a mute toggle. Test that isMuted exists on GameState and responds to the M key shortcut:

test('mute button exists and toggles audio state', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started, null, { timeout: 5000 });

  const hasMuteState = await gamePage.evaluate(() => {
    return typeof window.__GAME_STATE__.isMuted === 'boolean';
  });
  expect(hasMuteState).toBe(true);

  const before = await gamePage.evaluate(() => window.__GAME_STATE__.isMuted);
  await gamePage.keyboard.press('m');
  await gamePage.waitForTimeout(100);
  const after = await gamePage.evaluate(() => window.__GAME_STATE__.isMuted);
  expect(after).toBe(!before);

  await gamePage.keyboard.press('m');
  await gamePage.waitForTimeout(100);
  const restored = await gamePage.evaluate(() => window.__GAME_STATE__.isMuted);
  expect(restored).toBe(before);
});

The M key is a testable proxy for the mute button — if the event wiring exists, the visual button does too. Playwright cannot inspect Phaser Graphics objects directly.

Iterate Client -- Quick Feedback Loop

The standalone iterate client (scripts/iterate-client.js) is designed for tight implement-then-test cycles during development. Use it after every meaningful code change to catch issues immediately, rather than waiting for the full @playwright/test suite.

When to Use

Usage

# Basic: press space 3 times, capture screenshots each time
node scripts/iterate-client.js --url http://localhost:3000 \
  --actions-json '[{"buttons":["space"],"frames":4}]' \
  --iterations 3

# With action file
node scripts/iterate-client.js --url http://localhost:3000 \
  --actions-file scripts/example-actions.json --iterations 5

# Click a start button first, then perform actions
node scripts/iterate-client.js --url http://localhost:3000 \
  --click-selector "#play-btn" \
  --actions-json '[{"buttons":["right"],"frames":30},{"buttons":["space","right"],"frames":10}]'

# Debug: run headed (visible browser)
node scripts/iterate-client.js --url http://localhost:3000 \
  --actions-json '[{"buttons":["space"],"frames":4}]' \
  --headless false

Action Format

{
  "steps": [
    { "buttons": ["space"], "frames": 4 },
    { "buttons": [], "frames": 30 },
    { "buttons": ["right"], "frames": 30 },
    { "buttons": ["space", "right"], "frames": 10 },
    { "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 480, "mouse_y": 270 }
  ]
}

Supported buttons: up, down, left, right, space, enter, escape, w, a, s, d, f, m, left_mouse_button, right_mouse_button.

Output

output/iterate/
├── shot-0.png          # Canvas screenshot after iteration 0
├── state-0.json        # render_game_to_text() output
├── shot-1.png
├── state-1.json
├── errors-0.json       # Console errors (only if errors occurred)
└── errors-boot.json    # Boot-time errors (only if errors occurred)

The client breaks on the first new console error -- fix it before continuing.

Integration with AI Agents

The iterate client is the primary feedback mechanism for AI agents during game development:

1. Agent makes a code change 2. Agent runs iterate client with relevant actions 3. Agent reads screenshots (visually) and state JSON (structurally) to verify the change 4. If errors detected, agent reads the error JSON and fixes 5. Repeat until stable

Mobile Input & Responsive Layout Tests

Use the mobile-chrome project (Pixel 5 emulation) to test touch input and responsive layout.

Mobile Test Patterns

test('game canvas fills mobile viewport', async ({ gamePage }) => {
  const { width, height } = await gamePage.evaluate(() => {
    const canvas = document.querySelector('canvas');
    return { width: canvas.clientWidth, height: canvas.clientHeight };
  });
  const viewport = gamePage.viewportSize();
  expect(width).toBeGreaterThanOrEqual(viewport.width * 0.9);
  expect(height).toBeGreaterThanOrEqual(viewport.height * 0.9);
});

test('virtual joystick appears on touch device', async ({ gamePage }) => {
  // Start the game
  await gamePage.tap('#play-btn');
  await gamePage.waitForTimeout(1000);
  // Joystick should be visible (if gyro is unavailable in emulation)
  const joystick = await gamePage.$('#virtual-joystick');
  // On emulated devices without gyro, joystick should appear
  if (joystick) {
    const visible = await joystick.isVisible();
    expect(visible).toBe(true);
  }
});

test('touch tap registers as input', async ({ gamePage }) => {
  await gamePage.tap('#play-btn');
  await gamePage.waitForFunction(() => window.__GAME_STATE__?.started);
  // Tap on the canvas
  const canvas = gamePage.locator('canvas');
  await canvas.tap();
  // Game should still be running (no crash from touch input)
  const running = await gamePage.evaluate(() => window.__GAME_STATE__?.started);
  expect(running).toBe(true);
});

Notes

• The mobile-chrome project in playwright.config.js uses Pixel 5 device emulation
• Touch events are simulated via Playwright's .tap() method
• Virtual joystick testing requires checking if the DOM element exists (games without joystick will skip)
• Canvas tap tests verify the game doesn't crash on touch input, not specific gameplay behavior

Playwright MCP -- Interactive Visual QA

In addition to automated tests, use the Playwright MCP for interactive visual inspection. This gives your agent direct browser control for screenshots, element inspection, and real visual evaluation.

Setup

Install the Playwright MCP server so your agent can use browser_navigate, browser_take_screenshot, browser_snapshot, browser_evaluate, and other browser control tools:

claude mcp add playwright npx @playwright/mcp@latest

After running this command, the user must restart their agent (e.g., restart Claude Code) for the MCP server to take effect. Prompt them:

Playwright MCP has been added. Please restart Claude Code for it to take effect, then tell me to continue.

To verify it's working, try calling browser_navigate to any URL. If the tool is not available, the MCP server hasn't loaded yet.

When to Use MCP vs Automated Tests

MCP Visual Inspection Flow

When using MCP for QA:

1. `browser_navigate` to the game URL (e.g., http://localhost:3000) 2. `browser_wait_for` -- wait 2 seconds for the game to fully render 3. `browser_take_screenshot` -- capture gameplay (game starts immediately, no title screen) 4. Assess visually: Check rendering, entity sizing, background, atmosphere 5. Check safe zone: Verify no UI elements are hidden behind the top ~8% of the screen (Play.fun widget area at 75px). If deployed, inspect the widget directly:

   // browser_evaluate -- inspect Play.fun widget iframe
   const iframe = document.querySelector('iframe[src*="widget.play.fun"]');
   if (iframe) {
     const styles = window.getComputedStyle(iframe);
     return { position: styles.position, top: styles.top, height: styles.height, zIndex: styles.zIndex };
   }
   return 'No Play.fun widget found';

6. Check buttons: If game over is visible, verify button labels (text) are readable -- not blank rectangles 7. Let the player die, `browser_take_screenshot` -- check game-over screen polish and score display 8. `browser_press_key` (Space) -- restart and verify transitions 9. Report findings with specific visual observations

MCP + Automated: Best of Both

The recommended workflow is:

1. Write automated tests for all objective checks (boot, scenes, input, scoring, game over, regression, gameplay invariants) 2. Use MCP for subjective visual evaluation (does it look good? feel right? color palette working? safe zone respected? entity sizes appropriate?) 3. Run automated tests in CI; run MCP inspections during design passes

Test Patterns

Custom fixture code, boot tests, gameplay tests, and scoring tests for Playwright game QA.

Custom Test Fixture

Create a reusable fixture with game-specific helpers:

import { test as base, expect } from '@playwright/test';

export const test = base.extend({
  gamePage: async ({ page }, use) => {
    await page.goto('/');
    // Wait for Phaser to boot and canvas to render
    await page.waitForFunction(() => {
      const g = window.__GAME__;
      return g && g.isBooted && g.canvas;
    }, null, { timeout: 10000 });
    await use(page);
  },
});

export { expect };

Core Testing Patterns

1. Game Boot & Scene Flow

Test that the game initializes and scenes transition correctly.

import { test, expect } from '../fixtures/game-test.js';

test('game boots directly to gameplay', async ({ gamePage }) => {
  const sceneKey = await gamePage.evaluate(() => {
    return window.__GAME__.scene.getScenes(true)[0]?.scene?.key;
  });
  expect(sceneKey).toBe('GameScene');
});

2. Gameplay Verification

Test that game mechanics work — input affects state, scoring works, game over triggers.

test('bird flaps on space press', async ({ gamePage }) => {
  // Start game
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  // Record position before flap
  const yBefore = await gamePage.evaluate(() => {
    const scene = window.__GAME__.scene.getScene('GameScene');
    return scene.bird.y;
  });

  // Flap
  await gamePage.keyboard.press('Space');
  await gamePage.waitForTimeout(100);

  // Bird should have moved up (lower y)
  const yAfter = await gamePage.evaluate(() => {
    const scene = window.__GAME__.scene.getScene('GameScene');
    return scene.bird.y;
  });
  expect(yAfter).toBeLessThan(yBefore);
});

test('game over triggers on collision', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  // Don't flap — let bird fall to ground
  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.gameOver,
    null,
    { timeout: 10000 }
  );

  expect(await gamePage.evaluate(() => window.__GAME_STATE__.gameOver)).toBe(true);
});

3. Scoring

test('score increments when passing pipes', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  // Keep flapping to survive
  const flapInterval = setInterval(async () => {
    await gamePage.keyboard.press('Space').catch(() => {});
  }, 300);

  // Wait for at least 1 score
  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.score > 0,
    null,
    { timeout: 15000 }
  );

  clearInterval(flapInterval);

  const score = await gamePage.evaluate(() => window.__GAME_STATE__.score);
  expect(score).toBeGreaterThan(0);
});

Visual Regression & Advanced Testing

Screenshot comparison tests, performance/FPS tests, accessibility tests, and deterministic testing patterns for browser games.

Visual Regression Screenshots

Screenshot-based tests to catch unintended visual changes.

test('gameplay scene renders correctly', async ({ gamePage }) => {
  // Wait a beat for animations to settle
  await gamePage.waitForTimeout(500);
  await expect(gamePage.locator('canvas')).toHaveScreenshot('gameplay-scene.png', {
    maxDiffPixels: 300,
  });
});

test('game over scene renders correctly', async ({ gamePage }) => {

  // Let bird die
  await gamePage.waitForFunction(
    () => window.__GAME_STATE__.gameOver,
    null,
    { timeout: 10000 }
  );

  // Wait for game over scene
  await gamePage.waitForFunction(() => {
    const scenes = window.__GAME__.scene.getScenes(true);
    return scenes.some(s => s.scene.key === 'GameOverScene');
  });
  await gamePage.waitForTimeout(600); // transitions

  await expect(gamePage.locator('canvas')).toHaveScreenshot('game-over-scene.png', {
    maxDiffPixels: 300,
  });
});

Masking dynamic elements — use screenshot.css to hide particles, clouds, or animated elements that cause non-deterministic screenshots:

/* tests/fixtures/screenshot.css */
/* No CSS rules needed for canvas games — canvas is opaque to CSS.
   Instead, use window.__TEST_MODE__ flag in game code to freeze animations. */

Performance & FPS Tests

test('game loads within 3 seconds', async ({ page }) => {
  const start = Date.now();
  await page.goto('/');
  await page.waitForFunction(() => {
    const g = window.__GAME__;
    return g && g.isBooted && g.canvas;
  });
  const loadTime = Date.now() - start;
  expect(loadTime).toBeLessThan(3000);
});

test('game maintains 30+ FPS during gameplay', async ({ gamePage }) => {
  await gamePage.keyboard.press('Space');
  await gamePage.waitForFunction(() => window.__GAME_STATE__.started);

  const avgFps = await gamePage.evaluate(() => {
    return new Promise((resolve) => {
      let frames = 0;
      const start = performance.now();
      function countFrame() {
        frames++;
        if (performance.now() - start < 2000) {
          requestAnimationFrame(countFrame);
        } else {
          resolve(frames / ((performance.now() - start) / 1000));
        }
      }
      requestAnimationFrame(countFrame);
    });
  });

  expect(avgFps).toBeGreaterThan(30);
});

Accessibility Tests

Canvas games are inherently opaque to screen readers, but test the surrounding HTML:

import AxeBuilder from '@axe-core/playwright';

test('page has no accessibility violations', async ({ gamePage }) => {
  const results = await new AxeBuilder({ page: gamePage })
    .exclude('canvas')
    .analyze();
  expect(results.violations).toEqual([]);
});

Deterministic Testing

For reproducible tests, seed the game's RNG before page load:

// tests/helpers/seed-random.js
// Mulberry32 seeded PRNG — inject via page.addInitScript()
(function() {
  let seed = 42;
  Math.random = function() {
    seed |= 0;
    seed = (seed + 0x6D2B79F5) | 0;
    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
})();

Use it in tests:

test.beforeEach(async ({ page }) => {
  await page.addInitScript({ path: './tests/helpers/seed-random.js' });
});

Phaser also supports seeded RNG via config:

const config = {
  seed: ['qa-test-seed'],
  // ...
};