feat(browser): use @blazediff/core as the default screenshot comparator

Author: macarie

docs/api/browser/assertions.md

@@ -1133,15 +1133,15 @@ await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button')
 
 // with options
 await expect.element(getByTestId('button')).toMatchScreenshot({
-  comparatorName: 'pixelmatch',
+  comparatorName: '@blazediff/core',
   comparatorOptions: {
     allowedMismatchedPixelRatio: 0.01,
   },
 })
 
 // with both name and options
 await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
-  comparatorName: 'pixelmatch',
+  comparatorName: '@blazediff/core',
   comparatorOptions: {
     allowedMismatchedPixelRatio: 0.01,
   },
@@ -1150,12 +1150,13 @@ await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
 
 ### Options
 
-- `comparatorName: "pixelmatch" = "pixelmatch"`
+- `comparatorName: "@blazediff/core" | "pixelmatch" = "@blazediff/core"`
 
-  The name of the algorithm/library used for comparing images.
+  The algorithm/library used for comparing images.
 
-  Currently, [`"pixelmatch"`](https://github.com/mapbox/pixelmatch) is the only
-  supported comparator.
+  [`"@blazediff/core"`](https://blazediff.dev/docs/core) is the only built-in comparator, but you can use custom ones by [registering them in the config file](/config/browser#browser-expect-toMatchScreenshot-comparators).
+
+  Since v4.1, `"pixelmatch"` is a legacy alias for `"@blazediff/core"` and will be removed in the next major version.
 
 - `comparatorOptions: object`
 
@@ -1164,7 +1165,7 @@ await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
 
   Vitest has set default values out of the box, but they can be overridden.
 
-  - [`"pixelmatch"` options](#pixelmatch-comparator-options)
+  - [`"@blazediff/core"` options](#blazediff-core-comparator-options)
 
   ::: warning
   **Always explicitly set `comparatorName` to get proper type inference for
@@ -1181,9 +1182,9 @@ await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
     },
   })
 
-  // ✅ TypeScript knows these are pixelmatch options
+  // ✅ TypeScript knows these are `"@blazediff/core"` options
   await expect.element(button).toMatchScreenshot({
-    comparatorName: 'pixelmatch',
+    comparatorName: '@blazediff/core',
     comparatorOptions: {
       allowedMismatchedPixelRatio: 0.01,
     },
@@ -1208,9 +1209,9 @@ await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
   Setting this value to `0` disables the timeout, but if a stable screenshot
   can't be determined the process will not end.
 
-#### `"pixelmatch"` comparator options
+#### `"@blazediff/core"` comparator options
 
-The following options are available when using the `"pixelmatch"` comparator:
+The following options are available when using the `"@blazediff/core"` comparator:
 
 - `allowedMismatchedPixelRatio: number | undefined = undefined`
 

docs/config/browser/expect.md

@@ -28,7 +28,7 @@ export default defineConfig({
       enabled: true,
       expect: {
         toMatchScreenshot: {
-          comparatorName: 'pixelmatch',
+          comparatorName: '@blazediff/core',
           comparatorOptions: {
             threshold: 0.2,
             allowedMismatchedPixels: 100,

docs/guide/browser/visual-regression-testing.md

@@ -154,7 +154,7 @@ export default defineConfig({
     browser: {
       expect: {
         toMatchScreenshot: {
-          comparatorName: 'pixelmatch',
+          comparatorName: '@blazediff/core',
           comparatorOptions: {
             // 0-1, how different can colors be?
             threshold: 0.2,
@@ -174,7 +174,7 @@ Override global settings for specific tests:
 
 ```ts
 await expect(element).toMatchScreenshot('button-hover', {
-  comparatorName: 'pixelmatch',
+  comparatorName: '@blazediff/core',
   comparatorOptions: {
     // more lax comparison for text-heavy elements
     allowedMismatchedPixelRatio: 0.1,
@@ -339,7 +339,7 @@ possible solutions might be to:
 
   ```ts
   await expect(page.getByTestId('article-summary')).toMatchScreenshot({
-    comparatorName: 'pixelmatch',
+    comparatorName: '@blazediff/core',
     comparatorOptions: {
       // 10% of the pixels are allowed to change
       allowedMismatchedPixelRatio: 0.1,

packages/browser/context.d.ts

@@ -41,7 +41,7 @@ export interface ScreenshotOptions {
 }
 
 interface StandardScreenshotComparators {
-  pixelmatch: {
+  '@blazediff/core': {
     /**
      * The maximum number of pixels that are allowed to differ between the captured
      * screenshot and the stored reference image.
@@ -134,6 +134,10 @@ interface StandardScreenshotComparators {
      */
     diffMask?: boolean | undefined
   }
+  /**
+   * @deprecated Since v4.1, `"pixelmatch"` is a legacy alias for `"@blazediff/core"` and will be removed in the next major version.
+   */
+  pixelmatch: StandardScreenshotComparators['@blazediff/core']
 }
 
 export interface ScreenshotComparatorRegistry extends StandardScreenshotComparators {}
@@ -151,7 +155,7 @@ export interface ScreenshotMatcherOptions<
    *
    * Must be one of the keys from {@linkcode ScreenshotComparatorRegistry}.
    *
-   * @defaultValue `'pixelmatch'`
+   * @defaultValue `'@blazediff/core'`
    */
   comparatorName?: ComparatorName
   comparatorOptions?: ScreenshotComparatorRegistry[ComparatorName]

packages/browser/jest-dom.d.ts

@@ -698,15 +698,15 @@ export interface TestingLibraryMatchers<E, R> {
    *
    * // with options
    * await expect.element(getByTestId('button')).toMatchScreenshot({
-   *   comparatorName: 'pixelmatch',
+   *   comparatorName: '@blazediff/core',
    *   comparatorOptions: {
    *     allowedMismatchedPixelRatio: 0.01,
    *   },
    * })
    *
    * // with both name and options
    * await expect.element(getByTestId('button')).toMatchScreenshot('fancy-button', {
-   *   comparatorName: 'pixelmatch',
+   *   comparatorName: '@blazediff/core',
    *   comparatorOptions: {
    *     allowedMismatchedPixelRatio: 0.01,
    *   },

packages/browser/package.json

@@ -64,10 +64,10 @@
     "vitest": "workspace:*"
   },
   "dependencies": {
+    "@blazediff/core": "1.9.1",
     "@vitest/mocker": "workspace:*",
     "@vitest/utils": "workspace:*",
     "magic-string": "catalog:",
-    "pixelmatch": "7.1.0",
     "pngjs": "^7.0.0",
     "sirv": "catalog:",
     "tinyrainbow": "catalog:",

…eenshotMatcher/comparators/pixelmatch.ts …hotMatcher/comparators/blazediff-core.tspackages/browser/src/node/commands/screenshotMatcher/comparators/pixelmatch.ts renamed to packages/browser/src/node/commands/screenshotMatcher/comparators/blazediff-core.ts packages/browser/src/node/commands/screenshotMatcher/comparators/pixelmatch.ts renamed to packages/browser/src/node/commands/screenshotMatcher/comparators/blazediff-core.ts

@@ -1,6 +1,6 @@
 import type { ScreenshotComparatorRegistry } from '../../../../../context'
 import type { Comparator } from '../types'
-import pm from 'pixelmatch'
+import { diff } from '@blazediff/core'
 
 const defaultOptions = {
   allowedMismatchedPixelRatio: undefined,
@@ -12,9 +12,9 @@ const defaultOptions = {
   diffColor: [255, 0, 0],
   diffColorAlt: undefined,
   diffMask: false,
-} satisfies ScreenshotComparatorRegistry['pixelmatch']
+} satisfies ScreenshotComparatorRegistry['@blazediff/core']
 
-export const pixelmatch: Comparator<ScreenshotComparatorRegistry['pixelmatch']> = (
+export const blazediffCore: Comparator<ScreenshotComparatorRegistry['@blazediff/core']> = (
   reference,
   actual,
   { createDiff, ...options },
@@ -36,7 +36,7 @@ export const pixelmatch: Comparator<ScreenshotComparatorRegistry['pixelmatch']>
     ? new Uint8Array(reference.data.length)
     : undefined
 
-  const mismatchedPixels = pm(
+  const mismatchedPixels = diff(
     reference.data,
     actual.data,
     diffBuffer,

packages/browser/src/node/commands/screenshotMatcher/comparators/index.ts

@@ -1,14 +1,15 @@
 import type { BrowserCommandContext } from 'vitest/node'
 import type { ScreenshotComparatorRegistry } from '../../../../../context'
 import type { Comparator } from '../types'
-import { pixelmatch } from './pixelmatch'
+import { blazediffCore } from './blazediff-core'
 
 const comparators: {
   [ComparatorName in keyof ScreenshotComparatorRegistry]: Comparator<
     ScreenshotComparatorRegistry[ComparatorName]
   >
 } = {
-  pixelmatch,
+  '@blazediff/core': blazediffCore,
+  'pixelmatch': blazediffCore,
 }
 
 export function getComparator<ComparatorName extends keyof ScreenshotComparatorRegistry>(

packages/browser/src/node/commands/screenshotMatcher/utils.ts

@@ -17,7 +17,7 @@ type GlobalOptions = Required<Omit<
 >>
 
 const defaultOptions = {
-  comparatorName: 'pixelmatch',
+  comparatorName: '@blazediff/core',
   // these are handled by each comparator on its own
   comparatorOptions: {},
   screenshotOptions: {

packages/vitest/src/node/types/browser.ts

@@ -277,7 +277,7 @@ export interface BrowserConfigOptions {
         /**
          * The name of the comparator to use for visual diffing.
          *
-         * @defaultValue `'pixelmatch'`
+         * @defaultValue `'@blazediff/core'`
          */
         comparatorName?: ComparatorName
         comparatorOptions?: ToMatchScreenshotComparators[ComparatorName]