How to Build Reliable Canvas E2E Tests with Puppeteer and Pixelmatch

Introduction

When developing a Canvas‑related tool library, the author needed end‑to‑end (E2E) tests that verify rendering results. Existing approaches either mock Canvas APIs in Node or use heavy browser‑based tests, but neither fully satisfies the need for reliable visual verification.

Background

Two common E2E strategies were identified: pure data validation in Node (e.g., jest‑mock‑canvas) and browser‑based visual comparison (e.g., Cypress). The latter is more accurate but requires a real browser, which can be cumbersome for CI pipelines.

Three.js E2E Approach

Three.js’s own E2E tests on GitHub illustrate a two‑step process:

1. Capture Expected Snapshot

Start a static HTTP server serving local Three.js examples.

Use a headless browser to load the example and take a screenshot of the correct 3D rendering.

Stop the server.

2. Compare Against New Snapshot

Start the static server again.

Load the updated example with a headless browser, capture a screenshot, and compare pixel‑by‑pixel with the stored snapshot using pixelmatch. If the difference exceeds 0.5 % the test fails.

Stop the server.

Required npm Packages

puppeteer – provides the headless browser.

jimp – image processing.

pixelmatch – pixel‑level image comparison.

serve‑handler – static file server.

Implementation

1. Generate Expected Snapshot

const path = require('path');
const http = require('http');
const jimp = require('jimp');
const puppeteer = require('puppeteer');
const serveHandler = require('serve-handler');

const port = 3001;
const width = 400;
const height = 400;
const snapshotPicPath = path.join(__dirname, 'snapshot', 'expect.png');

async function main() {
  const server = http.createServer((req, res) => serveHandler(req, res, {
    public: path.join(__dirname, '..', 'src'),
  }));
  server.listen(port, async () => {
    try {
      const browser = await puppeteer.launch();
      const page = await browser.newPage();
      await page.setViewport({ width: width, height: height });
      await page.goto(`http://127.0.0.1:${port}/index.html`);
      const buf = await page.screenshot();
      await browser.close();
      server.close();

      (await jimp.read(buf)).scale(1).quality(100).write(snapshotPicPath);
      console.log('create snapshot of screen success!');
    } catch (err) {
      server.close();
      console.error(err);
      process.exit(-1);
    }
  });
  server.on('SIGINT', () => process.exit(1));
}
main();

2. Run E2E Test

const fs = require('fs');
const path = require('path');
const http = require('http');
const assert = require('assert');

const jimp = require('jimp');
const pixelmatch = require('pixelmatch');
const puppeteer = require('puppeteer');
const serveHandler = require('serve-handler');

const port = 3001;
const width = 400;
const height = 400;
const snapshotPicPath = path.join(__dirname, 'snapshot', 'expect.png');

let server = null;
let browser = null;

describe('E2E Testing', function () {
  before(function (done) {
    server = http.createServer((req, res) => serveHandler(req, res, {
      public: path.join(__dirname, '..', 'src'),
    }));
    server.listen(port, done);
    server.on('SIGINT', () => process.exit(1));
  });

  it('testing...', function (done) {
    this.timeout(1000 * 60);

    const expectDiffRate = 0.005;

    new Promise(async (resolve) => {
      browser = await puppeteer.launch();
      const page = await browser.newPage();
      await page.setViewport({ width: width, height: height });
      await page.goto(`http://127.0.0.1:${port}/index.html`);
      const buf = await page.screenshot();
      const actual = (await jimp.read(buf)).scale(1).quality(100).bitmap;
      const expected = (await jimp.read(fs.readFileSync(snapshotPicPath))).bitmap;
      const diff = actual;
      const failPixel = pixelmatch(expected.data, actual.data, diff.data, actual.width, actual.height);
      const failRate = failPixel / (width * height);
      resolve(failRate);
    }).then((failRate) => {
      assert.ok(failRate < expectDiffRate);
      done();
    }).catch(done);
  });

  after(function () {
    browser && browser.close();
    server && server.close();
  });
});

3. Visualize Differences

When the failure rate exceeds the threshold, a diff image is saved with highlighted differences for easy inspection.

const fs = require('fs');
const path = require('path');
const http = require('http');
const assert = require('assert');

const jimp = require('jimp');
const pixelmatch = require('pixelmatch');
const puppeteer = require('puppeteer');
const serveHandler = require('serve-handler');

const port = 3001;
const width = 400;
const height = 400;
const snapshotPicPath = path.join(__dirname, 'snapshot', 'expect.png');
const diffPicPath = path.join(__dirname, 'snapshot', 'diff.png');

let server = null;
let browser = null;

describe('E2E Testing', function () {
  before(function (done) {
    server = http.createServer((req, res) => serveHandler(req, res, {
      public: path.join(__dirname, '..', 'src'),
    }));
    server.listen(port, done);
    server.on('SIGINT', () => process.exit(1));
  });

  it('testing...', function (done) {
    this.timeout(1000 * 60);

    const expectDiffRate = 0.005;

    new Promise(async (resolve) => {
      browser = await puppeteer.launch();
      const page = await browser.newPage();
      await page.setViewport({ width: width, height: height });
      await page.goto(`http://127.0.0.1:${port}/index.html`);
      const buf = await page.screenshot();
      const actual = (await jimp.read(buf)).scale(1).quality(100).bitmap;
      const expected = (await jimp.read(fs.readFileSync(snapshotPicPath))).bitmap;
      const diff = actual;
      const failPixel = pixelmatch(expected.data, actual.data, diff.data, actual.width, actual.height);
      const failRate = failPixel / (width * height);

      if (failRate >= expectDiffRate) {
        (await jimp.read(diff)).scale(1).quality(100).write(diffPicPath);
        console.log(`create diff image at: ${diffPicPath}`);
      }

      resolve(failRate);
    }).then((failRate) => {
      assert.ok(failRate < expectDiffRate);
      done();
    }).catch(done);
  });

  after(function () {
    browser && browser.close();
    server && server.close();
  });
});

Additional Considerations

Cross‑OS pixel variations may require separate test suites per platform.

Thoughts on Front‑End Visual Quality Testing

Three aspects of front‑end visual quality are identified:

Code quality verification – unit tests, coverage, tools such as jest or mocha.

Visual correctness – E2E pixel comparison using puppeteer + pixelmatch or jest‑image‑snapshot.

Performance verification – benchmark testing with tools like benchmark.js.

Conclusion

The author discovered existing tools such as jest-image-snapshot, built a personal H5 image‑processing toy with tests (see https://github.com/chenshenhai/pictool), and encourages others to explore the repository.