fix: revert toMatchSnapshot deprecation

docs/src/api/class-snapshotassertions.md

@@ -2,75 +2,24 @@
 * since: v1.20
 * langs: js
 
-:::tip
-For visual regression testing, use [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] instead.
-:::
-
-Playwright provides methods for comparing text values with expected values stored in snapshot files.
+Playwright provides methods for comparing page and element screenshots with
+expected values stored in files.
 
 ```js
-expect(text).toMatchSnapshot('snapshot.txt');
+expect(screenshot).toMatchSnapshot('landing-page.png');
 ```
 
 ## method: SnapshotAssertions.toMatchSnapshot#1
 * since: v1.22
 
-Ensures that the passed [string] matches the expected snapshot stored in the test snapshots directory.
-
-**Usage**
-
-```js
-// Basic usage.
-expect(await page.title()).toMatchSnapshot('page-title.txt');
-
-// Bring some structure to your snapshot files by passing file path segments.
-expect(await page.title()).toMatchSnapshot(['page-title', 'step1.txt']);
-expect(await page.title()).toMatchSnapshot(['page-title', 'step2.txt']);
-```
-
-Note that matching snapshots only work with Playwright test runner.
-
-### param: SnapshotAssertions.toMatchSnapshot#1.name
-* since: v1.22
-- `name` <[string]|[Array]<[string]>>
-
-Snapshot name.
-
-## method: SnapshotAssertions.toMatchSnapshot#2
-* since: v1.22
+:::caution
+To compare screenshots, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
+:::
 
 Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
 
 **Usage**
 
-```js
-// Basic usage.
-expect(await page.title()).toMatchSnapshot();
-
-// Configure the snapshot name.
-expect(await page.title()).toMatchSnapshot({
-  name: 'page-title.txt',
-});
-```
-
-Note that matching snapshots only work with Playwright test runner.
-
-### option: SnapshotAssertions.toMatchSnapshot#2.name
-* since: v1.22
-- `name` <[string]|[Array]<[string]>>
-
-Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
-
-
-
-## method: SnapshotAssertions.toMatchSnapshot#3
-* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
-* since: v1.22
-
-Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
-
-**Usage**
-
 ```js
 // Basic usage.
 expect(await page.screenshot()).toMatchSnapshot('landing-page.png');
@@ -92,26 +41,29 @@ Learn more about [visual comparisons](../test-snapshots.md).
 
 Note that matching snapshots only work with Playwright test runner.
 
-### param: SnapshotAssertions.toMatchSnapshot#3.name
+### param: SnapshotAssertions.toMatchSnapshot#1.name
 * since: v1.22
 - `name` <[string]|[Array]<[string]>>
 
 Snapshot name.
 
-### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#3.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: SnapshotAssertions.toMatchSnapshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#3.threshold = %%-assertions-threshold-%%
+### option: SnapshotAssertions.toMatchSnapshot#1.threshold = %%-assertions-threshold-%%
 * since: v1.22
 
-## method: SnapshotAssertions.toMatchSnapshot#4
-* deprecated: To avoid flakiness, use [`method: PageAssertions.toHaveScreenshot#1`] instead.
+## method: SnapshotAssertions.toMatchSnapshot#2
 * since: v1.22
 
-Ensures that the passed [Buffer] matches the expected snapshot stored in the test snapshots directory.
+:::caution
+To compare screenshots, use [`method: PageAssertions.toHaveScreenshot#2`] instead.
+:::
+
+Ensures that passed value, either a [string] or a [Buffer], matches the expected snapshot stored in the test snapshots directory.
 
 **Usage**
 
@@ -135,18 +87,17 @@ Learn more about [visual comparisons](../test-snapshots.md).
 
 Note that matching snapshots only work with Playwright test runner.
 
-### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#4.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: SnapshotAssertions.toMatchSnapshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
 * since: v1.22
 
-### option: SnapshotAssertions.toMatchSnapshot#4.name
+### option: SnapshotAssertions.toMatchSnapshot#2.name
 * since: v1.22
 - `name` <[string]|[Array]<[string]>>
 
 Snapshot name. If not passed, the test name and ordinals are used when called multiple times.
 
-### option: SnapshotAssertions.toMatchSnapshot#4.threshold = %%-assertions-threshold-%%
+### option: SnapshotAssertions.toMatchSnapshot#2.threshold = %%-assertions-threshold-%%
 * since: v1.22
-

docs/src/release-notes-js.md

@@ -28,8 +28,6 @@ import LiteYouTube from '@site/src/components/LiteYouTube';
   Please use [`method: Locator.fill`] instead which is much faster. Use
   [`method: Locator.pressSequentially`] only if there is a special keyboard
   handling on the page, and you need to press keys one-by-one.
-* The method [`method: SnapshotAssertions.toMatchSnapshot#1`] is deprecated in
-  favor of [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`].
 
 ### Breaking Changes: Playwright no longer downloads browsers automatically
 

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

@@ -41,18 +41,18 @@ export default defineConfig({
 - type: ?<[Object]>
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
   - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
-    - `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`.
-    - `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.
+    - `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`.
+    - `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"`.
     - `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`.
     - `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
-    - `threshold` ?<[float]> **Deprecated.** 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`.
-    - `maxDiffPixels` ?<[int]> **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
-    - `maxDiffPixelRatio` ?<[float]> **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
+    - `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`.
+    - `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.
 
-Configuration for the `expect` assertion library. Learn more about [test configuration](../test-configuration.md#expect-options).
+Configuration for the `expect` assertion library. Learn more about [various timeouts](../test-timeouts.md).
 
 **Usage**
 
@@ -62,7 +62,7 @@ import { defineConfig } from '@playwright/test';
 export default defineConfig({
   expect: {
     timeout: 10000,
-    toHaveScreenshot: {
+    toMatchSnapshot: {
       maxDiffPixels: 10,
     },
   },
@@ -196,7 +196,7 @@ export default defineConfig({
 * since: v1.26
 - type: ?<[boolean]>
 
-Whether to skip snapshot expectations, such as [`method: PageAssertions.toHaveScreenshot#1`] and [`method: SnapshotAssertions.toMatchSnapshot#1`].
+Whether to skip snapshot expectations, such as `expect(value).toMatchSnapshot()` and `await expect(page).toHaveScreenshot()`.
 
 **Usage**
 
@@ -296,7 +296,7 @@ test('example test', async ({}, testInfo) => {
 * discouraged: Use [`property: TestConfig.snapshotPathTemplate`] to configure snapshot paths.
 - type: ?<[string]>
 
-The base directory, relative to the config file, for screenshot files created with [`method: PageAssertions.toHaveScreenshot#1`]. Defaults to [`property: TestConfig.testDir`].
+The base directory, relative to the config file, for snapshot files created with `toMatchSnapshot`. Defaults to [`property: TestConfig.testDir`].
 
 **Usage**
 

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

@@ -397,7 +397,7 @@ Use of [`property: TestInfo.snapshotSuffix`] is discouraged. Please use [`proper
 snapshot paths.
 :::
 
-Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case [`method: PageAssertions.toHaveScreenshot#1`] will use different snapshots depending on the platform. Learn more about [snapshots](../test-snapshots.md).
+Suffix used to differentiate snapshots between multiple test configurations. For example, if snapshots depend on the platform, you can set `testInfo.snapshotSuffix` equal to `process.platform`. In this case `expect(value).toMatchSnapshot(snapshotName)` will use different snapshots depending on the platform. Learn more about [snapshots](../test-snapshots.md).
 
 ## property: TestInfo.status
 * since: v1.10

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

@@ -91,16 +91,16 @@ export default defineConfig({
 - type: ?<[Object]>
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
   - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
-    - `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`.
-    - `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.
+    - `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`.
+    - `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"`.
     - `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`.
     - `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
   - `toMatchSnapshot` ?<[Object]> Configuration for the [`method: SnapshotAssertions.toMatchSnapshot#1`] method.
-    - `threshold` ?<[float]> **Deprecated.** 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`.
-    - `maxDiffPixels` ?<[int]> **Deprecated.** An acceptable amount of pixels that could be different, unset by default.
-    - `maxDiffPixelRatio` ?<[float]> **Deprecated.** An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1` , unset by default.
+    - `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`.
+    - `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.
 
 Configuration for the `expect` assertion library.
 

docs/src/test-assertions-js.md

@@ -82,7 +82,6 @@ Prefer [auto-retrying](#auto-retrying-assertions) assertions whenever possible.
 | [`method: GenericAssertions.toHaveProperty`] | Object has a property |
 | [`method: GenericAssertions.toMatch`] | String matches a regular expression |
 | [`method: GenericAssertions.toMatchObject`] | Object contains specified properties |
-| [`method: SnapshotAssertions.toMatchSnapshot#1`] | String equals a reference value, stored in a snapshot file |
 | [`method: GenericAssertions.toStrictEqual`] | Value is similar, including property types |
 | [`method: GenericAssertions.toThrow`] | Function throws an error |
 | [`method: GenericAssertions.any`] | Matches any instance of a class/primitive |

docs/src/test-configuration-js.md

@@ -131,15 +131,22 @@ export default defineConfig({
       // An acceptable amount of pixels that could be different, unset by default.
       maxDiffPixels: 10,
     },
+
+    toMatchSnapshot: {
+      // An acceptable ratio of pixels that are different to the
+      // total amount of pixels, between 0 and 1.
+      maxDiffPixelRatio: 0.1,
+    },
   },
 
 });
 ```
 
 | Option | Description |
 | :- | :- |
-| `expect.timeout` | [Web first assertions](./test-assertions.md) like `expect(locator).toHaveText()` have a separate timeout of 5 seconds by default. This is the maximum time the `expect()` should wait for the condition to be met. Learn more about [test and expect timeouts](./test-timeouts.md) and how to set them for a single test. |
-| `expect.toHaveScreenshot` | Configuration for [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] methods. |
+| [`property: TestConfig.expect`] | [Web first assertions](./test-assertions.md) like `expect(locator).toHaveText()` have a separate timeout of 5 seconds by default. This is the maximum time the `expect()` should wait for the condition to be met. Learn more about [test and expect timeouts](./test-timeouts.md) and how to set them for a single test. |
+| [`method: PageAssertions.toHaveScreenshot#1`] | Configuration for the `expect(locator).toHaveScreeshot()` method. |
+| [`method: SnapshotAssertions.toMatchSnapshot#1`]| Configuration for the `expect(locator).toMatchSnapshot()` method.|
 
 
 ### Add custom matchers using expect.extend