@watershed-labs/screenshot

Screenshot capture, image processing, PII blur, and reporter attachment for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/screenshot is the baseline image capability shared by every Watershed template that touches a browser or device. create-otter uses it for failure evidence. create-salamander uses it for mobile failure captures. create-egret uses it as the capture layer underneath @watershed-labs/visual.

This package captures and attaches. It knows nothing about baselines, diffs, or thresholds. If you find yourself adding comparison logic here, it belongs in @watershed-labs/visual instead.

Installation

npm install @watershed-labs/screenshot

Usage

import { Screenshot } from '@watershed-labs/screenshot';

const shot = new Screenshot(driver);

// Full-page capture — attached to reporter automatically
await shot.capture({ label: 'checkout-failure', fullPage: true });

// Viewport only
await shot.capture({ label: 'header-state', fullPage: false });

// Element-scoped capture
const element = await driver.findElement(By.css('[data-testid="error-banner"]'));
await shot.captureElement(element, { label: 'error-banner' });

// With PII blur — blurs matching elements before capture, restores after
await shot.capture({
    label: 'user-profile',
    fullPage: true,
    blur: ['[data-testid="email"]', '[data-testid="card-number"]']
});

// Format conversion
await shot.capture({ label: 'summary', format: 'webp', quality: 85 });

API

| Method | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | | capture(options) | Full-page or viewport screenshot. Attaches to @watershed-labs/reporter with label, timestamp, and worker ID. | | captureElement(element, options) | Crops to the bounding box of a specific WebElement. | | blur(selectors) | Applies a CSS blur to matching elements before capture. Automatically reverses after capture. | | resize(width, height) | Resizes the output image. Useful for normalising across different display densities. | | convert(format, quality?) | Converts output to png, jpeg, or webp. |

Options

| Option | Type | Default | Description | | ---------- | ------------------------------------- | -------- | ------------------------------------------------ | | label | string | required | Filename label for the captured image | | fullPage | boolean | true | Capture full scrollable page or viewport only | | format | 'png' \| 'jpeg' \| 'webp' \| 'avif' | 'avif' | Output image format (AVIF ~40-60KB per 1280x720) | | quality | number | 90 | JPEG or WebP quality (1–100) | | blur | string[] | [] | CSS selectors of elements to blur before capture |

Dependencies

• sharp (Apache 2.0) — image processing and format conversion

Parallel Safety

Safe. Each instance is scoped to a single driver session. Worker ID is stamped on every captured image filename automatically to prevent output file collisions across parallel workers.

Licence

MIT — part of the Watershed ecosystem.