Coding agents can write a web game in minutes, but they can't watch it move. playproof lets them (and you) see a game frame by frame, play it with scripted input, hunt for crashes, check it on phone screens and measure how smoothly it runs, on desktop or on a real Android phone. Everything comes back as images made to be read, with a short summary that points at what looks wrong.
[A contact sheet of a buggy game: two white flicker frames and a teleporting ball are outlined in red and explained under the chart]
Tested with Canvas 2D, DOM, Phaser 3, PixiJS 8, three.js, Godot 4 web exports and Unity WebGL builds: two runs of each give identical frames (npm run test:engines).
Install
Ask your agent
Paste this into Claude Code, Codex, Cursor, Gemini CLI or any other coding agent:
It will pick the right command below for itself.
Claude Code
Codex
Gemini CLI
Cursor, OpenCode, GitHub Copilot and other agents
Claude Desktop and other MCP apps
For apps that call tools instead of running commands, playproof is also an MCP server whose tools return the images directly. Add it to the app's MCP config:
Without an agent
Nothing to install. npx playproof init in your game's folder writes a playproof.config.json (it finds your dev server, build folder or HTML file); or point any command at a dev server, a build folder or an HTML file directly:
playproof uses your installed Chrome or Edge. npx playproof install-browser downloads its own Chromium if you prefer.
Why
A screenshot catches one random instant, so the things that make a game feel broken stay invisible: a jump without anticipation, a sprite that teleports, a one-frame flicker, a button that does nothing, a crash after a hundred taps, a canvas that is blurry on every phone.
playproof runs the game on a virtual clock. Time only moves when playproof moves it, one exact frame at a time, so it can film any moment and every run gives the same pixels. Then it lays the frames out where a model (or a person) can actually look at them. Because runs repeat exactly, an agent can film a motion, change the code, film it again and see precisely what its change did.
What it does
frames: watch an animation
Films the game frame by frame and builds a contact sheet: dashed boxes show what changed since the previous tile, and the bar chart shows how much of the screen changed in every frame. playproof flags sudden jumps (teleports, missing tweens), one-frame flicker (draw-order bugs, half-updated state), holds (stalls) and nothing moving at all.
[Contact sheet of a jump: 14 tiles over 700 ms with dashed boxes around what moved, and a bar per frame]
Add --animate to also get the film as an animated PNG at real speed, to watch it yourself or drop into a pull request. Add --zoom auto when the thing that moves is small: playproof captures at full device resolution and crops every frame to where most of the motion happens, so a character's squash and stretch fill the tiles.
It also draws an onion skin: the whole motion in one picture, oldest moments faintest. The gaps between the ghosts are the easing (wide gaps are fast, tight gaps are slow), which is exactly what animators look at to judge an arc, an anticipation or an overshoot.
[Onion skin of the jump: ghosts bunch up near the top of the arc, where the character slows down]
frames --compare: see what a change did
Film, change the code, film again with --compare <earlier run>. Every sampled frame of the earlier run sits above the same frame now, with the differences outlined, and the earlier run's motion is drawn as a line over the new bars. Because runs are deterministic, "identical" means identical.
[Before and after a snappier jump: the new frames reach the top sooner and land earlier]
play: run a script, get a storyboard
[Storyboard: title screen, four frames of a jump, the game over screen, and the retry]
monkey: random play that hunts for crashes
Taps, drags, long presses, rapid triple taps, keys, and sending the tab to the background, all at random but repeatable by seed. It reports uncaught errors, failed requests, hangs (infinite loops), soft-locks (input keeps coming, nothing changes) and a render loop that stops. Every error comes with a command that reproduces it exactly, and the whole run is saved as repro.steps, a script play --script replays action by action: delete lines until only the ones that matter are left.
When the game exposes its buttons (see the hook below), the monkey explores: on each screen it tries buttons it has not pressed yet before repeating itself. screens.png shows every distinct screen it reached, so you can see how far a random player gets, and what it never reached.
devices: phones, tablet and desktop side by side
Loads the game on nine screens and checks for the layout bugs that only show up there: blurry canvas (no devicePixelRatio scaling), stretched canvas, canvas cut off, page scrolling, missing viewport meta, missing touch-action: none, clipped text and tiny touch targets. The same problem on several devices is reported once.
[Six devices side by side; the stretched ball on landscape and desktop is obvious, and findings are listed underneath]
On a real Android phone, in Chrome or inside your app
frames, play, monkey and perf run on a USB-connected Android phone with --android (a tab in Chrome) or --app <package>, which attaches to the WebView inside an app built with Capacitor, Cordova or Ionic. playproof reloads the app's page with the virtual clock, so you get the same frame-exact sheets from the real app on the real device, and reloads it back to normal when it is done. Localhost is forwarded to the phone automatically.
Debug builds of Capacitor and Cordova apps have WebView debugging on; for other builds see webContentsDebuggingEnabled. In Chrome, playproof opens its own tab, talks only to that tab and closes it afterwards; it never lists or reads your other tabs.
perf: frame pacing, locally or on a real phone
Measures real frame times while the game idles, runs a script (--do) or takes random taps (--monkey): fps, p95/p99, dropped frames against the display's refresh rate, long main-thread tasks and heap growth. Locally the CPU is slowed 4× to approximate a mid-range phone. With --android it measures Chrome on a USB-connected Android phone; localhost is forwarded to the phone automatically.
[Frame-time chart with most bars over the 16.7 ms budget line, marked red]
Scenarios and check: snapshot tests for motion
Put the game's defaults and the moments worth watching in playproof.config.json (your editor autocompletes it from the schema):
Then the target can be left out, and --scenario jump replaces the whole step list:
playproof check films every scenario and compares it with its baseline in playproof-baselines/, then runs monkey and devices. The first run writes the baselines (commit them). After that, any change to how a scenario moves fails the check with a compare.png that shows exactly what changed, until you accept it with --update. Baselines are kept per operating system, because fonts and anti-aliasing differ between them.
In CI
The action installs Chromium, runs playproof check (or any command via command and args), writes the summary to the job page and uploads the images as an artifact. Generate the Linux baselines once in CI (the first run writes them; download them from the artifact or run --update there) so they match the machine that checks them.
Steps
Used by --do and --script <file> (one step per line there). Separate steps with ;. Points are relative to the game area (the largest canvas, or --area <selector>).
Times: 500, 500ms, 1.5s.
Optional: a hook in your game
None of this is required, but four small functions make tests sharper:
Without it, use --ready "<js expression>" or --wait-for <selector> to wait for loading, and percentages for taps. examples/jumper shows the hook in a complete game.
How it works
- Virtual clock. Before any game script runs, playproof replaces
requestAnimationFrame, setTimeout/setInterval, performance.now and Date, and stops the CSS animation timeline. Time starts frozen. Advancing it runs timers and frames in exact order at 60 fps, which is why wait 2s takes milliseconds and why two runs produce identical frames.
- Repeatable loading. While the page loads, playproof advances frames itself. Whenever the game has work in flight that takes real time (network requests, WebAssembly compilation, image and audio decoding, IndexedDB), virtual time waits for it, so a slow machine or connection gives the same frames as a fast one. The settle time counts from the moment the game's render loop starts, which is when engines like Unity and Godot start their own clocks.
- Seeded randomness.
Math.random is seeded (--seed, or --seed off).
- Real input. Touch devices get real touch events (with the pointer and mouse events Chrome derives from them); others get mouse events. Key presses are held for a few frames so games that poll input see them.
- Images, not logs. Contact sheets, onion skins, storyboards and charts are drawn in a blank Chromium page, so playproof has a single dependency (
playwright-core) and no native image libraries.
Output
Each run writes to .playproof/<time>-<command>/ (or --out <dir>): the images, report.json with all the numbers (per-frame motion, step log, frame times), summary.txt, and the sampled frames in tiles/ for later comparisons. Add .playproof/ to your .gitignore. --json prints the report instead of the summary.
Exit codes: 0 nothing serious found, 1 errors found (crashes, failed requests, failed steps, frame drops on a real phone), 2 playproof itself could not run. That makes monkey and devices usable as CI checks.
Requirements
- Node.js 22.18 or newer.
- A Chromium-based browser: your installed Chrome or Edge, or
npx playproof install-browser. Pick one with --browser chromium|chrome|msedge|<path>.
- For
--android and --app: adb (Android platform-tools), a phone with USB debugging allowed, the screen on and unlocked.
Limitations
- Audio, video, Web Workers and WebAssembly threads keep real time; a game whose simulation runs in a worker will not be frame-exact.
- Local
perf numbers come from emulation without a GPU: good for comparing before and after a change, not for promising a frame rate. Use --headed for GPU rendering or --android for the real thing.
- Motion findings are heuristics. A sudden jump may be an intended cut and a one-frame flash may be a deliberate hit flash, which is why they are worded as things to look at.
- Chromium only, for now.
Development
The two example games are also the test targets: examples/jumper is a small, clean game; examples/buggy has eight planted bugs that the tests expect playproof to catch.
Issues and pull requests are welcome. See CONTRIBUTING.md.
License
MIT
