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.
This library depends on canvas
package. Please refer to the canvas documentation for any additional installation steps.
npm install -D pdf-visual-diff
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 suffixnew
(the current view of the PDF as an image) and one with the suffixdiff
(showing the difference between the snapshot and thenew
image). - If they are equal, the function returns
true
. Ifnew
anddiff
versions are present, they are deleted.
- If they differ, the function returns
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.
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))
})
})
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__"]
This packages provides a custom Jest matcher toMatchPdfSnapshot
.
"jest": {
"setupFilesAfterEnv": ["pdf-visual-diff/lib/toMatchPdfSnapshot"]
}
If you are using TypeScript add import('pdf-visual-diff/lib/toMatchPdfSnapshot')
to your typings.
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.