Configuration

dungbeetle init writes a dungbeetle.config.json to your project root. Everything Dungbeetle does — what it captures, how it normalizes output, and how strict diffs are — comes from this one file.

This section breaks the config into focused pages:

• Lifecycle — the setup → start → wait → capture → teardown flow and the capture targets.
• Normalization — ANSI handling and mask rules that keep baselines stable.
• Comparison — numeric and pixel tolerances.
• Schema — the full field-by-field reference.

Simple

The smallest config that captures a terminal command and a web page:

{
  "version": 1,
  "project": { "name": "my-app" },
  "lifecycle": {
    "capture": [
      { "kind": "terminal", "name": "cli-help", "command": "my-app --help" },
      { "kind": "web", "name": "home", "url": "http://localhost:3000" }
    ]
  }
}

baselinesDir (dungbeetle.snapshots) and artifactsDir (.dungbeetle/artifacts) fall back to their defaults when omitted.

Advanced

A fuller config: a built-and-served app (lifecycle start / wait), a browser-backed web capture with a screenshot, mask rules, and loosened tolerances.

{
  "version": 1,
  "project": { "name": "my-app" },
  "baselinesDir": "dungbeetle.snapshots",
  "artifactsDir": ".dungbeetle/artifacts",
  "lifecycle": {
    "setup": ["npm run build"],
    "start": ["npm run preview"],
    "wait": { "url": "http://localhost:4173", "timeoutMs": 30000 },
    "capture": [
      { "kind": "terminal", "name": "cli-help", "command": "my-app --help" },
      {
        "kind": "web",
        "name": "home",
        "url": "http://localhost:4173",
        "driver": "playwright",
        "accessibility": true,
        "screenshot": true
      }
    ],
    "teardown": []
  },
  "normalization": {
    "ansi": "semantic",
    "masks": [
      {
        "name": "iso-timestamp",
        "pattern": "\\b\\d{4}-\\d{2}-\\d{2}T[\\d:.]+Z\\b",
        "replacement": "<iso-timestamp>"
      },
      {
        "name": "uuid",
        "pattern": "\\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\b",
        "replacement": "<uuid>"
      }
    ]
  },
  "comparison": {
    "numericTolerance": { "relative": 0.1 },
    "pixelTolerance": { "maxChangedRatio": 0.01 }
  }
}

Validate your config

Run dungbeetle doctor to validate the config, capture targets, baseline paths, missing HTML fixtures, and optional Playwright browser setup before you capture baselines.