Test Visual Regression in PDFs

pdf-visual-diff is a library for testing visual regressions in PDFs. It uses pdf.js to convert PDFs into PNGs and jimp for image comparisons.

Installation

This library depends on canvas package. Please refer to the canvas documentation for any additional installation steps.

npm install -D pdf-visual-diff

Description

This package exports a single function, comparePdfToSnapshot, with the following signature:

function comparePdfToSnapshot(
  pdf: string | Buffer,
  snapshotDir: string,
  snapshotName: string,
  options?: CompareOptions
): Promise<boolean>

It compares a PDF to a persisted snapshot. If a snapshot does not exists, one is created. When the function is executed, it has following side effects:

• If a previous snapshot file does not exist, the PDF is converted to an image, saved as a snapshot, and the function returns true.
• If a snapshot exists, the PDF is converted to an image and compared to the snapshot:
  • If they differ, the function returns false and creates two additional images next to the snapshot: one with the suffix new (the current view of the PDF as an image) and one with the suffix diff (showing the difference between the snapshot and the new image).
  • If they are equal, the function returns true. If new and diff versions are present, they are deleted.

Returns a promise that resolves to true if the PDF matches the snapshot or if a new snapshot is created, and false if the PDF differs from the snapshot.

For further details and configuration options, please refer to the API Documentation.

Sample usage

Note: You can find sample projects in the 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 a Buffer instead
  it('should pass', () =>
    comparePdfToSnapshot(pathToPdf, __dirname, 'my-awesome-report').then(
      (x) => expect(x).to.be.true,
    ))
})

// Example with masking regions of a two-page PDF
describe('PDF masking', () => {
  it('should mask two-page PDF', () => {
    const blueMask: RegionMask = {
      type: 'rectangle-mask',
      x: 50,
      y: 75,
      width: 140,
      height: 100,
      color: 'Blue',
    }
    const greenMask: RegionMask = {
      type: 'rectangle-mask',
      x: 110,
      y: 200,
      width: 90,
      height: 50,
      color: 'Green',
    }

    comparePdfToSnapshot(twoPagePdfPath, __dirname, 'different-mask-per-page', {
      maskRegions: (page) => {
        switch (page) {
          case 1:
            return [blueMask]
          case 2:
            return [greenMask]
          default:
            return []
        }
      },
    }).then((x) => expect(x).to.be.true))
  })
})

Tools

pdf-visual-diff provides a CLI for approving or discarding new PDF snapshots. The CLI can be used via npx or npm by updating the scripts section of your package.json:

"scripts": {
  "test:pdf-approve": "pdf-visual-diff approve",
  "test:pdf-discard": "pdf-visual-diff discard"
}

To approve new snapshots, run the following command in your terminal:

npm run test:pdf-approve

Paths for the new snapshots will be listed. You will then be prompted to confirm whether you want to replace the old snapshots with the new ones:

New snapshots:
./__snapshots__/test_doc_1.new.png
./__snapshots__/single-page-snapshot.new.png
Are you sure you want to overwrite current snapshots? [Y/n]:

These commands can be customized by specifying a custom path and snapshots folder name.

Approve command help:

npx pdf-visual-diff approve --help

Approve new snapshots

Options:
      --help                Show help                                  [boolean]
      --version             Show version number                        [boolean]
  -p, --path                                                      [default: "."]
  -s, --snapshots-dir-name                            [default: "__snapshots__"]

Discard command help:

npx pdf-visual-diff discard --help

Discard new snapshots and diffs

Options:
      --help                Show help                                  [boolean]
      --version             Show version number                        [boolean]
  -p, --path                                                      [default: "."]
  -s, --snapshots-dir-name                            [default: "__snapshots__"]

Usage with Jest

This packages provides a 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

In your tests, pass a path to the PDF or PDF content a Buffer.

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

As you can see, there is no need to manage directories or names manually. The necessary information is extracted from the Jest context.