pdf-visual-comparer

A Node.js package to visually compare two PDF files and calculate the total number of differing pixels across their pages. It also provides a custom matcher for Playwright.

Installation

npm install pdf-visual-comparer

Basic Usage

The determineDifferentPixelsCount function compares two PDFs and returns the total number of differing pixels.

import determineDifferentPixelsCount from 'pdf-visual-comparer';

const firstPdf = '/path/to/first.pdf';
const secondPdf = '/path/to/second.pdf';

try {
  // Supports file paths, Buffers, TypedArrays, or ArrayBuffers
  const diffPixelsCount = await determineDifferentPixelsCount(firstPdf, secondPdf);
  console.log(`Total different pixels: ${diffPixelsCount}`);
} catch (error) {
  console.error('Comparison failed:', error);
}

Playwright Custom Matcher

pdf-visual-comparer provides a toMatchPdf matcher for Playwright to fail tests when PDFs differ visually.

Setup

1. Register the matcher in your Playwright config or a setup file:

   import { expect } from '@playwright/test';
   import toMatchPdf from 'pdf-visual-comparer/playwright';
   
   expect.extend({ toMatchPdf });

2. Add TypeScript typings (optional but recommended): Update your tsconfig.json to include the global typings:

   {
     "compilerOptions": {
       "types": ["pdf-visual-comparer/typings/global.d.ts"]
     }
   }

Usage in Tests

The matcher accepts an optional testInfo object to attach visual diffs to your Playwright report and a threshold for pixel differences.

import { expect, test } from '@playwright/test';

test('PDFs should match visually', async ({ page }, testInfo) => {
  const actualPdf = 'path/to/actual.pdf';
  const expectedPdf = 'path/to/expected.pdf';

  // Basic usage
  await expect(actualPdf).toMatchPdf(expectedPdf);

  // With testInfo (attaches diff screenshots and PDFs to the report)
  await expect(actualPdf).toMatchPdf(expectedPdf, testInfo);

  // With threshold (allows up to 100 differing pixels)
  const threshold = 100;
  await expect(actualPdf).toMatchPdf(expectedPdf, testInfo, threshold);
});

When a test fails:

• The expected and actual PDFs are attached to the report.
• For each differing page, a screenshot of both pages and a visual diff are attached.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue on the GitHub repository.

License

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