@watershed-labs/visual

Baseline management, pixel diffing, threshold assertion, and HTML diff reporting for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/visual is the visual regression engine for create-egret. It depends on @watershed-labs/screenshot for image capture and owns everything else: baseline storage, pixel diffing via pixelmatch, threshold assertion, and a self-contained HTML diff report.

All visual comparison is fully self-hosted. No screenshots leave the machine by default. Percy is supported as an opt-in adapter for teams that want managed cloud diffing and have no data residency constraints — it is never the default.

Installation

npm install @watershed-labs/visual

Usage

import { VisualComparator } from '@watershed-labs/visual';

const visual = new VisualComparator(driver, {
    baselineDir:    './visual-baselines',
    threshold:      0.01,    // 1% pixel difference tolerance
    updateBaseline: process.env.UPDATE_BASELINE === 'true',
});

// Assert full page matches baseline — creates baseline on first run
await visual.assertMatch('homepage-above-fold');

// Assert with a custom threshold for a known dynamic area
await visual.assertMatch('dashboard-charts', { threshold: 0.05 });

// Assert a specific element only
const element = await driver.findElement(By.css('[data-testid="product-card"]'));
await visual.assertElementMatch(element, 'product-card-default');

// Via @watershed-labs/assertions
await expect(page).toMatchVisualSnapshot('homepage-above-fold');

API

| Method | Description | |---|---| | assertMatch(label, options?) | Captures current state and diffs against the stored baseline. Creates the baseline on first run. Fails if the diff exceeds the threshold. | | assertElementMatch(element, label, options?) | Scoped to a single WebElement. Uses @watershed-labs/screenshot captureElement internally. | | updateBaselines() | Overwrites all stored baselines with the current screenshots. Triggered by UPDATE_BASELINE=true. | | getDiffReport() | Returns the HTML diff report as a string. Attached to @watershed-labs/reporter automatically on any failure. | | setAdapter(adapter) | Swaps the baseline storage adapter. |

Storage Adapters

| Adapter | Import | Description | |---|---|---| | LocalAdapter | default | Reads and writes baselines to the local filesystem. Default. | | S3Adapter | @watershed-labs/visual/adapters/s3 | Stores baselines in AWS S3. Requires AWS_BUCKET env var. | | GCSAdapter | @watershed-labs/visual/adapters/gcs | Stores baselines in Google Cloud Storage. | | PercyAdapter | @watershed-labs/visual/adapters/percy | Sends screenshots to Percy/BrowserStack. Opt-in only — see below. |

Updating Baselines

Baselines are updated by setting UPDATE_BASELINE=true before running the suite:

UPDATE_BASELINE=true npx cucumber-js

Commit the updated baselines to version control. Baseline updates should always be a deliberate, reviewed change — not an automatic CI step.

Percy — Opt-In Only

Percy must never be the default adapter. To opt in:

import { PercyAdapter } from '@watershed-labs/visual/adapters/percy';

const visual = new VisualComparator(driver, {
    adapter: new PercyAdapter({ token: process.env.PERCY_TOKEN }),
});

Teams opting in accept that screenshots will be transmitted to BrowserStack's infrastructure. This is incompatible with GDPR data residency requirements, government classification policies, and most financial institution data handling rules.

Dependencies

• pixelmatch (MIT) — pixel-level image comparison
• @watershed-labs/screenshot — image capture

Parallel Safety

Safe. Each worker reads and writes to worker-scoped baseline paths to prevent race conditions. Baselines are reconciled in the AfterAll coordinator phase before the final report is generated.

Licence

MIT — part of the Watershed ecosystem.