feat(browser): support custom screenshot comparison algorithms

[macarie]

Description

Adds support for custom screenshot comparison algorithms in toMatchScreenshot so users can now register them in their config.

The video shows the TypeScript integration: when you declare a comparator in ScreenshotComparatorRegistry, it automatically becomes available in the config with full type checking: required registration, correct option types, and autocomplete for comparatorName.

fancy-comparator-demo.mp4

Custom comparators are registered in the config under browser.expect.toMatchScreenshot.comparators:

declare module 'vitest/browser' {
  interface ScreenshotComparatorRegistry {
    myComparator: {
      threshold?: number
    }
  }
}

export default defineConfig({
  test: {
    browser: {
      expect: {
        toMatchScreenshot: {
          comparators: {
            myComparator: (reference, actual, { createDiff, threshold = 0.1 }) => {
              // Custom comparison logic
              return { pass, diff, message }
            },
          },
        },
      },
    },
  },
})

Then can be used in tests:

await expect(locator).toMatchScreenshot({
  comparatorName: 'myComparator', // Autocompleted and type-checked
  comparatorOptions: { threshold: 0.2 }, // Typed based on registry
})

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
• Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[netlify]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c65cb47
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/68ebd8699c07b70008bfc698
😎 Deploy Preview	https://deploy-preview-8687--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sheremet-va]

Should we add links here? That explain what SSIM and perceptual diff mean

[macarie]

I had some issues when writing this... Went through a few iterations as I didn't know how much "beginner-friendly" to be.

I landed on "this is an advanced feature, people that are looking for it already know what they want to do with a custom comparator" so I didn't went into too much detail explaining different diffing algorithms, just provided some search terms.

If you think we should add some links, I can try finding some sources (probably Wikipedia for a general overview).

[sheremet-va]

Wikipedia links would be great

[macarie]

I've added the link (for SSIM) and reworded the final bit to "perceptual similarity metrics", which is more accurate. I don't have a link to this tho, as I believe it's more of an academic topic.

[sheremet-va]

Thank you!