Configuration schema

The full dungbeetle.config.json shape. See the Configuration overview for a narrative walkthrough.

Top-level fields

Field	Type	Description
version	number	Config schema version (currently 1).
project.name	string	Project name, used in reports.
baselinesDir	string	Where baselines are written (default dungbeetle.snapshots). Commit this.
artifactsDir	string	Where JSON/HTML reports go (default .dungbeetle/artifacts).
lifecycle	object	Capture lifecycle — see below.
normalization	object	ANSI handling and mask rules.
comparison	object	Numeric and pixel tolerances.

lifecycle

Runs in order: setup → start → wait → capture → teardown.

Field	Type	Description
setup	string[]	Shell commands run before capture.
start	string[]	Shell commands run as background processes for long-lived dev servers.
wait.command	string	Polled until it succeeds.
wait.url	string	Polled until it responds.
wait.timeoutMs	number	Readiness timeout (and default per-target timeout).
capture	target[]	The targets to snapshot.
teardown	string[]	Shell commands run after capture; start processes are then stopped.

Capture targets

Every target has a kind, a unique name, and an optional timeoutMs. Command-running kinds (terminal, check, performance, desktop) also take an optional cwd. Kind-specific options:

terminal

Field	Description
command	The command to run.

See Terminal snapshots.

check

Field	Description
tool	Which parser to use (laravel-routes, phpstan, pest, pint, …). Required.
command	Override the tool's default command.
output	Read tool output from this file instead of (or after) running command.

See Check snapshots.

web

Field	Description
url	Fetch and snapshot a live page (default driver, no browser).
html	Path to a local HTML fixture to snapshot instead.
driver	"playwright" for browser-backed capture.
accessibility	(Playwright) include an accessibility snapshot.
screenshot	(Playwright) capture a screenshot for pixel diffing.
screenshotFile	Ingest an existing image instead of capturing a page.
screenshotMode	"strict" (default) or "advisory" visual gating.
pixelTolerance	Visual tolerance override for this target.
browser.channel / browser.executablePath	(Playwright) browser selection.
viewport.width / viewport.height	(Playwright) viewport size.

See Web snapshots.

performance

Field	Description
tool	Which parser to use: k6 (default), ab, or autocannon.
script	A k6 script; Dungbeetle runs k6 run --summary-export.
summary	An existing tool-output file to ingest (no tool run).
command	The tool command to run (required for ab / autocannon).
metrics	Restrict the snapshot to selected metric names.
k6Path	k6 binary to use (default k6 on PATH).
env	Extra environment variables for the tool run.

See Performance baselines.

desktop

Field	Description
tree	A saved accessibility-tree JSON file.
command	A command that prints an accessibility tree as JSON.
driver	"macos-ax" for native macOS capture, or "ocr" for screenshot + OCR.
app	(macos-ax / ocr) the running app to capture / snapshot name.
maxDepth	(macos-ax) max tree depth to walk.
ocrFallback	Fall back to screenshot + OCR when the structured capture is empty or fails.
screenshot	(ocr) a saved image file to OCR.
screenshotCommand	(ocr) command that captures an image to the {out} path.
ocrCommand	(ocr) command that OCRs {image} to text on stdout (default: tesseract {image} stdout).

See Desktop snapshots.

api

Field	Description
url	The endpoint to call.
method	HTTP method (default GET, or POST with a body/query).
headers	Request headers, sent as-is.
body	Raw request body, sent verbatim.
query / variables	GraphQL sugar: posts the standard JSON envelope.
includeHeaders	Response headers to keep (default ["content-type"]).

See API snapshots.

game

Field	Description
engine	Adapter id; "godot" is the only engine today.
project	Engine project directory (contains project.godot).
walkthrough	Path to the walkthrough script (JSON).
mode	"semantic" (default, headless) or "visual" (per-marker screenshots).
enginePath	Engine binary (falls back to DUNGBEETLE_GODOT_PATH, then PATH).
seed / physicsFps	Determinism knobs (defaults 0 / 60).
screenshotMode	"advisory" (default) or "strict" visual gating.
pixelTolerance	Visual tolerance override for this target.
markers	Per-marker pixelTolerance overrides, keyed by marker name.

See Game snapshots.

normalization

Field	Type	Description
ansi	"semantic" | "strip"	Keep styling as structured segments, or text only.
masks	mask[]	{ name, pattern, replacement } — replace dynamic values everywhere.

comparison

Field	Type	Description
numericTolerance.absolute	number	Absolute epsilon for numeric equality.
numericTolerance.relative	number	Relative epsilon (fraction).
pixelTolerance.maxChangedRatio	number	Fraction of pixels (0–1) allowed to differ.
pixelTolerance.perChannelThreshold	number	Per-channel 0–255 delta tolerated per pixel.

Both tolerances default to {} (exact). See Comparison.