Module: runner/visualDiff

DIF-001 — Visual regression diffing helpers.

Wraps pixelmatch + pngjs to compare a freshly-captured screenshot against a saved baseline, persist a side-by-side diff image, and return a structured result the test runner can attach to a step.

A baseline is created lazily on the first run that produces a screenshot for a given (testId, stepNumber, browser) tuple. Subsequent runs compare against that baseline; if the pixel difference ratio exceeds VISUAL_DIFF_THRESHOLD the step is flagged visualRegression: true.

Directory layout

artifacts/
  baselines/<testId>/<browser>/step-<N>.png
  diffs/<runId>-<testId>-step<N>.png

Exports

  • ensureBaseline — Create-or-read the baseline image + DB row.
  • diffScreenshot — Diff a captured PNG against the saved baseline.
  • acceptBaseline — Promote a captured screenshot to the new baseline.
Source:

Methods

(static) acceptBaseline(args) → {Object}

Promote a previously-captured screenshot to the new baseline for a test step.

Called from the "Accept visual changes" action on the run detail page.

Parameters:
Name Type Description
args Object
Properties
Name Type Attributes Default Description
testId string
browser string <optional>
 "chromium"
stepNumber number <optional>
 0
sourceAbsPath string

Absolute filesystem path to the PNG to promote.
Source:
Throws:

When the source file cannot be read.

Type
Error
Returns:
Type
Object

(static) diffScreenshot(args) → {VisualDiffResult}

Diff a freshly-captured screenshot against the saved baseline.

  • If no baseline exists yet, the capture is promoted to the baseline and status = "baseline_created" is returned.
  • If dimensions differ the diff short-circuits with status = "error".
  • Otherwise pixelmatch runs and status is "match" or "regression" depending on VISUAL_DIFF_THRESHOLD.
Parameters:
Name Type Description
args Object
Properties
Name Type Attributes Default Description
runId string
testId string
browser string <optional>
 "chromium"
stepNumber number <optional>
 0
pngBuffer Buffer

Raw PNG bytes of the captured screenshot.
Source:
Returns:
Type
VisualDiffResult

(static) ensureBaseline(testId, stepNumber, browseropt) → {Object|null}

Read the baseline image from disk for a given test + step, if one exists.

Parameters:
Name Type Attributes Default Description
testId string
stepNumber number
browser string <optional>
 "chromium"
Source:
Returns:
Type
Object | null

(inner) baselineAbsPath(testId, browser, stepNumber) → {string}

Absolute path to the baseline PNG for a given test + browser + step.

Parameters:
Name Type Description
testId string
browser string
stepNumber number
Source:
Returns:
Type
string

(inner) baselinePublicPath(testId, browser, stepNumber) → {string}

Public (URL-safe) artifact path for a baseline.

Parameters:
Name Type Description
testId string
browser string
stepNumber number
Source:
Returns:
Type
string

(inner) persistBaseline(testId, stepNumber, browser, pngBuffer) → {Object}

Create baseline directory + PNG file and persist a DB row.

Parameters:
Name Type Description
testId string
stepNumber number
browser string
pngBuffer Buffer
Source:
Returns:
Type
Object

(inner) readPng(absPath) → {Object|null}

Load a PNG from disk, returning null on error.

Parameters:
Name Type Description
absPath string
Source:
Returns:
Type
Object | null

Type Definitions

VisualDiffResult

Type:
  • Object
Properties:
Name Type Attributes Description
status "baseline_created" | "match" | "regression" | "error"
diffPixels number <optional>

Number of differing pixels.
totalPixels number <optional>

Total pixels compared.
diffRatio number <optional>

diffPixels / totalPixels (0..1).
threshold number <optional>

Threshold used (mirrors VISUAL_DIFF_THRESHOLD).
baselinePath string <optional>

Public artifact path of the baseline PNG.
diffPath string <optional>

Public artifact path of the diff PNG.
message string <optional>

Human-readable reason when status = "error".
Source: