@selfage/screenshot_test_matcher

Install

npm install @selfage/screenshot_test_matcher

Overview

Written in TypeScript and compiled to ES6 with inline source map & source. See @selfage/tsconfig for full compiler options. Provides assertion on screenshots while generating/deleting diff files directly in browser context. It needs to be executed by @selfage/puppeteer_test_executor or @selfage/bundler_cli, which leverages Puppeteer to launch a browser page.

Basic usage

1import { asyncAssertScreenshot } from '@selfage/screenshot_test_matcher';
2
3async function main(): Promise<void> {
4  // Append some img to body.
5  document.body.style.margin = "0";
6  document.body.style.padding = "0";
7  let img = document.createElement("img");
8  let loaded = new Promise<void>((resolve) => {
9    img.onload = () => {
10      resolve();
11    };
12  });
13  img.src = ...
14  await loaded;
15  document.body.appendChild(img);
16
17  // Assert screenshot
18  await asyncAssertScreenshot(
19    'actual/file/path.png',
20    'expected/file/path.png',
21    'diff/file/path.png'
22  );
23}

The actual screenshot will be written to the actual/file/path.png. It will be deleted, if assertion succeeded. Otherwise, a diff file will also be written to diff/file/path.png. The file path is a relative path whose base path is provided when executed by @selfage/puppeteer_test_executor or @selfage/bundler_cli.

Advanced options

1  await asyncAssertScreenshot(
2    'actual/file/path.png',
3    'expected/file/path.png',
4    'diff/file/path.png',
5    {
6      // Default to 500ms. to wait for page to be stable before taking screenshot.
7      delay: 500,
8      // Default to false. Whether to take screenshot for the full page.
9      fullPage: true,
10      // The quality of the image, between 0-100. Not applicable to png images.
11      quality: 80,
12      // Default to 0.1. Range from 0 to 1. Smaller values make the comparison more sensitive.
13      threshold: .1;
14      // A list of rectangle areas to be excluded from comparison.
15      excludedAreas: [{
16        x: 10,
17        y: 20,
18        width: 100,
19        height: 200
20      }]
21    }
22  );