Skip to content
This repository

JavaScript / Canvas based image diff utility with Jasmine matchers for testing canvas.

branch: master

1.0.6 release.

* Add top-aligned diffing option.
* Fix issue with diffing transparencies.
latest commit b7ef33d3cf
Carl Sutherland cesutherland authored
Octocat-spinner-32 bin Provide exit codes to parent process November 20, 2013
Octocat-spinner-32 examples Fix fork ribbon. July 01, 2012
Octocat-spinner-32 js Merge in top-aligned diffing. March 05, 2014
Octocat-spinner-32 lib Upgrade to jasmine-1.2.0 July 01, 2012
Octocat-spinner-32 make Updated license, moved to separate file. February 20, 2012
Octocat-spinner-32 spec Allow images to be top aligned when diffing December 20, 2013
Octocat-spinner-32 .gitignore Added node_modules to gitignore. February 14, 2012
Octocat-spinner-32 LICENSE Added license. October 26, 2011
Octocat-spinner-32 Makefile Add node test to make task February 15, 2012
Octocat-spinner-32 1.0.6 release. March 05, 2014
Octocat-spinner-32 bower.json typo fix December 23, 2013
Octocat-spinner-32 imagediff.js Merge in top-aligned diffing. March 05, 2014
Octocat-spinner-32 imagediff.min.js Merge in top-aligned diffing. March 05, 2014
Octocat-spinner-32 package.json 1.0.6 release. March 05, 2014


JavaScript / Canvas based imagediff utility.


  • 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.
    • options.align set to 'top' to top-align the images when diffing different sizes.
  • 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 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.

On failed tests, toImageDiffEqual() will display the expected image, the actual image and the imagediff of the two letting you easily spot mistakes.

To use matchers:

  beforeEach(function () {



If you are using js-imagediff pelase drop us a line and let us know what you are doing with it.



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


  • Move canvas to optional dependencies for browserify support.


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


  • 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.


  • 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.


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


Carl Sutherland

Something went wrong with that request. Please try again.