Visual difference utility using Mocha, Chai, Puppeteer, and PixelMatch
Last updated 6 days ago by d2l-travis-deploy .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @brightspace-ui/visual-diff 
SYNC missed versions from official npm registry.


Build status

A visual difference utility using Mocha, Chai, Puppeteer, and PixelMatch.

screenshot of console log

screenshot of generated difference report


Install visual-diff.

npm i @brightspace-ui/visual-diff


Create Test Fixture

Create an .html file containing the element to be tested.


  • provide some whitespace around the element so screenshots do not clip other fixtures on the page if larger clip dimensions are used for the screenshot.
<!DOCTYPE html>
<html lang="en">
    <script src=".../node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
    <script type="module">
      import '.../button-icon.js';
    <d2l-button-icon id="normal" icon="d2l-tier1:gear" text="Icon Button"></d2l-button-icon>

Create Visual-Diff Tests

Create the visual-diff tests. Provide a unique name and the location where screenshots are saved. Use the VisualDiff context to navigate, take screenshots, and compare. Append the --golden arg to generate goldens.


  • use deviceScaleFactor to account for dpr (device-pixel-ratio), especially on retina display
  • run diffs with a different view-port size for media queries; avoid duplicating
  • bring page to front when testing focus (i.e. activate the browser tab)
  • reset focus between tests if not reloading the page
  • name screenshots using this.test.fullTitle()
  • use the standard Puppeteer API for all its greatness
  • wait for animations to complete before taking screenshot
const puppeteer = require('puppeteer');
const VisualDiff = require('visual-diff');

describe('d2l-button-icon', function() {

  const visualDiff = new VisualDiff('button-icon', __dirname);

  let browser, page;

  before(async() => {
    browser = await puppeteer.launch();
    page = await browser.newPage();
    await page.setViewport({width: 800, height: 800, deviceScaleFactor: 2});
    await page.goto(
      {waitUntil: ['networkidle0', 'load']}
    await page.bringToFront();

  after(() => browser.close());

  it('focus', async function() {
    await focus(page, '#normal');
    const rect = await visualDiff.getRect(page, '#normal');
    await visualDiff.screenshotAndCompare(page, this.test.fullTitle(), { clip: rect });


Running Tests

First, generate goldens using --golden arg before making changes.

"scripts": {
  "test:diff:golden": "mocha './test/**/*.visual-diff.js' -t 10000 --golden"

Make desired code changes, then run the tests to compare.

"scripts": {
  "test:diff": "mocha './test/**/*.visual-diff.js' -t 10000"

In Travis, commit the updates to the goldens.

"scripts": {
  "test:diff:golden:commit": "commit-goldens"


  • specify a longer Mocha timeout (while a screenshot is worth a 1000 tests, each screenshot is slower compared to a typical unit test)
  • use Mocha's grep option to run a subset (i.e. npm run test:diff -- -g some-pattern)
  • to update the goldens in Travis, do the following:
    1. In recent build for your repo, in top right corner click "More options" > "Trigger build"
    2. Enter the following parameters:
      • Branch: your current branch (NOT master)
      • Custom Commit Message: Updating goldens for <component>
      • Custom config: script: npm run build && npm run test:diff:golden && npm run test:diff:golden:commit
        • For a specific subset of goldens: script: npm run build && npm run test:diff:golden -- -g <component e.g., button> && npm run test:diff:golden:commit

Running in CI



Contributions are welcome, please submit a pull request!

Code Style

This repository is configured with EditorConfig rules and contributions should make use of them.

Current Tags

  • 1.0.1                                ...           latest (6 days ago)

6 Versions

  • 1.0.1                                ...           6 days ago
  • 1.0.0                                ...           7 days ago
  • 0.1.0                                ...           a month ago
  • 0.0.3                                ...           2 months ago
  • 0.0.2                                ...           5 months ago
  • 0.0.1                                ...           5 months ago
Today 2
This Week 2
This Month 32
Last Day 0
Last Week 30
Last Month 21
Dependencies (5)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |