punkfuncgames/record-golden-test

Record Golden Test — Visual Regression Pipeline

Prerequisites

• A playable game (implement-game completed, optionally polish-game completed)
• MCP bridge connected with replay tools available

Available Tools

| Tool | Purpose | |------|---------| | start_replay_recording | Enter Play Mode and begin capturing inputs + keyframe screenshots | | stop_replay_recording | Stop recording, exit Play Mode, return replay JSON | | play_golden_replay | Replay a saved session by injecting recorded inputs | | validate_golden_replay | Replay + capture at keyframe timestamps + AI vision comparison |

Replay Format

Replays are stored as JSON files:

{
  "gameName": "my-game",
  "recordedAt": "2026-04-01T12:00:00Z",
  "duration": 45.2,
  "resolution": { "width": 1920, "height": 1080 },
  "inputEvents": [
    {
      "timestamp": 0.0,
      "type": "KeyDown",
      "key": "Space",
      "position": null
    },
    {
      "timestamp": 1.25,
      "type": "MouseClick",
      "key": null,
      "position": { "x": 960, "y": 540 }
    }
  ],
  "keyframes": [
    {
      "timestamp": 0.0,
      "screenshot": "keyframes/0000_main-menu.png",
      "description": "Main menu displayed with Play button centered"
    },
    {
      "timestamp": 5.0,
      "screenshot": "keyframes/0001_gameplay-start.png",
      "description": "Gameplay started, player spawned at center, score shows 0"
    },
    {
      "timestamp": 30.0,
      "screenshot": "keyframes/0002_wave-3.png",
      "description": "Wave 3 active, 5 enemies on screen, score shows 1500"
    }
  ]
}

Process

Step 1: Prepare Recording

1. Confirm the game scene is loaded and ready
2. Decide on recording duration (30-60 seconds recommended)
3. Tell the user to get ready to play

Step 2: Record Session

1. Call start_replay_recording with:
   • Game name
   • Target resolution
   • Keyframe interval (default: every 5 seconds)
2. Inform the user that recording has started
3. User plays the game for 30-60 seconds
   • The tool captures all input events (keyboard, mouse, touch, gamepad)
   • Screenshots are taken at each keyframe interval
4. Call stop_replay_recording
5. Receive the replay JSON data

Step 3: Save Replay

Save the replay JSON and keyframe screenshots to:

Tests/GoldenReplays/{game-name}-golden-{timestamp}.json
Tests/GoldenReplays/keyframes/{nnnn}_{description}.png

Screenshots are stored as separate PNG files referenced by relative path in the JSON (not base64-embedded) to keep diffs readable and repo size manageable.

Create the directories if they do not exist:

mkdir -p Tests/GoldenReplays/keyframes

Step 4: Annotate Keyframes

Review each keyframe screenshot and add semantic descriptions:

For each keyframe:

1. Read the screenshot image
2. Write a description that captures the semantic state, not pixel details:
   • What screen/phase is active (menu, gameplay, pause, game over)
   • What entities are visible and approximately where
   • What the score/UI shows
   • What the player is doing
3. Update the keyframe's description field in the JSON

Good descriptions enable semantic comparison during regression:

| Good (Semantic) | Bad (Pixel) | |----------------|-------------| | "3 enemies visible in upper half, player at bottom center" | "Red sprite at x:480 y:900" | | "Score displays 1500, health bar at ~75%" | "Text reads 1500 at position 100,50" | | "Game over screen with final score and retry button" | "Dark overlay with white text" |

Step 5: Verify Replay

1. Call play_golden_replay with the saved JSON file path
2. Observe that the replay reproduces the recorded session
3. Call validate_golden_replay to run the full validation:
   • Replays all input events
   • Captures screenshots at each keyframe timestamp
   • AI vision compares replay screenshots against golden keyframe screenshots
   • Reports pass/fail per keyframe with semantic diff

If validation fails on a keyframe:

• Check if the game has non-deterministic elements (random spawns, physics jitter)
• Widen the semantic tolerance in the description if needed
• Re-record if the issue is fundamental

Step 6: Commit

git add Tests/GoldenReplays/
git commit -m "test({game-name}): record golden replay session"

Regression Testing Workflow

After future changes, run regression by invoking validate_golden_replay:

1. Replay injects the recorded inputs into the game
2. At each keyframe timestamp, a screenshot is captured
3. AI vision compares the new screenshot against the golden keyframe
4. Comparison is semantic, not pixel-perfect:
   • "Are the same entities present in similar positions?"
   • "Does the UI show consistent state?"
   • "Is the overall visual composition similar?"
5. Report lists each keyframe as PASS or FAIL with a description of what diverged

This catches:

• Missing entities after refactors
• Broken UI layouts
• Scoring/progression regressions
• Visual regressions from material or lighting changes

Output

The golden replay file path, keyframe count, duration, and validation result (pass/fail per keyframe).