@exzeo/pdf-diff

pdf-diff

Compares two PDFs and provides results on how they differ, including a diff image.

Install

npm install exframe-pdf-diff

Usage

compare

compare function takes two PDFs as input and returns a Promise that is fulfilled with the difference results when the comparison is complete.

const { compare } = require('exframe-pdf-diff');

(async () => {
  const result = await compare('./one.pdf', './two.pdf', {
    outputDirectory: './output'),
  });

  console.log(result);
})();


Output:
{
  baseline: { pageCount: 2 },
  actual: { pageCount: 2 },
  diffs: [
    {
      pageNumber: 1,
      numDiffPixels: 32563,
      percentDiffPixels: 0.06718120749983494,
      diffImageFileName: '/diff_1.png'
    },
    {
      pageNumber: 2,
      numDiffPixels: 0,
      percentDiffPixels: 0,
      diffImageFileName: '/diff_2.png'
    }
  ]
}

chaiPlugin

chaiPlugin is a function that can be passed to chai.use for convenient test assertions when verifying PDFs.

const chai = require('chai');
const { expect } = chai;
chai.use(require('exframe-pdf-diff').chaiPlugin);

describe('generated PDF', () => {
  it('matches baseline', async () => {
    await expect('./new.pdf').to.equalPdf('./baseline.pdf', {
      outputDirectory: './output'),
    });
  });
});

API

compare(pdf1, pdf2, options?)

Returns a Promise that is either fulfilled with the difference results when the comparison is completed successfully, or rejected with an error.

pdf1|pdf2

Type: Buffer | String | Stream

PDF used in comparison. A provided String is assumed to be a file name. A Buffer and Stream is assumed to contain binary PDF data. Note: Stream input will be read into a memory buffer prior to loading the document.

options

Type: object

pageRange

Type: String
Default: '1-' (all pages)

One or more pages to compare. Accepts a comma-separated list (i.e. '1,3,7'), a range (i.e. '1-3'), or combination ('1,5,8-').

outputDirectory

Type: String
Default: (no output files)

When present, will be used to write files for the following cases:

• Diff images will be written for each page where the actual result does not equal the baseline
• The actual PDF will be written if the page count differs from the baseline PDF page count

debug

Type: Boolean
Default: false

When true, all intermediate and diff images will be written to the outputDirectory for each compared page, regardless of whether they matched.

Note: This option is ignored if outputDirectory is not set to a valid path.

chaiPlugin

All input and options for the chai plugin are the same as the compare function.