playproof

playproof

Eyes and hands for browser games.

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.

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:

Install playproof from https://github.com/EmirhanOzl/playproof

It will pick the right command below for itself.

Claude Code

claude plugin marketplace add EmirhanOzl/playproof

claude plugin install playproof@playproof

Codex

codex plugin marketplace add EmirhanOzl/playproof

codex plugin add playproof@playproof

Gemini CLI

gemini extensions install https://github.com/EmirhanOzl/playproof

Cursor, OpenCode, GitHub Copilot and other agents

npx skills add EmirhanOzl/playproof

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:

{

"mcpServers": { "playproof": { "command": "npx", "args": ["-y", "playproof", "mcp"] } } }

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:

npx playproof frames http://localhost:5173 --device "Pixel 8" --do "tap 50%,50%" --duration 1s

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.

npx playproof frames ./dist --device "Pixel 8" --do "tap @Play; wait 400ms; key Space" --duration 700ms

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.

frames --compare: see what a change did

Film, change the code, film again with --compare . 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.

npx playproof frames http://localhost:5173 --do "tap @Play; key Space" --out .playproof/before

...change the jump...

npx playproof frames http://localhost:5173 --do "tap @Play; key Space" --compare .playproof/before

play: run a script, get a storyboard

npx playproof play http://localhost:5173 --device "Pixel 8" \

--do "shot title; tap @Play; wait 400ms; key Space; film 600ms; until window.playproof.state().screen === 'over' 20s; shot game over; tap @Retry; shot 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.

npx playproof monkey ./dist --device "Pixel 8" --steps 300

ERROR   Uncaught error: TypeError: Cannot read properties of undefined (reading 'activate')

during: action 13: tap 699,820, wait 119ms at HTMLCanvasElement. (http://127.0.0.1:52009/:51:40) Reproduce: playproof monkey "./dist" --seed 1 --steps 13 --device "Pixel 8"

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.

npx playproof devices http://localhost:5173

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 , 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.

npx playproof frames http://localhost:5173 --android --do "tap 50%,60%" --duration 800ms

npx playproof monkey --app com.example.mygame --steps 200 npx playproof perf --app com.example.mygame --duration 10s --monkey

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.

npx playproof perf ./dist --duration 10s --monkey

npx playproof perf http://localhost:5173 --android

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):

{

"$schema": "https://unpkg.com/playproof/schema/config.schema.json", "target": "http://localhost:5173", "device": "Pixel 8", "scenarios": { "title": { "duration": "800ms" }, "jump": { "do": "tap @Play; wait 400ms; key Space", "duration": "700ms", "zoom": "auto" } }, "check": { "monkey": { "steps": 200 }, "devices": true } }

Then the target can be left out, and --scenario jump replaces the whole step list:

npx playproof frames --scenario jump

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.

npx playproof check                 # everything

npx playproof check --only jump # one scenario npx playproof check --update # accept the current motion

In CI

- uses: actions/checkout@v7

• uses: EmirhanOzl/playproof@v0 with: start: npm run preview wait-for-url: http://localhost:4173

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 (one step per line there). Separate steps with ;. Points are relative to the game area (the largest canvas, or --area ).

| expect | fail the run unless the expression