👁️ codeceptjs-visual-helper


A visual regression testing helper for CodeceptJS, providing pixel-by-pixel screenshot comparison with comprehensive support for Playwright, Puppeteer, WebDriver, Appium, WebDriverIO and TestCafe.

Overview 📖

This helper enables automated visual regression testing by comparing screenshots captured during test execution against established baseline images. When differences are detected, the helper generates diff images that highlight the discrepancies, facilitating rapid identification of unintended visual changes.

$3

- Multi-driver Support — Seamlessly integrates with Playwright, Puppeteer, WebDriver, Appium, WebDriverIO and TestCafe
- Configurable Tolerance — Define acceptable thresholds for pixel differences
- Ignore Regions — Exclude dynamic content areas from comparison
- Baseline Variations — Support multiple baseline versions for responsive or themed layouts
- Detailed Reporting — Comprehensive diff images and statistics for each comparison

Installation 📦

``bash
npm install @digital-commons-official/codeceptjs-visual-helper --save-dev
`

Configuration ⚙️

Add the helper to your codecept.conf.js configuration file:

`javascript
helpers: {
Playwright: {
// Your browser helper configuration
},
VisualHelper: {
require: '@digital-commons-official/codeceptjs-visual-helper',
baselineDir: './tests/screenshots/baseline/',
diffDir: './tests/screenshots/diff/',
actualDir: './tests/output/',
tolerance: 1.5,
threshold: 0.1
}
}
`

$3

| Option | Type | Default | Description | |
|--------------------------|-----------|---------------------------------|-----------------------------------------------------|----------------------------------------------------------------|
| baselineDir | string | ./tests/screenshots/baseline/ | Directory containing baseline images | |
| diffDir | string | false | ./tests/screenshots/diff/ | Directory for generated diff images; set to false to disable |
| actualDir | string | global.output_dir | Directory for captured screenshots | |
| tolerance | number | 0 | Permitted percentage of differing pixels (0–100) | |
| threshold | number | 0.1 | Pixelmatch colour comparison threshold (0–1) | |
| diffPrefix | string | Diff_ | Filename prefix for diff images | |
| saveIntermediateImages | boolean | false | Retain intermediate processing images for debugging | |
| captureActual | boolean | 'missing' | 'missing' | Automatic capture of actual screenshots |
| captureBaseline | boolean | 'missing' | 'missing' | Automatic capture of baseline images |

Usage 🚀

$3

The assertVisualMatch method compares the current viewport against a baseline image, failing the test if differences exceed the configured tolerance:

`javascript
// Basic full-page comparison
await I.assertVisualMatch('homepage');

// With custom tolerance
await I.assertVisualMatch('dashboard', { tolerance: 2.5 });

// Element-specific comparison
await I.assertVisualMatch('navigation', { element: '#main-nav' });

// Excluding dynamic regions
await I.assertVisualMatch('profile-page', {
ignoreRegions: [
{ x: 10, y: 10, width: 200, height: 50 } // Timestamp area
]
});
`

$3

The compareVisual method performs comparison and returns detailed results without throwing exceptions:

`javascript
const result = await I.compareVisual('checkout-form');

if (!result.isMatch) {
console.log(Visual difference detected: ${result.differencePercent}%);
console.log(Diff image saved to: ${result.diffImagePath});
}
`

$3

`javascript
// Capture current viewport as actual image
await I.captureScreenshot('landing-page');

// Capture and save as new baseline
await I.captureScreenshot('landing-page', 'baseline');

// Capture specific element
await I.captureScreenshot('footer', 'baseline', 'footer.main');
`

Comparison Options

| Option | Type | Description |
|------------------|----------|----------------------------------------------------------------|
| tolerance | number | Override the default tolerance for this comparison |
| compareWith | string | Specify a custom baseline image name |
| element | string | CSS selector for element-specific comparison |
| bounds | object | Bounding box { x, y, width, height } to constrain comparison |
| ignoreRegions | array | Array of regions [{ x, y, width, height }] to exclude |
| pixelmatchArgs | object | Override pixelmatch library options |

Baseline Variations

The helper supports multiple baseline variations using the tilde (~) suffix convention:

`bash
homepage.png # Primary baseline
homepage~dark.png # Dark theme variant
homepage~tablet.png # Tablet viewport variant
`

During comparison, the helper evaluates all matching variations and reports the best match, enabling comprehensive testing across different visual states.

Comparison Result Object

`typescript
interface VisualComparisonResult {
isMatch: boolean; // Whether difference is within tolerance
differencePercent: number; // Percentage of differing pixels
differentPixels: number; // Count of differing pixels
totalPixels: number; // Total pixels in the image
comparedPixels: number; // Pixels compared (excluding masked regions)
variationName: string; // Name of the matched variation
diffImagePath: string; // Path to the generated diff image
variations: Array<...>; // Results for all evaluated variations
}
`

Development 🛠️

$3

`bash
project/helper/
├── src/
│ ├── index.js # Main VisualHelper class
│ ├── index.d.ts # TypeScript declarations
│ ├── config/
│ │ └── defaults.js # Default configuration values
│ ├── drivers/
│ │ └── adapter.js # Browser driver abstraction layer
│ ├── services/
│ │ ├── comparator.js # Image comparison logic
│ │ └── path-builder.js # File path construction
│ └── utils/
│ ├── conversion.js # Type conversion utilities
│ ├── filesystem.js # File system operations
│ └── image.js # PNG manipulation functions
└── tests/
├── config/ # Configuration tests
├── services/ # Service tests
├── utils/ # Utility tests
└── integration/ # Visual comparison integration tests
`

$3

`bash


Execute all tests (unit, integration, e2e)

task test

Execute helper unit tests only

task project:test:helper

Execute integration tests with visual diff output

task project:test:helper:integration

Execute CodeceptJS end-to-end tests

task project:test:helper:e2e
`

$3

The integration tests generate actual diff images that may be inspected visually. Following execution, examine the project/helper/test-output/ directory to review:

- Identical comparison — Baseline and actual images with zero differences
- Different comparison — Images with intentional differences and highlighted diff output
- Tolerance comparison — Demonstration of strict versus lenient tolerance settings
- UI simulation — Complex page comparison with ignore regions

$3

The helper is designed to be published as an npm package. The following tasks support the release workflow:

`bash


Prepare the helper package (runs tests and shows pack contents)

task project:release:helper

Dry run of npm publish (no actual publish)

task project:release:helper:publish:dry

Publish to npm (requires npm login and correct permissions)

task project:release:helper:publish
``

Licence 📜

EUPL-1.2