Quick start

Three commands take you from nothing to a baseline that runs in CI.

dungbeetle init     # scaffold dungbeetle.config.json
dungbeetle update   # capture targets and write the first baselines
dungbeetle test     # compare current output against the baselines

What each step does

1. dungbeetle init writes a starter dungbeetle.config.json in the current directory.
2. dungbeetle update captures every configured target and writes baselines under dungbeetle.snapshots/. Commit these — they're the reviewable record of your app's output.
3. dungbeetle test captures current output, compares it against the baselines, and exits non-zero on any difference — so it drops straight into CI.

JSON/HTML reports are written to the paths you pass via --json / --html. A failing web test shows a semantic DOM diff by default; before/after screenshots are embedded too when they were captured (the Playwright driver — the default fetch driver does DOM-only, no browser).

First-run behavior

If baselines don't exist yet, dungbeetle test fails with missing results and tells you which baseline path is absent. Run dungbeetle update to create them, then dungbeetle test passes on unchanged output.

The report statuses are updated, passed, failed, missing, and error.

In CI

Use dungbeetle ci for machine-readable output:

dungbeetle ci --json report.json --html report.html

Add --json-only to suppress HTML and console output when you only need the JSON.

Working with a subset of targets

Pass --target <name...> to update, test, or ci to work with one or more named targets instead of the whole suite:

dungbeetle update --target home nav
dungbeetle test   --target home

Try the examples

The repository ships runnable examples under examples/ — demo, perf, desktop, and p1/playwright. They include committed baselines, so test and ci pass without a prior update:

dungbeetle update --config examples/demo/dungbeetle.config.json   # refresh baselines
dungbeetle test   --config examples/demo/dungbeetle.config.json   # compare

Next

• Follow the full walkthrough — local, commit-to-repo, and cloud review in one pass.
• Learn the full configuration format.
• Pick a capture type: Terminal, Web, Performance, Desktop.
• Store baselines and runs centrally with the cloud server.