Visual Regression Testing for PDFs in JavaScript

Library for testing visual regression of PDFs. It uses pdf.js for conversion of a pdf to png (in node pdf.js depends on canvas). Than comparison is happening via jimp.

Installation

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 compareOptions - image comparison options * @param compareOptions.tolerance - number value for error tolerance, ranges 0-1 (default: 0) * @param compareOptions.maskRegions - `(page: number) => ReadonlyArray<RegionMask> | undefined` mask predefined regions per page, i.e. when there are parts of the pdf that change between tests */typeComparePdfToSnapshot=(pdf: string|Buffer,snapshotDir: string,snapshotName: string,compareImageOpts: Partial<CompareOptions>={},)=>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',()=>{constpathToPdf='path to your pdf'// or you might pass in Buffer insteadit('should pass',()=>comparePdfToSnapshot(pathToPdf,__dirname,'my-awesome-report').then((x)=>expect(x).to.be.true,))})// Example with masking regions of a two page pdfdescribe('pdf masking',()=>{it('should mask two page pdf',()=>{constblueMask: RegionMask={type: 'rectangle-mask',x: 50,y: 75,width: 140,height: 100,color: 'Blue',}constgreenMask: 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){case1:
return[blueMask]case2:
return[greenMask]default:
return[]}},}).then((x)=>expect(x).to.be.true))})})

Tools

pdf-visual-diff provides scripts for approving all new snapshots or discarding them. Add to your scripts section in package.json

"test:pdf-approve": "pdf-visual-diff approve",
"test:pdf-discard": "pdf-visual-diff discard",

pdf-visual-diff approve
Approve new snapshots
Options:
--help Show help [boolean]
--version Show version number [boolean]
-p, --path [default: "."]
-s, --snapshots-dir-name [default: "__snapshots__"]

pdf-visual-diff discard
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 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.

constpathToPdf='path to your pdf'// or you might pass in Buffer insteaddescribe('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.

Usage with Playwright

This packages provides custom Playwright matcher toMatchPdfSnapshot

Setup

Add the following line to your playwright.config.ts

import'pdf-visual-diff/lib/playwright'

If you are using Typescript add node_modules/pdf-visual-diff/lib/playwright to your tsconfig.json types.

Usage

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

constpathToPdf='path to your pdf'// or you might pass in Buffer insteaddescribe('test pdf report visual regression',()=>{it('should match',()=>expect(pathToPdf).toMatchPdfSnapshot({name: 'my-pdf.pdf'// file extension will always be replaced with .png}))})