Applied The Lora Playbook

The Game Test Harness

Last reviewed

Intermediate

What you'll learn

~55 min
  • Build a Node.js test harness that runs your Phaser game headless
  • Script collision, spawn, balance, and replay scenarios with game-specific assertions
  • Record a scenario and replay it to check the simulation is deterministic
  • Generate a printable HTML pass/fail report after every run

What you’re building

You have a combat system, enemy behaviors, a HUD, dialogue, and a level editor. You have been playtesting by running the game, pressing buttons, and eyeballing whether things work. That process has two problems: it is slow (you test one scenario at a time), and it is unreliable (you forget to test edge cases, and “it seemed fine when I played it” is not evidence).

Professional game studios have QA teams. You do not. What you can have is an automated test harness that scripts specific scenarios — “spawn the player at position X, place 3 enemies at positions Y, simulate 60 frames of gameplay, check if the player is still alive” — and reports pass or fail. Run it after every change. If a test that used to pass now fails, you know exactly what you broke.

These are the bugs automated testing catches: enemies spawning inside walls, collision boxes that miss at certain angles, difficulty spikes where the player cannot survive a room without exploiting a mechanic. Your test harness catches these problems before a player ever sees them.

By the end of this lesson you will have a Node.js test runner that loads Phaser in headless mode (with a simulated DOM), runs scripted scenarios, checks assertions, records scenario states for playback, and generates an HTML report showing which tests passed and which failed.

ℹSoftware pattern: Headless simulation with assertion testing

Load the application in a non-visual environment, script interactions, check outcomes. This is the same pattern used in end-to-end web testing (Playwright, Cypress), API testing, and simulation validation. The core concept — run the system automatically and verify results — is universal.


The showcase

Here is what the finished test harness produces:

  • Collision tests: Does the player’s hitbox collide with enemies at the expected positions? Does the player stop at walls? Do projectiles hit targets?
  • Spawn verification: Do enemies appear at the positions defined in the level JSON? Does the player start at the correct spawn point? Are all expected entities present after scene initialization?
  • Balance checks: Can the player survive a room with 3 basic enemies? How many hits does it take to defeat a heavy enemy? Does the health potion restore the expected amount?
  • Scenario recording: Define a scenario as a sequence of inputs (move right for 30 frames, attack, wait 10 frames, dodge). Record the game state at each frame. Play it back to verify identical results.
  • HTML report: A single-page report with a summary (X passed, Y failed, Z skipped), a table of all tests with status, duration, and details, and expandable sections showing failure details with expected vs. actual values.

Before you start

If your AI tool is open from the last lesson, leave it (/exit, or Ctrl+D in Antigravity) so you are back at your terminal prompt. Create a folder for this test harness and step into it:

Terminal window
mkdir -p ~/retro-remake/18-game-test-harness && cd ~/retro-remake/18-game-test-harness

In Windows PowerShell, run mkdir ~/retro-remake/18-game-test-harness; cd ~/retro-remake/18-game-test-harness. In a desktop agent app, open ~/retro-remake/18-game-test-harness as your workspace folder. Then start your AI tool the way Workbench Setup showed.

Switch to plan mode

Switch into Plan mode (Shift+Tab, /plan, or the mode picker) so your agent aligns on the headless Phaser bootstrap, scenario runner, game assertions, and HTML report before writing files.

The conversation

Each message below is an example. Say it in your own words.

Say what you want

Ask for an automated game test harness that runs without opening a browser window and produces an HTML pass/fail report:

Build an automated test harness that runs our action game without opening a browser, executes collision, spawn, balance, and replay scenarios, and writes an HTML pass/fail report. Ask me what you need first.

Answer its questions

Your agent will ask about running the game without a browser window, the entity stats, the test categories, and the HTML report:

If it asksYou might say
How should the game run without a browser window?Run the game simulation without graphics and step through frames one by one so tests are fast and repeatable.
What entity stats and actions should the harness simulate?Player (100 HP, 10 damage), basic (80 HP), fast (20 HP), heavy (160 HP), potions (+25 HP), and walls.
Which test categories and scenarios should it include?Four suites: collision checks, level JSON spawn checks, combat balance checks, and deterministic 120-frame scenario replay.
What game checks should tests be able to assert?Alive or dead status, exact or minimum health, position accuracy, enemy counts, collisions, pickup collection, and no wall clipping.
What output should the test runner produce?Print a color-coded terminal summary, fail if any test fails, and save a full report to output/test-report.html.

Read the plan

Before approving the build, check the agent’s plan for these four details:

  1. Node 21+ safe jsdom and headless stepping (src/harness.js): creates a jsdom window before requiring Phaser, defines global.navigator via Object.defineProperty (because Node 21+ already defines a read-only navigator), stops the automatic loop with game.loop.stop() once 'ready' fires, and steps frames deterministically with game.headlessStep(time, 16).
  2. Game API and entity stats: supports createPlayer, createEnemy (basic 80 HP/12 dmg, fast 20 HP/8 dmg, heavy 160 HP/20 dmg), createWall, createPickup, loadLevel (consuming the Level Editor Lite JSON format plus playerSpawn), simulateFrames(n), simulateInput(inputs), and getState(), plus game-specific assertion helpers (isAlive, isDead, healthAbove, healthEquals, positionNear, allEnemiesDead, enemyCount, collisionOccurred, pickupCollected, noClipping).
  3. Thirteen tests across four suites (tests/*.test.js):
    • Collision (4 tests): overlapping enemy deals damage, distant enemy does not, wall stops player movement, ranged attack hits enemy.
    • Spawn (3 tests): fixtures/test-level.json spawns the expected enemy count, places player at playerSpawn, keeps all entities in bounds.
    • Balance (4 tests): player defeats 1 grunt in 8 attacks, dies to 3 grunts without attacking, heals +25 from a potion, and needs 16 hits for a 160 HP heavy enemy.
    • Replay (2 tests): replaying fixtures/scenario-recording.json matches every 10-frame snapshot, and back-to-back runs are deterministic.
  4. Printable HTML report (src/reporter.js): uses chalk@4 and glob@8 (CommonJS) in the runner and writes output/test-report.html with summary cards, pass rate, duration, and expandable expected-vs-actual failure details.

If the plan assigns global.navigator = ... directly or calls game.step() instead of game.headlessStep(time, 16), steer it before approving:

Make sure the headless browser globals work on modern Node versions and step the game simulation forward frame by frame instead of relying on an automatic render loop.

Once the plan covers all four points, approve it and let your agent build the test harness. After running node src/runner.js and opening output/test-report.html, ask your agent to save a Git checkpoint.

💡QA without a QA team

One human playing through a game tests one path per session. An automated harness tests dozens of scenarios in seconds. This is not replacing playtesting — you still need human eyes on the game. But it catches the dumb stuff (collision off by one pixel, enemy spawns inside a wall, health math wrong) so your playtesting time is spent on the things only humans can evaluate: does it feel good?


What you get

After generation, the project folder structure looks like this:

18-game-test-harness/
package.json
src/
runner.js
harness.js
scenario.js
assertions.js
reporter.js
tests/
collision.test.js
spawn.test.js
balance.test.js
scenario-replay.test.js
fixtures/
test-level.json
scenario-recording.json
output/

Fire it up

Ask your agent to install what is needed, run the test suite, and open the HTML report:

Install the packages, run the full game test suite, and open output/test-report.html in my browser.

Or run it from a terminal:

Terminal window
cd ~/retro-remake/18-game-test-harness
npm install
node src/runner.js

You should see terminal output:

REFERENCE OUTPUT Sample 13-test headless game harness terminal output open reference hide reference Reference example of the test runner output when all four suites pass and output/test-report.html is generated.
Game Test Harness - Running all tests...
COLLISION
✓ Player collides with enemy at same position (12ms)
✓ Player does not collide with distant enemy (8ms)
✓ Player stops at wall (15ms)
✓ Projectile hits enemy (11ms)
SPAWN
✓ Level JSON spawns correct enemy count (6ms)
✓ Player spawns at level start position (5ms)
✓ All entities within level bounds (7ms)
BALANCE
✓ Player defeats one grunt with attacks (22ms)
✓ Player cannot survive 3 grunts without attacking (18ms)
✓ Health potion restores 25 health (9ms)
✓ Heavy enemy requires 16 hits (14ms)
REPLAY
✓ Recorded scenario matches (31ms)
✓ Scenario is deterministic (28ms)
13 passed, 0 failed (186ms)
Report: output/test-report.html

Open output/test-report.html in your browser to see the full visual report.

If something is off

ProblemFollow-up prompt
Phaser crashes in Node.jsThe test runner crashes on startup before running any scenarios. Make sure the simulated browser globals are initialized safely on modern Node versions before the game engine loads.
Physics do not simulate in headless modeEntities spawn, but no movement or collisions happen when frames advance. Stop the automatic game loop once the scene is ready and advance the physics simulation manually frame by frame.
Tests run but all failEvery test scenario runs and fails even when the setup looks right. Make sure the state check reads live positions and health values directly from the active game objects after simulating frames.
HTML report is emptyThe runner creates output/test-report.html, but the page shows no test results. Pass the full list of test names, categories, durations, and pass/fail details from the runner into the HTML report generator.

Deep dive

The test harness has four layers, and each one solves a different problem.

The harness is a headless game instance. Phaser supports a HEADLESS render type that runs game logic and physics without creating a visible canvas. This means you can run the game in Node.js, simulate frames programmatically, and inspect the game state — all without opening a browser. Browser test tools like Playwright take the other route and drive a real headless browser, but the idea is the same: run the application in a controlled environment where you can script interactions and inspect outcomes.

Scenarios are reproducible by design. A scenario defines an initial setup (which entities exist and where), an input sequence (what the player does and when), and assertions (what should be true after execution). Given the same setup and inputs, the physics simulation produces the same results every time. This determinism is what makes automated testing possible — if a test passes today but fails tomorrow, something in your game code changed.

Assertions speak game language. Instead of generic expect(value).toBe(other), the assertion helpers use game concepts: isAlive, allEnemiesDead, healthAbove, noClipping. This makes tests readable. “Player defeats one grunt” with assertion assert.isAlive('player') reads like a game design requirement, because it is one.

The HTML report is your CI dashboard. After every code change, run the test harness. The report shows what passed and what broke. If you add a new enemy type and suddenly “Player defeats one grunt” fails, you know your balance changed. The report is evidence, not opinion.

🔍Testing balance, not just bugsclick to expand

The balance tests are the most interesting category. They encode game design decisions as testable assertions:

  • “Player defeats one grunt” means your combat is not impossibly hard.
  • “Player cannot survive without attacking” means the game requires engagement, not just running through.
  • “Heavy enemy requires 16 hits” means damage numbers are calibrated correctly.

When you tweak enemy health, player damage, or attack speed, these tests tell you immediately whether your changes preserved the intended difficulty curve. That is not bug detection — it is design validation. Call it balance regression testing: it is one of the most valuable things automated testing can do for a game.


Customize it

Add visual replay

Add a replay option to the test runner that captures entity positions every 10 frames for any failed test and saves an animated GIF to output/ so I can see what went wrong.

Add performance benchmarks

Add a performance test suite measuring simulated FPS at 10, 50, 100, and 200 enemies, memory delta across 1000 frames, and entity spawn time, rendered with green/yellow/red badges in the HTML report.

Add level validation tests

Add a level validation test suite that scans every level JSON file to verify spawns sit on walkable ground outside walls, at least one reachable exit exists, and all coordinates stay in bounds.

Try it yourself

  1. Walk through the plan-mode conversation above and let your agent build the test harness.
  2. Ask your agent to run the test suite (or run npm install && node src/runner.js) and see all tests pass.
  3. Open the HTML report and review the results. Click a test to see its details.
  4. Break something on purpose: edit fixtures/test-level.json and change an enemy spawn to a position outside the grid. Run the tests again. The spawn test should fail with a clear error message.
  5. Write a new balance test: “Player with 50% health defeats one grunt.” Define the scenario setup, inputs, and assertions. Run the harness and check whether your game supports that difficulty claim.
  6. Run with --verbose to see frame-by-frame state output for debugging.

Key takeaways

  • Automated testing catches regressions instantly. Change enemy damage, run tests, see what broke. No manual playtesting required for known scenarios.
  • Headless Phaser runs in Node.js with a simulated DOM. The same Phaser physics engine that runs in the browser runs in your test environment. The harness defines its own entity stats, so keep them matched to your game’s: then a balance change that breaks one breaks the other.
  • Balance tests encode design decisions. “Player defeats one grunt” is not just a test, it is a documented design constraint that breaks loudly if you violate it.
  • Scenario recording ensures determinism. Record a playthrough, save it, replay it later. If the result changes, your code changed. That is the definition of a regression.
  • The HTML report is shareable evidence. Send it to a collaborator, show it to an investor, attach it to a build. “All 13 tests pass” is more convincing than “I played through it and it seemed fine.”
💡Run tests after every change

The harness takes seconds to run. Make it a habit: edit code, run tests, check report. This loop catches problems when they are small and cheap to fix, not after you have built three more features on top of a broken foundation. That discipline separates hobby projects from shippable products.


What’s next

You have combat, movement, VFX, a HUD, dialogue, a level editor, and automated tests. Every piece exists. None of them are connected. In the next lesson you will build the Playable Demo Assembly — a single cohesive 2-minute playable demo that stitches together the combat loop, movement system, visual effects, HUD, and dialogue into one complete level with a title screen, mission briefing, combat encounters, a boss fight, and a victory screen. That is the artifact that proves the concept works.

intellimetrics · Arlington, VA
© 2026 intellimetrics.net
Search lessons