# Dungbeetle

> Dungbeetle is a snapshot and visual regression testing tool — a free CLI plus self-hostable cloud — built for AI agents and the humans they work for.

Every link below is the raw-markdown twin of a docs page — the same clean URL
without the .md suffix serves the HTML, and honors `Accept: text/markdown`.
Other machine surfaces: the full docs as one file at https://dungbeetle.dev/llms-full.txt, the
OpenAPI 3.1 spec at https://dungbeetle.dev/openapi.yaml, an installable agent skill at
https://dungbeetle.dev/.well-known/skills/default/skill.md, and an MCP server (see Agent
integration below — agents authenticate via a human-approved device flow with
scoped, revocable tokens).

## Getting started

- [Introduction](https://dungbeetle.dev/guide/introduction.md): What Dungbeetle is and why: snapshot and visual regression testing with semantic JSON diffs instead of pixel comparisons, built for AI agents and their humans.
- [Installation](https://dungbeetle.dev/guide/installation.md): How to install the Dungbeetle CLI with npm, check the Node.js 22 requirement, and verify your setup with dungbeetle doctor before capturing snapshot baselines.
- [Quick start](https://dungbeetle.dev/guide/quick-start.md): Get from zero to snapshot testing in CI with three Dungbeetle CLI commands: init scaffolds a config, update captures baselines, and test compares output.
- [Walkthrough](https://dungbeetle.dev/guide/walkthrough.md): An end-to-end Dungbeetle walkthrough: run visual regression tests locally, commit snapshots for pull-request review, then approve diffs in the cloud UI.

## Cloud

- [Overview](https://dungbeetle.dev/cloud.md): How the Dungbeetle cloud server stores runs and baselines without committing them to your repo: auth, teams, pushing from CI, review and approval, analytics.
- [Pricing](https://dungbeetle.dev/pricing.md): Dungbeetle pricing explained: the CLI is free forever, the managed cloud uses flat tiers with unlimited seats, and self-hosting is an enterprise option.
- [Enterprise self-hosting](https://dungbeetle.dev/guide/self-hosting.md): How to self-host the Dungbeetle cloud server as an enterprise customer: what the BUSL-1.1 offering includes, deployment support, and how to request access.

## Configuration

- [Overview](https://dungbeetle.dev/configuration/index.md): How to configure Dungbeetle via dungbeetle.config.json: lifecycle, capture targets, normalization masks, and diff tolerances, with simple and advanced examples.
- [Lifecycle](https://dungbeetle.dev/configuration/lifecycle.md): How Dungbeetle's capture lifecycle works: setup builds, start background servers, wait for readiness, snapshot your targets, then teardown — all from config.
- [Normalization](https://dungbeetle.dev/configuration/normalization.md): Keep Dungbeetle snapshot baselines stable: ANSI styling modes and regex mask rules that replace timestamps and UUIDs so dynamic values don't cause false diffs.
- [Comparison](https://dungbeetle.dev/configuration/comparison.md): Tune how strict Dungbeetle diffs are: numeric tolerance for jittery metrics, and pixel comparison tolerance for screenshot visual regression tests.
- [Schema](https://dungbeetle.dev/configuration/schema.md): The complete Dungbeetle configuration schema: every dungbeetle.config.json field, capture target options for all seven kinds, tolerances, and mask rules.

## Examples

- [Agents](https://dungbeetle.dev/examples/agents.md): Give a swarm of coding agents a safety net with Dungbeetle: each one tests its changes against your baselines, and regressions land in your review queue, not on main.
- [Playwright](https://dungbeetle.dev/examples/playwright.md): 
- [Learn by example: Wildmatch](https://dungbeetle.dev/examples/wildmatch.md): 
- [Laravel](https://dungbeetle.dev/examples/laravel.md): Laravel snapshot testing walkthrough: install Dungbeetle in a fresh app, baseline the welcome page plus routes and schema, and read node-level semantic diffs.
- [VitePress](https://dungbeetle.dev/examples/vitepress.md): Snapshot-test a VitePress site with Dungbeetle: build and preview the docs, baseline the home page with the fetch driver, and catch DOM changes as semantic diffs.
- [Python](https://dungbeetle.dev/examples/python.md): Python snapshot testing with Dungbeetle: baseline a FastAPI route using the zero-dependency fetch driver, catch changes as semantic diffs, and snapshot CLIs too.
- [Go](https://dungbeetle.dev/examples/go.md): Go snapshot testing with Dungbeetle: baseline a net/http service page, read a node-level semantic diff when a handler changes, and snapshot CLI output too.
- [Godot](https://dungbeetle.dev/examples/godot.md): Godot game testing with Dungbeetle: script a walkthrough, baseline gameplay state headlessly, catch changes as a two-line semantic diff, and prove determinism.

## Capture types

- [Terminal](https://dungbeetle.dev/capture-types/terminal.md): How Dungbeetle terminal snapshots capture a command's exit code, stdout and stderr with ANSI styling normalized, and diff them at the word level.
- [Web](https://dungbeetle.dev/capture-types/web.md): Snapshot web pages as structured DOM with Dungbeetle: fetch or Playwright capture, web screenshot testing with pixel tolerance, and accessibility snapshots.
- [Check](https://dungbeetle.dev/capture-types/check.md): Snapshot your app's shape with Dungbeetle check targets: Laravel routes, database schema, test results, PHPStan and Pint findings — drift shows as a named diff.
- [Performance](https://dungbeetle.dev/capture-types/performance.md): Set performance baselines with Dungbeetle: snapshot k6, Apache Benchmark, or autocannon load-test metrics and fail regressions beyond a numeric tolerance.
- [Desktop](https://dungbeetle.dev/capture-types/desktop.md): Snapshot desktop app UIs as accessibility trees with Dungbeetle: ingest a tree, use the native macOS driver, or fall back to screenshot OCR for canvas UIs.
- [API](https://dungbeetle.dev/capture-types/api.md): API contract testing with Dungbeetle: snapshot REST and GraphQL responses — status, headers, JSON body — and review changes as semantic diffs, not text walls.
- [Game](https://dungbeetle.dev/capture-types/game.md): Visual and semantic regression testing for games with Dungbeetle: script a Godot walkthrough, snapshot game state at markers, and diff deterministic runs.
- [Raw](https://dungbeetle.dev/capture-types/raw.md): 

## Migration guides

- [Overview](https://dungbeetle.dev/migrate/index.md): Migration guides for moving to Dungbeetle from Lost Pixel, Wraith, BackstopJS or Loki — why teams leave pixel-only tools and the steps every switch shares.
- [From Lost Pixel](https://dungbeetle.dev/migrate/lost-pixel.md): Migrate from Lost Pixel to Dungbeetle: Lost Pixel is sunsetting after joining Figma — map lostpixel.config.ts to Dungbeetle and replace the SaaS review UI.
- [From Wraith](https://dungbeetle.dev/migrate/wraith.md): Migrate from Wraith to Dungbeetle: the BBC tool is archived and PhantomJS-based — translate your YAML config to a maintained Playwright-powered alternative.
- [From BackstopJS](https://dungbeetle.dev/migrate/backstopjs.md): BackstopJS alternative: migrate backstop.json scenarios and viewports to Dungbeetle, a maintained tool with structured diffs and central hosted review.
- [From Loki](https://dungbeetle.dev/migrate/loki.md): Migrate from Loki to Dungbeetle: outgrow Storybook-only pixel diffs — point web targets at story iframe URLs and add structured diffs plus hosted review.

## Compare

- [vs Playwright](https://dungbeetle.dev/compare/playwright.md): Playwright visual regression testing with toHaveScreenshot — how to do it well, where it stops scaling, and how Dungbeetle adds review, baselines, and agent auth.
- [vs Percy](https://dungbeetle.dev/compare/percy.md): An honest Percy alternative comparison: BrowserStack's cross-browser screenshot testing vs Dungbeetle's flat-tier, agent-native semantic snapshots.
- [vs Chromatic](https://dungbeetle.dev/compare/chromatic.md): An honest Chromatic alternative comparison: Storybook-first component visual testing vs Dungbeetle's flat-tier, agent-native snapshot testing for web and beyond.
- [Best tools 2026](https://dungbeetle.dev/compare/best-visual-regression-testing-tools.md): An honest guide to the best visual regression testing tools in 2026 — Playwright, Percy, Chromatic, Applitools, BackstopJS, Argos, and Dungbeetle compared fairly.

## CLI

- [Overview](https://dungbeetle.dev/cli/index.md): Dungbeetle CLI command reference: init, update, test, ci, flake and doctor, plus login, push, push-baselines and anon — common flags and report statuses.
- [Local commands](https://dungbeetle.dev/cli/local.md): Run Dungbeetle locally with no cloud account: the init, update, test and ci commands, plus flake to catch unstable targets and doctor to validate your setup.
- [Cloud commands](https://dungbeetle.dev/cli/cloud.md): Dungbeetle cloud commands: login and logout for agent tokens, push runs and baselines to a cloud server, credential resolution, and anon one-off share links.

## API

- [Overview](https://dungbeetle.dev/api/index.md): Dungbeetle HTTP API reference: authentication with agent tokens or Basic client credentials, error codes, health probes, and the full /api/v1 endpoint list.
- [Runs](https://dungbeetle.dev/api/runs.md): Dungbeetle runs API: POST /api/v1/runs to ingest a CI run report, list and fetch stored runs, and record approve/reject reviews that can promote baselines.
- [Screenshots](https://dungbeetle.dev/api/screenshots.md): Dungbeetle screenshots API: fetch a run's PNGs by artifact id, then probe and PUT content-addressed sha-256 uploads so unchanged images transfer zero bytes.
- [Baselines](https://dungbeetle.dev/api/baselines.md): Dungbeetle baselines API: upload versioned baseline snapshots per target, list targets, and fetch latest or historical versions, deduped by content digest.
- [Repository & usage](https://dungbeetle.dev/api/repository.md): Dungbeetle repository endpoints: identify the authenticated repo, read pass-rate and flakiness analytics, and check current-period usage against plan limits.
- [Status codes & limits](https://dungbeetle.dev/api/limits.md): Dungbeetle API status codes, plan limits, and retention: when writes return 402, how Free hard limits and paid fair-use differ, and the Stripe webhook.

## MCP

- [Overview](https://dungbeetle.dev/mcp/index.md): What the Dungbeetle MCP server does: coding agents like Claude Code and Cursor triage visual regression runs via low-token diff summaries; humans approve baselines.
- [Setup](https://dungbeetle.dev/mcp/setup.md): How to set up the Dungbeetle MCP server: mint a scoped agent token with dungbeetle login or use CI client credentials, then configure any MCP client over stdio.
- [Agent authentication](https://dungbeetle.dev/mcp/auth.md): How Dungbeetle agent authentication works: RFC 8628 device-flow login mints scoped, revocable agent tokens a human approves, audits, and can revoke any time.
- [Tools & agent loop](https://dungbeetle.dev/mcp/tools.md): Reference for the Dungbeetle MCP tools and agent loop: list runs, read low-token semantic diffs, check usage, then approve or reject with human confirmation.

## Agent tools

- [Claude Code](https://dungbeetle.dev/mcp/claude-code.md): Claude Code MCP setup for Dungbeetle: mint an agent token, add the server with claude mcp add or a project .mcp.json, and triage visual regressions from chat.
- [Cursor](https://dungbeetle.dev/mcp/cursor.md): Connect Cursor to the Dungbeetle MCP server via .cursor/mcp.json so agent mode can triage snapshot runs and read semantic diffs; approval stays with you.
- [Codex](https://dungbeetle.dev/mcp/codex.md): Configure OpenAI Codex for Dungbeetle: add the MCP server to ~/.codex/config.toml, inject the agent token in sandboxed runs, and teach the loop via AGENTS.md.
- [Gemini CLI](https://dungbeetle.dev/mcp/gemini-cli.md): Gemini CLI MCP setup for Dungbeetle: add the server to ~/.gemini/settings.json, verify with /mcp, and let Gemini triage visual regression runs on a scoped token.

## Reference

- [Security](https://dungbeetle.dev/reference/security.md): How Dungbeetle protects your data: tenant isolation, encryption at rest, scoped agent tokens, a small dependency surface, and how to report a vulnerability.
- [Licensing](https://dungbeetle.dev/reference/licensing.md): How Dungbeetle is licensed: the CLI under FSL-1.1 and the cloud server under BUSL-1.1 — both source-available, both converting to Apache-2.0 over time.
- [Docs for agents](https://dungbeetle.dev/docs-for-agents.md): Every machine-readable surface dungbeetle.dev exposes for AI agents and bots: llms.txt, markdown docs endpoints, OpenAPI spec, MCP server, and device-flow auth.
- [Changelog](https://dungbeetle.dev/changelog.md): What's new in Dungbeetle: release notes for the visual regression testing CLI and cloud — new capture types, agent features, and fixes, with an RSS feed.

## Optional

- [Privacy Policy](https://dungbeetle.dev/legal/privacy.md): Privacy policy for the hosted Dungbeetle Cloud service: what account, content, billing and log data is collected, retention windows, and how to delete data.
- [Terms of Service](https://dungbeetle.dev/legal/terms.md): Terms of service for the hosted Dungbeetle Cloud service: accounts, customer content ownership, acceptable use, plans and billing, and self-hosting licenses.