Visual difference utility using Mocha, Chai, Puppeteer, and PixelMatch
Last updated a month 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
npm i puppeteer


Note: Both the .html and the .js file need to end with the .visual-diff suffix for the tests to run correctly.

Create Test Fixture

Create an .html file containing the element to be tested. Below is an example .html file with the component 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. Below is an example of the visual-diff test for the above component.


  • use the createPage(browser) helper to create a page with the reduced motion preference, default viewport dimensions (800x800), and device scaling factor.
  • 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
  • use the prefers-reduced-motion: reduce media query in your component, or wait for animations to complete before taking screenshots
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 visualDiff.createPage(browser);
    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

In order to run this utility in CI, you need to add some secure environment variables to your Travis CI file.

The visual diff test reports will be stored in Amazon S3 and the Goldens are stored in the GitHub repository, and added to the current PR branch when initially generated or updated.

  1. Run the following commands with the appropriate secret value. For D2L projects, reach out to us to setup (recommended), otherwise use config/keys for your own Amazon S3 bucket and GitHub repo.
travis encrypt VISUAL_DIFF_S3_ID="SECRET" --add --com
travis encrypt VISUAL_DIFF_S3_SECRET="SECRET" --add --com
travis encrypt GITHUB_RELEASE_TOKEN="SECRET" --add --com
  1. Edit .travis.yml to include comments above the generated secrets, identifying what the secrets are.


  - secure: TOKEN
  - secure: TOKEN
  - secure: TOKEN


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.2.1                                ...           latest (a month ago)

11 Versions

  • 1.2.1                                ...           a month ago
  • 1.2.0                                ...           2 months ago
  • 1.1.1                                ...           6 months ago
  • 1.1.1-beta.0                                ...           6 months ago
  • 1.1.0                                ...           6 months ago
  • 1.0.1                                ...           8 months ago
  • 1.0.0                                ...           8 months ago
  • 0.1.0                                ...           9 months ago
  • 0.0.3                                ...           10 months ago
  • 0.0.2                                ...           a year ago
  • 0.0.1                                ...           a year ago
Today 0
This Week 0
This Month 11
Last Day 0
Last Week 11
Last Month 25
Dependencies (5)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |