pdf-visual-comparer

This is a Node.js package that allows you to compare two PDF files and calculate the number of different pixels between their pages. Also provides a custom matcher for playwright.

Installation

To use this package, first install it via npm:

npm install pdf-visual-comparer

Usage

To use the determineDifferentPixelsCount function, import it from the pdf-visual-comparer package and pass in the file paths or buffers of the PDF files you want to compare:

import determineDifferentPixelsCount  from 'pdf-visual-comparer';

const firstPdfSrc = '/path/to/first.pdf';
const secondPdfSrc = '/path/to/second.pdf';

determineDifferentPixelsCount(firstPdfSrc, secondPdfSrc)
  .then((diffPixelsCount) => {
    console.log(`Number of different pixels between PDFs: ${diffPixelsCount}`);
  })
  .catch((error) => {
    console.error(error);
  });

You can also pass in TypedArray or ArrayBuffer objects as the PDF sources.

Playwright Custom Matcher

The custom playwright matcher compares two given PDFs and fails a playwright test if the PDFs have different pixels. In that case a screenshot of the pages with different pixels are attached. In any case both PDFs will be attached to the test result.

To use the toMatchPdf function inside a playwright test, you need to add the following:

Add the global typings reference inside your tsconfig.json. A global.d.ts file with the following content.

{
    "typeRoots": [
        "pdf-visual-compare/typings/global.d.ts"
    ]
}

Extend the playwright expect with toMatchPdf.

import { defineConfig, devices, expect } from '@playwright/test';
import toMatchPdf from 'pdf-visual-comparer/playwright';

expect.extend({
    toMatchPdf
});

Import it from the pdf-visual-comparer/playwright package.

import { expect, test } from '@playwright/test';
import toMatchPdf from 'pdf-visual-comparer/playwright';

test('should match given pdfs', async () => {
    await expect('/path/to/first.pdf').toMatchPdf('/path/to/second.pdf');
});

Pass the testInfo object to toMatchPdf to attach the following to the test result:

• the expected PDF
• the actual PDF
• if two compared pages have different pixels:
  • a screenshot of each page of the expected and actual PDF
  • a screenshot with a visual diff of each page of the PDFs

import { expect, test } from '@playwright/test';
import toMatchPdf from 'pdf-visual-comparer/playwright';

test('should match given pdfs', async ({page}, testInfo) => {
    await expect('/path/to/first.pdf').toMatchPdf('/path/to/second.pdf', testInfo);
});

Pass a threshold to toMatchPdf to allow the amount of pixels to vary between the actual and the expected PDF:

import { expect, test } from '@playwright/test';
import toMatchPdf from 'pdf-visual-comparer/playwright';

test('should match given pdfs with threshold', async ({page}, testInfo) => {
    const threshold = 100;
    await expect('/path/to/first.pdf').toMatchPdf('/path/to/second.pdf', testInfo, threshold);
});

Contributing

Contributions are welcome! If you find a bug or want to add a new feature, please open an issue or pull request on the GitHub repository.

License

This package is licensed under the MIT License. See the LICENSE file for details.