@watershed-labs/assertions

Domain-specific assertion matchers for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/assertions extends Chai and Jest expect with matchers designed specifically for web, API, visual, and contract testing. It keeps assertion language consistent across every Watershed template — a QA engineer reading a create-dipper spec and a create-otter spec sees the same vocabulary and the same failure message format.

Installation

npm install @watershed-labs/assertions

Usage

import { expect } from '@watershed-labs/assertions';

// Accessibility
await expect(page).toBeAccessible('AA');

// Security headers
await expect(response).toHaveSecurityHeaders();

// Performance
await expect(response).toRespondWithin(300);

// Visual regression
await expect(page).toMatchVisualSnapshot('homepage-above-fold');

// Console cleanliness
await expect(page).toHaveNoConsoleErrors();

// Contract
await expect(interaction).toMatchContract(pactInteraction);

Matchers

| Matcher | Description | Used in | |---|---|---| | toBeAccessible(wcagLevel?) | Runs axe-core scan and asserts zero violations at the given WCAG level. Default 'AA'. | otter, egret, salamander | | toHaveSecurityHeaders(headers?) | Asserts OWASP-recommended headers are present and correctly set. | otter, dipper, pike | | toRespondWithin(ms) | Asserts the response time is below the given threshold in milliseconds. | dipper, beaver | | toMatchVisualSnapshot(label, options?) | Diffs the current page against a stored baseline via @watershed-labs/visual. | egret | | toHaveNoConsoleErrors() | Asserts no console.error entries were captured during the scenario. | otter, egret | | toMatchContract(interaction) | Asserts a Pact interaction was fulfilled correctly. | mussel |

Failure Messages

All matchers produce structured, human-readable failure messages that include the assertion context, the actual value, and the expected value. Diff output is formatted for terminal and included in the HTML report attachment.

Parallel Safety

Safe. The library is stateless — matchers receive all context as arguments and hold no instance state between calls.

Licence

MIT — part of the Watershed ecosystem.