To compare website screenshots in Node.js, decode both PNG files into raw pixel data, make sure they have identical dimensions, and pass their pixel buffers to Pixelmatch. Its return value is the number of mismatched pixels; set your own tolerance to decide whether that count should fail a test. You can also save Pixelmatch’s output as a diff image to inspect the changes.
Install Pixelmatch and pngjs
Pixelmatch compares image data; pngjs handles reading and writing PNG files in this example. Install both packages in your project:
npm install pixelmatch pngjsThe code below uses ES module imports. Save it as compare.js in a project configured for ES modules, or use a .mjs file extension.
Compare two screenshots and write a diff image
Save the baseline and new capture as baseline.png and actual.png in the project directory, then run the script. The example checks dimensions before comparison, writes diff.png, and prints Pixelmatch’s mismatch count.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
import fs from 'node:fs';
import pixelmatch from 'pixelmatch';
import { PNG } from 'pngjs';
const baseline = PNG.sync.read(fs.readFileSync('baseline.png'));
const actual = PNG.sync.read(fs.readFileSync('actual.png'));
if (baseline.width !== actual.width || baseline.height !== actual.height) {
throw new Error('Screenshots must have equal dimensions');
}
const diff = new PNG({ width: baseline.width, height: baseline.height });
const mismatchedPixels = pixelmatch(
baseline.data,
actual.data,
diff.data,
baseline.width,
baseline.height,
{ threshold: 0.1 }
);
fs.writeFileSync('diff.png', PNG.sync.write(diff));
console.log(`Mismatched pixels: ${mismatchedPixels}`);Pixelmatch accepts image data as a Buffer, Uint8Array or Uint8ClampedArray. Both inputs and an output image, when supplied, must have matching dimensions. The output argument can be null if you only need a mismatch count and do not need a visual diff. See the Pixelmatch README for its API and documented example.
Use the count as a test result
The returned number is a count, not an automatic pass/fail decision. Choose an allowed mismatch count for your application and compare the result with that limit. For example, a strict test might require zero mismatches, while a project that tolerates small rendering variations can set a larger, explicitly chosen limit.
const allowedMismatches = 25;
if (mismatchedPixels > allowedMismatches) {
throw new Error(`Visual difference too large: ${mismatchedPixels} mismatched pixels`);
}The value 25 is an example policy, not a Pixelmatch recommendation. A raw count also depends on screenshot dimensions, so determine the limit from your test’s purpose rather than treating one number as universal.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Choose comparison settings
Pixelmatch options let you tune sensitivity, anti-aliasing treatment, and how the diff is rendered. The current project README documents windowSize; check the documentation for your installed version before relying on that option, since the package README snapshot for 7.2.0 does not establish its availability in every release.
| Option | Effect | When to change it |
|---|---|---|
threshold |
Ranges from 0 to 1; lower values make the comparison more sensitive. The documented default is 0.1. |
Lower it when subtle color differences matter; raise it cautiously if minor pixel-level variation creates unwanted mismatches. |
includeAA |
Defaults to false, so detected anti-aliased pixels are ignored. Set to true to count them as differences. |
Enable it when edge-rendering differences should count in your test. |
alpha |
Controls blending of unchanged pixels in the diff output. | Adjust the display if you need unchanged areas to be more or less visible. |
aaColor, diffColor, diffColorAlt |
Set colors used to show anti-aliased pixels and differences. | Use these to make categories of changes easier to distinguish in the output image. |
diffMask |
Renders the diff over transparency rather than over the original image. | Choose it when you want a transparent mismatch mask for downstream inspection or compositing. |
windowSize |
With the default Infinity, reports mismatches across the full image. A finite size reports the maximum mismatch count in any sliding square of that size. |
Use a finite window to focus on the most concentrated local difference, if supported by your installed release. |
For example, include anti-aliased edge changes while using the documented default sensitivity:
const mismatchedPixels = pixelmatch(
baseline.data,
actual.data,
diff.data,
baseline.width,
baseline.height,
{ threshold: 0.1, includeAA: true }
);Keep screenshot comparisons meaningful
A comparison is most useful when the baseline and new screenshot represent the same page state and rendering conditions. Keep the capture setup consistent—for example, use the same viewport, page state, and timing—so that the diff is more likely to reflect a website change rather than a changed capture condition. This is practical testing guidance, not a Pixelmatch guarantee.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
- Capture the same URL and relevant interaction state.
- Keep viewport dimensions and device scale consistent.
- Wait for the page content your test depends on before capturing.
- Review
diff.pngwhen a count crosses your limit; the count alone does not explain where the pixels changed.
Quick manual comparison with the CLI
For a one-off comparison of PNG files, Pixelmatch also documents a command-line interface:
pixelmatch image1.png image2.png output.png 0.1Use the library API in a Node.js test when you need to inspect the returned count, apply a project-specific pass/fail rule, or integrate comparison into a capture pipeline. The CLI is a direct option for a manual diff.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Troubleshooting
Dimension mismatch error
Pixelmatch requires both images—and the output image, if used—to have the same width and height. Check the decoded dimensions before calling it. If screenshots differ in size, fix the capture settings or deliberately resize/crop them with an image-processing step before comparison; do not pass mismatched buffers and assume the result is meaningful.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
The diff reports too many changes
First inspect diff.png and confirm the screenshots show the same page state at the same viewport. If the only changes are anti-aliased edges, leave the default includeAA: false; setting it to true makes those detected pixels count. Adjust threshold only to reflect the sensitivity your test needs.
No diff image is needed
Pass null as Pixelmatch’s output argument and keep the returned mismatch count. This avoids creating an image buffer for inspection when the test only needs a numeric result.
The script cannot import Pixelmatch
Confirm that both dependencies are installed in the project and that Node.js is treating the script as an ES module. Use a .mjs filename or configure the project for ES modules, as assumed by the example imports.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
windowSize is unrecognized or behaves differently
The current main-branch README documents this option, but its availability should not be assumed for every older package version. Check the README or API documentation corresponding to the version installed in your project.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need to obtain screenshots before comparing them locally, ScreenshotNeo can return a PNG, JPEG, WebP or PDF from one GET request. Its cookie/consent cleanup removes known consent banners, newsletter popups and chat widgets before capture, and each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server also gives AI agents tools to take screenshots, get page information and capture PDFs.
For example, this cURL request saves a screenshot. See the ScreenshotNeo API documentation for configuration and response details:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpFor local Node.js capture code, the same API can be called with fetch:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes 1,000 screenshots per month on its free plan with no card required; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can Pixelmatch compare JPEG or WebP files directly?
The documented Node.js workflow here uses pngjs to decode PNG files; convert other formats to PNG or decode them to compatible raw pixel data before calling Pixelmatch.
Does a nonzero mismatch count always mean a visual test should fail?
No. Pixelmatch returns a count, and your test must define the acceptable tolerance for its purpose.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
