Screenshot Comparison Validator

A utility that compares screenshot images from different browsers and platforms while intelligently handling rendering differences caused by anti-aliasing variations.

Background

When testing web applications across different browsers and operating systems, screenshots of the same content may differ slightly due to varying text rendering, font anti-aliasing, and sub-pixel rendering techniques. These differences are visual artifacts rather than actual content changes and should be identified separately from genuine visual regressions.

Requirements

Build a screenshot comparison tool that:

1. Compares two PNG screenshot images and reports the number of different pixels
2. Excludes anti-aliasing differences from the mismatch count (since these vary between browsers/platforms)
3. Generates a visual diff output with different colors for genuine differences versus anti-aliased pixels
4. Calculates the total mismatch count both with and without anti-aliasing pixels included

Input

Your tool should accept:

• Two PNG image file paths (baseline and comparison screenshots)
• An output file path for the visual diff image

Output

The tool should:

• Write a visual diff PNG file showing differences (with anti-aliased pixels in a different color)
• Return an object with:
  • Number of mismatched pixels excluding anti-aliasing differences
  • Number of mismatched pixels including anti-aliasing differences
  • Boolean indicating if screenshots match (when ignoring AA)

Behavior

• The tool must exclude anti-aliasing artifacts when determining if screenshots match
• Anti-aliased pixels should be visually distinguished in the diff output
• Images must be the same dimensions to be compared

Test Cases

• When comparing two identical screenshots, reports 0 differences both with and without AA @test
• When comparing screenshots with only anti-aliasing differences, reports 0 differences when excluding AA but >0 when including AA @test
• When comparing screenshots with actual content changes, reports >0 differences even when excluding AA @test

Implementation

@generates

API

/**
 * Compares two screenshot images and generates a diff output
 *
 * @param {string} baselinePath - Path to the baseline PNG screenshot
 * @param {string} comparisonPath - Path to the comparison PNG screenshot
 * @param {string} outputPath - Path where the diff PNG should be written
 * @returns {Promise<{mismatchedPixelsExcludingAA: number, mismatchedPixelsIncludingAA: number, passed: boolean}>}
 */
async function compareScreenshots(baselinePath, comparisonPath, outputPath) {
  // IMPLEMENTATION HERE
}

module.exports = { compareScreenshots };

Dependencies { .dependencies }

pixelmatch { .dependency }

Provides pixel-level image comparison with anti-aliasing detection support.

pngjs { .dependency }

Provides PNG image encoding and decoding capabilities.