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.
Reference Files
For detailed reference, see companion files in this directory:
│ ├── 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.
, 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.
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
)
;
}
)
;
Core 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.
When Adding QA to a Game
Install Playwright:
npm install -D @playwright/test @axe-core/playwright && npx playwright install chromium
Create
playwright.config.js
with the game's dev server port
Expose
window.GAME
,
window.GAME_STATE
,
window.EVENT_BUS
in
main.js
Create
tests/fixtures/game-test.js
with the
gamePage
fixture
Create
tests/helpers/seed-random.js
for deterministic behavior
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
Add npm scripts:
test
,
test:ui
,
test:headed
,
test:update-snapshots
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