Snapshot rules and ignore regions

Keep comparison settings in your repository or draw regions in the review UI.

Requires CLI 0.7.0 or newer. npm distribution is currently pending; pilots can install the supplied release tarball with npm install --save-dev ./difora-0.7.0.tgz.

Repository config

Create difora.config.json in the screenshot directory or working directory. An explicit --config ./config/difora.json takes priority; otherwise the screenshot directory wins over the working directory. No config means no repository rules. Invalid config fails before upload with exit code 2.

{
  "$schema": "https://difora.eu/schema/difora-config-v1.json",
  "version": 1,
  "rules": [
    {
      "match": "pages/**",
      "threshold": 0.1,
      "changeRatioThreshold": 0.001,
      "ignore": [{ "x": 10, "y": 10, "width": 100, "height": 40 }]
    }
  ]
}

Download the JSON schema. The CLI never downloads a schema during upload. Config is at most 1 MB, with 200 rules and 50 regions per rule. Unknown fields are rejected.

Patterns and priority

Names are relative PNG paths without the extension, such as pages/home@1280. Matching is case-sensitive. * stays within one directory, ** crosses directories, **/ also matches no directory, and ? matches one non-slash character. Brackets and braces are literal. A backslash escapes *, ? or another backslash; double it in JSON. Patterns are limited to 600 characters.

A matching repository rule wins over all UI rules. Within each source, more literal characters wins, then fewer wildcard tokens; ties use the first config entry or oldest saved UI rule. Only one rule is selected. Its omitted threshold fields inherit the project defaults; they do not inherit another rule. Omitted ignore regions mean none. Disabled UI rules do not match.

Thresholds range from 0 to 1. threshold is pixel colour tolerance; changeRatioThreshold is the permitted fraction of changed comparable pixels. Zero is valid for both. Identical image hashes stay identical.

Coordinates and comparison

Regions use integer screenshot pixels, not CSS pixels: x, y, width, height, each from 0 to 30,000,000. The editor accounts for zoom and display pixel density. Zero-area and out-of-bounds regions have no effect. Regions are clipped to the overlap of baseline and current images; overlapping regions are counted once.

The ratio is differing pixels divided by the united image canvas minus ignored overlap. A completely masked same-size image has ratio zero. A size change still counts as changed. Hatched areas in the diff show ignored pixels; original images are preserved. The comparison canvas is limited to 30 million pixels.

Save rules in the app

Open Settings → Rules to add, edit, disable or delete rules and test snapshot names against saved rules and project defaults. Any organization member can manage rules; changes are audited.

On a build, select a snapshot, choose Ignore regions, and drag rectangles over the current image. Use zoom, Fit and Pan, or delete individual rectangles. Save creates an exact-name UI rule or updates the existing exact-name rule. Then use Re-run comparison. Approved builds apply changes on the next upload. Repository rules still take priority; edit the config and upload again to change them.

The review caption records the applied source, pattern, thresholds and masked percentage. Changing a saved rule does not silently change an existing result.

Parallel builds and retries

Every shard must upload the same complete rules array, in the same order. The first manifest pins it; conflicting manifests return 409. Retries retain the predecessor's config. To change rules for a parallel group, use a new parallel ID and upload all shards. A web rerun applies the uploaded repository config with the current UI rules and project defaults.