Introduction

Dungbeetle captures your app's output as stable, reviewable JSON and produces semantic diffs instead of brittle pixel comparisons. Output is normalized (timestamps, UUIDs, and temp paths are masked) so baselines stay readable and survive cosmetic churn.

Why Dungbeetle

Most snapshot tools force a choice between two extremes: brittle pixel diffs that break on a one-pixel anti-aliasing shift, or unstructured text dumps that are impossible to review. Dungbeetle takes a third path — it normalizes each kind of output into deterministic JSON and compares the meaning:

• A terminal color change shows up as a styling diff, not a wall of escape codes.
• A renamed button is a single changed attribute, not a remove-plus-add cascade.
• A screenshot that shifts within tolerance simply passes.

The result is a baseline you can read in a pull request and a diff that tells you what changed.

What it captures

• 🖥️ Terminal — command output with ANSI normalization.
• 🌐 Web — structured DOM snapshots (url/html fetch by default, or a playwright driver when a browser is available).
• ⚡ Performance — baselines from k6 metrics, compared with numeric tolerance.
• 🪟 Desktop — accessibility-tree snapshots (role/name/state), with an experimental native macOS driver (driver: "macos-ax").
• 🔌 API — REST/GraphQL response snapshots (status, headers, JSON body) with structural diffs and numeric tolerance.
• 🔎 Check — snapshots of a tool's report on your app (routes, schema, scheduled jobs, static analysis) as a stable keyed record.
• 🎮 Game — scripted walkthroughs snapshotting semantic game state at named markers, deterministic and headless, with optional per-marker screenshots (Godot 4.x first).
• 🎭 Shared masking for dynamic values, and stable JSON diffs you can review in a pull request.

How baselines work

Baselines are committed under dungbeetle.snapshots/ so changes show up in code review. An optional self-hostable cloud server stores runs and baselines centrally when you'd rather not commit them.

Vocabulary

• Capture — the act of recording a target's current output.
• Snapshot — the artifact a capture produces.
• Baseline — the approved snapshot new output is compared against.
• Run — one CLI execution and its report (every result from one test/ci).
• Repository — the unit the cloud organizes around: one codebase, its baselines, and its runs.
• Walkthrough — a scripted flow through a game (inputs, waits, assertions) that a game target replays deterministically.
• Marker — a named point in a walkthrough where state (and optionally a screenshot) is captured; markers key the snapshot and the review UI.

Next steps

• Install Dungbeetle and check your environment.
• Follow the quick start to capture your first baseline.
• Learn the configuration format.
• Building on Dungbeetle? The CLI's developer docs (architecture, adding a capture type) live in the CLI repository.