chore: do not use "threshold" option for the ssim-cie94 comparator (#19314)

docs/src/api/params.md

@@ -801,7 +801,7 @@ An acceptable amount of pixels that could be different. Default is configurable
 * langs: js
 - `comparator` <[string]> Either `"pixelmatch"` or `"ssim-cie94"`.
 
-A comparator function to use when comparing images.
+A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
 
 ## assertions-max-diff-pixel-ratio
 * langs: js
@@ -813,7 +813,9 @@ An acceptable ratio of pixels that are different to the total amount of pixels,
 * langs: js
 - `threshold` <[float]>
 
-An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with `TestConfig.expect`. Defaults to `0.2`.
+An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ)
+between the same pixel in compared images, between zero (strict) and one (lax), default is configurable with
+`TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
 
 ## shared-context-params-list-v1.8
 - %%-context-option-acceptdownloads-%%

docs/src/test-api/class-testconfig.md

@@ -40,7 +40,7 @@ export default config;
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
   - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
     - `comparator` ?<[string]> a comparator function to use, either `"pixelmatch"` or `"ssim-cie94"`. Defaults to `"pixelmatch"`.
-    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"` comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults `threshold` value to `0.01`.
+    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used by `pixelmatch` image comparator.
     - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
     - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
     - `animations` ?<[ScreenshotAnimations]<"allow"|"disabled">> See [`option: animations`] in [`method: Page.screenshot`]. Defaults to `"disabled"`.
@@ -48,7 +48,7 @@ export default config;
     - `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
     - `comparator` ?<[string]> a comparator function to use, either `"pixelmatch"` or `"ssim-cie94"`. Defaults to `"pixelmatch"`.
-    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"` comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults `threshold` value to `0.01`.
+    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used by `pixelmatch` image comparator.
     - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
     - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
 

docs/src/test-api/class-testproject.md

@@ -111,7 +111,7 @@ export default config;
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
   - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
     - `comparator` ?<[string]> a comparator function to use, either `"pixelmatch"` or `"ssim-cie94"`. Defaults to `"pixelmatch"`.
-    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"` comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults `threshold` value to `0.01`.
+    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used by `pixelmatch` image comparator.
     - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
     - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
     - `animations` ?<[ScreenshotAnimations]<"allow"|"disabled">> See [`option: animations`] in [`method: Page.screenshot`]. Defaults to `"disabled"`.
@@ -119,7 +119,7 @@ export default config;
     - `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
     - `comparator` ?<[string]> a comparator function to use, either `"pixelmatch"` or `"ssim-cie94"`. Defaults to `"pixelmatch"`.
-    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"` comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults `threshold` value to `0.01`.
+    - `threshold` ?<[float]> an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and `1` (lax). `"pixelmatch"` comparator computes color difference in [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used by `pixelmatch` image comparator.
     - `maxDiffPixels` ?<[int]> an acceptable amount of pixels that could be different, unset by default.
     - `maxDiffPixelRatio` ?<[float]> an acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
 

packages/playwright-core/src/utils/comparators.ts

@@ -62,7 +62,9 @@ function compareImages(mimeType: string, actualBuffer: Buffer | string, expected
   let count;
   if (options.comparator === 'ssim-cie94') {
     count = compare(expected.data, actual.data, diff.data, expected.width, expected.height, {
-      maxColorDeltaE94: (options.threshold ?? 0.01) * 100,
+      // All ΔE* formulae are originally designed to have the difference of 1.0 stand for a "just noticeable difference" (JND).
+      // See https://en.wikipedia.org/wiki/Color_difference#CIELAB_%CE%94E*
+      maxColorDeltaE94: 1.0,
     });
   } else if ((options.comparator ?? 'pixelmatch') === 'pixelmatch') {
     count = pixelmatch(expected.data, actual.data, diff.data, expected.width, expected.height, {

packages/playwright-test/types/test.d.ts

@@ -541,9 +541,8 @@ interface TestConfig {
       /**
        * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
        * `1` (lax). `"pixelmatch"` comparator computes color difference in
-       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"`
+       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used
-       * comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults
+       * by `pixelmatch` image comparator.
-       * `threshold` value to `0.01`.
        */
       threshold?: number;
 
@@ -591,9 +590,8 @@ interface TestConfig {
       /**
        * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
        * `1` (lax). `"pixelmatch"` comparator computes color difference in
-       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"`
+       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used
-       * comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults
+       * by `pixelmatch` image comparator.
-       * `threshold` value to `0.01`.
        */
       threshold?: number;
 
@@ -3870,7 +3868,7 @@ interface LocatorAssertions {
     caret?: "hide"|"initial";
 
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -3910,7 +3908,7 @@ interface LocatorAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
 
@@ -3952,7 +3950,7 @@ interface LocatorAssertions {
     caret?: "hide"|"initial";
 
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -3992,7 +3990,7 @@ interface LocatorAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
 
@@ -4205,7 +4203,7 @@ interface PageAssertions {
     };
 
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -4251,7 +4249,7 @@ interface PageAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
 
@@ -4317,7 +4315,7 @@ interface PageAssertions {
     };
 
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -4363,7 +4361,7 @@ interface PageAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
 
@@ -4452,7 +4450,7 @@ interface SnapshotAssertions {
    */
   toMatchSnapshot(name: string|Array<string>, options?: {
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -4471,7 +4469,7 @@ interface SnapshotAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
   }): void;
@@ -4505,7 +4503,7 @@ interface SnapshotAssertions {
    */
   toMatchSnapshot(options?: {
     /**
-     * A comparator function to use when comparing images.
+     * A comparator function to use when comparing images. Defaults to `"pixelmatch"`.
      */
     comparator?: string;
 
@@ -4529,7 +4527,7 @@ interface SnapshotAssertions {
     /**
      * An acceptable perceived color difference in the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) between the
      * same pixel in compared images, between zero (strict) and one (lax), default is configurable with
-     * `TestConfig.expect`. Defaults to `0.2`.
+     * `TestConfig.expect`. Defaults to `0.2`. This option is used by "pixelmatch" image comparator.
      */
     threshold?: number;
   }): void;
@@ -4642,9 +4640,8 @@ interface TestProject {
       /**
        * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
        * `1` (lax). `"pixelmatch"` comparator computes color difference in
-       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"`
+       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used
-       * comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults
+       * by `pixelmatch` image comparator.
-       * `threshold` value to `0.01`.
        */
       threshold?: number;
 
@@ -4692,9 +4689,8 @@ interface TestProject {
       /**
        * an acceptable perceived color difference between the same pixel in compared images, ranging from `0` (strict) and
        * `1` (lax). `"pixelmatch"` comparator computes color difference in
-       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. `"ssim-cie94"`
+       * [YIQ color space](https://en.wikipedia.org/wiki/YIQ) and defaults `threshold` value to `0.2`. This option is used
-       * comparator computes color difference by [CIE94](https://en.wikipedia.org/wiki/Color_difference#CIE94) and defaults
+       * by `pixelmatch` image comparator.
-       * `threshold` value to `0.01`.
        */
       threshold?: number;