HumbleSoftware/js-imagediff: JavaScript / Canvas based image diff utility with Jasmine matchers for testing canvas.

js-imagediff ============

JavaScript / Canvas based imagediff utility.

API

• createCanvas() create a new Canvas element.
• createImageData(width, height) create a new ImageData object.
• isImage(object) tests for Image object.
• isCanvas(object) tests for Canvas object.
• isContext(object) tests for CanvasRenderingContext2D object.
• isImageData(object) tests for ImageData object.
• isImageType(object) tests for any of the above.
• toImageData(object) converts image type object to a new ImageData object.
• equal(a, b, tolerance) tests image type objects for equality; accepts tolerance in pixels.
• diff(a, b, options) performs an image diff on a and b, returning a - b.

• noConflict() removes imagediff from the global space for compatibility, returning imagediff.
• imageDataToPNG(imageData, outputFile, [callback]) (node only) renders the imageData to png in outputFile with optional callback.

js-imagediff is available through the npm. It uses node-canvas which requires lib cairo to be installed. Install js-imagediff with npm install -g imagediff.

Command Line

• imagediff [-e|equal] [-t|tolerance VALUE] FILE_A FILE_B tests equality of two image files with an optional tolerance, printing 'true' or 'false'.
• imagediff [-d|diff] FILE_A FILE_B OUTPUT_FILE renders an imagediff between two files, saving as the output file.

Cannot find module 'canvas'

Canvas has been moved to an optional dependency for better browser and browserify support. If you see a message that the module cannot be found, please check npm install first, incase there was indeed an issue installing it. This relates to https://github.com/HumbleSoftware/js-imagediff/issues/22. Please let me know if you have any issues on account of this, or know of a better work around.

Unit Testing Canvas -------------------

JS ImageDiff opens up the easy testing of Canvas and other image-like objects in JavaScript. js-imagediff supplies two Jasmine matchers to make this easier.

• toImageDiffEqual(expected, tolerance) expect a result to equal another image type.
• toBeImageData() expect a result to be ImageData.

To use matchers:

beforeEach(function () {
    this.addMatchers(imagediff.jasmine);
  });

Demo ----

• A demo is available at http://humblesoftware.github.com/js-imagediff/
• A Jasmine test demo is available at http://humblesoftware.github.com/js-imagediff/test.html

• Flotr2 - unit testing
• Envision.js - unit testing
• CSS Critic - A CSS regression testing framework
• HUSL - Human-friendly HSL - used for regression testing before release.
• SUCCSS - CSS regression testing.
• Origami.js - A canvas library

Development -----------

Local setup

Use the Node version in .nvmrc, then:

npm ci
npx playwright install --with-deps chromium  # one-time
npm test

Scripts

• npm test runs the specs in headless Chromium with Playwright.
• npm run test:serve serves the specs at http://localhost:8085/spec/ to watch them run in a browser.
• npm run test:node runs the specs in Node.js (requires the optional canvas dependency).

Dev container

The repo includes an optional dev container with Node, Chromium and its system libraries ready to go, so only Podman or Docker is needed. Open the repo in VS Code or Codespaces, or run devcontainer up --workspace-folder ., and dependencies are installed with npm ci; then npm test works as above. Working without the container is still supported.

The container uses the official Playwright image, whose tag in .devcontainer/devcontainer.json must match the @playwright/test version in package-lock.json. Bump the tag whenever Playwright is upgraded. CI (.github/workflows/test.yml) reads the image from the same file, so it needs no separate change.

Changelog ---------

2.0.0-alpha

• Update to support Jasmine 3.

1.0.8

• Update canvas dependency.
• Expose internal Canvas.

1.0.7

• Add async image loading for canvas (closes #31, #35, #39).
• Support --diff, --equal, --tolerance (closes #17).

1.0.6

• Add top-aligned diffing option.
• Fix issue with diffing transparencies.

1.0.5

• Move canvas to optional dependencies for browserify support.

1.0.4

• Updated canvas dependency.
• Add check for arguments count in diff mode.

1.0.3

• Added NPM/node.js support.
• Added command line interface for equal and diff methods.
• Added imageDataToPNG method for node environments.
• Added tolerance to handle lossy formats and provide option for acceptable difference.

1.0.2

• Added optional width / height parameters to createCanvas for symmetry with createImageData.
• Fixed issue with toImageDiffEqual() matcher and non Node types - will no convert ImageData and contexts to Canvas elements for display.

1.0.1

• Moved library to imagediff.js
• Added Jasmine matchers
• Minor bug fixes, lint fixes.