Visual Regression Testing for PDFs in JavaScript

Getting started

First download and install GraphicsMagick for your platform. For macOS you can simply use Homebrew and do:

brew install graphicsmagick

then use npm:

npm install -D pdf-visual-diff

Description

This package exports single function comparePdfToSnapshot. With the following signature:

/**
 * Compare pdf to persisted snapshot. If one does not exist it is created
 * @param pdf - path to pdf file or pdf loaded as Buffer
 * @param snapshotDir - path to a directory where __snapshots__ folder is going to be created
 * @param snapshotName - uniq name of a snapshot in the above path
 * @param compareImageOpts - settings for image comparation
 * @param compareImageOpts.highlightColor - color for differences in the diff image, defaults to Black
 * @param compareImageOpts.highlightStyle - highlight style as documented by the {@link http://www.graphicsmagick.org/GraphicsMagick.html#details-highlight-style gm package}, defaults to Tint
 * @param compareImageOpts.tolerance - number value for error tolerance, defaults to 0
 * @param compareImageOpts.writeDiff - flag to enable/disable diff file creation, defaults to true
 * @param compareImageOpts.maskRegions - exclude regions from the diff by masking them with solid rectangles
 */
type ComparePdfToSnapshot = (
  pdf: string | Buffer,
  snapshotDir: string,
  snapshotName: string,
  compareImageOpts?: Partial<CompareImagesOpts>,
) => Promise<boolean>

When function is executed it has following side effects:

• In absence of a previous snapshot file it converts pdf to an image, saves it as a snapshot and returns true
• If there is a snapshot, then pdf is converted to an image and gets compared to the snapshot:
  • if they differ function returns false and creates next to the snapshot image two other versions with suffixes new and diff. new one is the current view of the pdf as an image, where diff shows the difference between the snapshot and new images
  • if they are equal function returns true and in case there are new and diff versions persisted it deletes them

Sample usage

NB! You can find sample projects inside examples folder.

Write a test file:

import { comparePdfToSnapshot } from 'pdf-visual-diff'
import { expect } from 'chai'

describe('test pdf report visual regression', () => {
  const pathToPdf = 'path to your pdf' // or you might pass in Buffer instead
  it('should pass', () =>
    comparePdfToSnapshot(pathToPdf, __dirname, 'my-awesome-report').then(
      (x) => expect(x).to.be.true,
    ))
})

Usage with Jest

This packages provides custom jest matcher toMatchPdfSnapshot

Setup

"jest": {
  "setupFilesAfterEnv": ["pdf-visual-diff/lib/toMatchPdfSnapshot"]
}

If you are using Typescript add import('pdf-visual-diff/lib/toMatchPdfSnapshot') to your typings.

Usage

All you have to do in your tests is pass a path to the pdf or pdf content as Buffer.

const pathToPdf = 'path to your pdf' // or you might pass in Buffer instead
describe('test pdf report visual regression', () => {
  it('should match', () => expect(pathToPdf).toMatchPdfSnapshot())
})

As you can see no need to fiddle with any dirs nor names. Needed information is extracted from jest context.