Agentic Visual Testing: Setting Up

@blazediff/agent screenshots your routes, diffs them against baselines committed to your repo, and hands the diffs it cannot classify to your coding agent for a verdict. Claude Code, Cursor and Codex are supported out of the box. There is no hosted service, no API key in the default flow, and no screenshot leaves your machine.

The workflow splits in two, on purpose:

• Authoring happens on your machine. You capture baselines, add masks, write harnesses, and accept intentional changes. All of it is blocked in CI.
• Checking happens in CI. One command re-captures, diffs, and fails the build on a regression.

This page covers authoring, from nothing to a committed set of baselines. Then read Running in CI.

1. Install

npm install --save-dev @blazediff/agent

pnpm add --save-dev @blazediff/agent

yarn add --dev @blazediff/agent

bun add --dev @blazediff/agent

The first run offers to install a bundled Playwright Chromium. No sudo, no npx playwright install --with-deps.

blazediff-agent browsers install --check --json   # check
blazediff-agent browsers install                  # install if missing

2. Onboard

onboard writes .blazediff/config.json from your dev script, sets up .gitignore, installs Chromium, and installs the playbook into whichever coding-agent stack lives in your project.

# Setup only. Baselines are captured explicitly in step 4.
blazediff-agent onboard --no-capture

It detects the stack automatically (Claude Code, Codex, Cursor). Pass --stack <name> to be explicit, or --stack local to install the local Moondream and Qwen judge when there is no coding agent in the project.

3. Start the dev server

blazediff-agent serve-status --detach --json   # waits up to 60s for the port

Already have a running URL, such as staging? Skip the dev server and point the agent at it: blazediff-agent onboard --url https://staging.example.com.

4. Capture baselines

Pipe in a JSON list of routes. One capture call screenshots them all and writes the manifest plus the baseline PNGs.

cat <<'EOF' | blazediff-agent capture --stdin --mode baseline --json
[
  {"id": "home", "url": "/", "mask": [".timestamp"]},
  {"id": "pricing", "url": "/pricing"}
]
EOF

Then tear the dev server down. This step is mandatory:

blazediff-agent serve-status --kill --json

What ends up in .blazediff/

config.json is committed and drives every later run:

{
  "devServer": { "command": "pnpm dev", "port": 3000, "readyTimeoutMs": 60000 },
  "framework": "next",
  "packageManager": "pnpm",
  "baseUrl": "http://127.0.0.1:3000"
}

manifest.json is written by capture. Never edit it by hand. Per-route behavior, such as logging in or clicking through a flow, belongs in a harness rather than in config.

Next

• Running in CI: the one command CI runs, and what its exit codes mean
• Judging and harnesses: what to do when a check fails
• Every command and flag: @blazediff/agent reference