cherry-pick(#14174): fix(types): fix the toHaveScreenshot types (#14194)

Co-authored-by: Andrey Lushnikov <aslushnikov@gmail.com>
Co-authored-by: Pavel Feldman <pavel.feldman@gmail.com>

docs/src/api/class-locatorassertions.md

@@ -1002,7 +1002,7 @@ Property value.
 ### option: LocatorAssertions.toHaveJSProperty.timeout = %%-csharp-java-python-assertions-timeout-%%
 
 
-## async method: LocatorAssertions.toHaveScreenshot
+## async method: LocatorAssertions.toHaveScreenshot#1
 * langs: js
 
 Ensures that [Locator] resolves to a given screenshot. This function will re-take
@@ -1013,27 +1013,47 @@ yield the same result, and save the last one as an expectation.
 
 ```js
 const locator = page.locator('button');
-await expect(locator).toHaveScreenshot();
+await expect(locator).toHaveScreenshot('image.png');
 ```
 
-### option: LocatorAssertions.toHaveScreenshot.timeout = %%-js-assertions-timeout-%%
-### option: LocatorAssertions.toHaveScreenshot.timeout = %%-csharp-java-python-assertions-timeout-%%
-
-### option: LocatorAssertions.toHaveScreenshot.animations = %%-screenshot-option-animations-%%
+### param: LocatorAssertions.toHaveScreenshot#1.name
+- `name` <[string]|[Array]<[string]>>
 
-### option: LocatorAssertions.toHaveScreenshot.caret = %%-screenshot-option-caret-%%
+Snapshot name.
 
-### option: LocatorAssertions.toHaveScreenshot.mask = %%-screenshot-option-mask-%%
+### option: LocatorAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%%
+### option: LocatorAssertions.toHaveScreenshot#1.animations = %%-screenshot-option-animations-%%
+### option: LocatorAssertions.toHaveScreenshot#1.caret = %%-screenshot-option-caret-%%
+### option: LocatorAssertions.toHaveScreenshot#1.mask = %%-screenshot-option-mask-%%
+### option: LocatorAssertions.toHaveScreenshot#1.omitBackground = %%-screenshot-option-omit-background-%%
+### option: LocatorAssertions.toHaveScreenshot#1.scale = %%-screenshot-option-scale-%%
+### option: LocatorAssertions.toHaveScreenshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: LocatorAssertions.toHaveScreenshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: LocatorAssertions.toHaveScreenshot#1.threshold = %%-assertions-threshold-%%
 
-### option: LocatorAssertions.toHaveScreenshot.omitBackground = %%-screenshot-option-omit-background-%%
+## async method: LocatorAssertions.toHaveScreenshot#2
+* langs: js
 
-### option: LocatorAssertions.toHaveScreenshot.scale = %%-screenshot-option-scale-%%
+Ensures that [Locator] resolves to a given screenshot. This function will re-take
+screenshots until it matches with the saved expectation.
 
-### option: LocatorAssertions.toHaveScreenshot.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+If there's no expectation yet, it will wait until two consecutive screenshots
+yield the same result, and save the last one as an expectation.
 
-### option: LocatorAssertions.toHaveScreenshot.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+```js
+const locator = page.locator('button');
+await expect(locator).toHaveScreenshot();
+```
 
-### option: LocatorAssertions.toHaveScreenshot.threshold = %%-assertions-threshold-%%
+### option: LocatorAssertions.toHaveScreenshot#2.timeout = %%-js-assertions-timeout-%%
+### option: LocatorAssertions.toHaveScreenshot#2.animations = %%-screenshot-option-animations-%%
+### option: LocatorAssertions.toHaveScreenshot#2.caret = %%-screenshot-option-caret-%%
+### option: LocatorAssertions.toHaveScreenshot#2.mask = %%-screenshot-option-mask-%%
+### option: LocatorAssertions.toHaveScreenshot#2.omitBackground = %%-screenshot-option-omit-background-%%
+### option: LocatorAssertions.toHaveScreenshot#2.scale = %%-screenshot-option-scale-%%
+### option: LocatorAssertions.toHaveScreenshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: LocatorAssertions.toHaveScreenshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: LocatorAssertions.toHaveScreenshot#2.threshold = %%-assertions-threshold-%%
 
 
 ## async method: LocatorAssertions.toHaveText

docs/src/api/class-pageassertions.md

@@ -114,7 +114,7 @@ Expected substring or RegExp.
 ### option: PageAssertions.NotToHaveURL.timeout = %%-csharp-java-python-assertions-timeout-%%
 
 
-## async method: PageAssertions.toHaveScreenshot
+## async method: PageAssertions.toHaveScreenshot#1
 * langs: js
 
 Ensures that the page resolves to a given screenshot. This function will re-take
@@ -124,31 +124,51 @@ If there's no expectation yet, it will wait until two consecutive screenshots
 yield the same result, and save the last one as an expectation.
 
 ```js
-await expect(page).toHaveScreenshot();
+await expect(page).toHaveScreenshot('image.png');
 ```
 
-### option: PageAssertions.toHaveScreenshot.timeout = %%-js-assertions-timeout-%%
-### option: PageAssertions.toHaveScreenshot.timeout = %%-csharp-java-python-assertions-timeout-%%
-
-### option: PageAssertions.toHaveScreenshot.animations = %%-screenshot-option-animations-%%
-
-### option: PageAssertions.toHaveScreenshot.caret = %%-screenshot-option-caret-%%
+### param: PageAssertions.toHaveScreenshot#1.name
+- `name` <[string]|[Array]<[string]>>
 
-### option: PageAssertions.toHaveScreenshot.clip = %%-screenshot-option-clip-%%
+Snapshot name.
 
-### option: PageAssertions.toHaveScreenshot.fullPage = %%-screenshot-option-full-page-%%
+### option: PageAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%%
+### option: PageAssertions.toHaveScreenshot#1.animations = %%-screenshot-option-animations-%%
+### option: PageAssertions.toHaveScreenshot#1.caret = %%-screenshot-option-caret-%%
+### option: PageAssertions.toHaveScreenshot#1.clip = %%-screenshot-option-clip-%%
+### option: PageAssertions.toHaveScreenshot#1.fullPage = %%-screenshot-option-full-page-%%
+### option: PageAssertions.toHaveScreenshot#1.mask = %%-screenshot-option-mask-%%
+### option: PageAssertions.toHaveScreenshot#1.omitBackground = %%-screenshot-option-omit-background-%%
+### option: PageAssertions.toHaveScreenshot#1.scale = %%-screenshot-option-scale-%%
+### option: PageAssertions.toHaveScreenshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: PageAssertions.toHaveScreenshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: PageAssertions.toHaveScreenshot#1.threshold = %%-assertions-threshold-%%
 
-### option: PageAssertions.toHaveScreenshot.mask = %%-screenshot-option-mask-%%
 
-### option: PageAssertions.toHaveScreenshot.omitBackground = %%-screenshot-option-omit-background-%%
+## async method: PageAssertions.toHaveScreenshot#2
+* langs: js
 
-### option: PageAssertions.toHaveScreenshot.scale = %%-screenshot-option-scale-%%
+Ensures that the page resolves to a given screenshot. This function will re-take
+screenshots until it matches with the saved expectation.
 
-### option: PageAssertions.toHaveScreenshot.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+If there's no expectation yet, it will wait until two consecutive screenshots
+yield the same result, and save the last one as an expectation.
 
-### option: PageAssertions.toHaveScreenshot.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+```js
+await expect(page).toHaveScreenshot();
+```
 
-### option: PageAssertions.toHaveScreenshot.threshold = %%-assertions-threshold-%%
+### option: PageAssertions.toHaveScreenshot#2.timeout = %%-js-assertions-timeout-%%
+### option: PageAssertions.toHaveScreenshot#2.animations = %%-screenshot-option-animations-%%
+### option: PageAssertions.toHaveScreenshot#2.caret = %%-screenshot-option-caret-%%
+### option: PageAssertions.toHaveScreenshot#2.clip = %%-screenshot-option-clip-%%
+### option: PageAssertions.toHaveScreenshot#2.fullPage = %%-screenshot-option-full-page-%%
+### option: PageAssertions.toHaveScreenshot#2.mask = %%-screenshot-option-mask-%%
+### option: PageAssertions.toHaveScreenshot#2.omitBackground = %%-screenshot-option-omit-background-%%
+### option: PageAssertions.toHaveScreenshot#2.scale = %%-screenshot-option-scale-%%
+### option: PageAssertions.toHaveScreenshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%
+### option: PageAssertions.toHaveScreenshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%
+### option: PageAssertions.toHaveScreenshot#2.threshold = %%-assertions-threshold-%%
 
 
 ## async method: PageAssertions.toHaveTitle

docs/src/release-notes-js.md

@@ -59,7 +59,7 @@ title: "Release notes"
   await submitButton.click();
   ```
 
-- New web-first assertions [`method: PageAssertions.toHaveScreenshot`] and [`method: LocatorAssertions.toHaveScreenshot`] that
+- New web-first assertions [`method: PageAssertions.toHaveScreenshot#1`] and [`method: LocatorAssertions.toHaveScreenshot#1`] that
   wait for screenshot stabilization and enhances test reliability.
 
   The new assertions has screenshot-specific defaults, such as:
@@ -71,7 +71,7 @@ title: "Release notes"
   await expect(page).toHaveScreenshot();
   ```
 
-  The new [`method: PageAssertions.toHaveScreenshot`] saves screenshots at the same
+  The new [`method: PageAssertions.toHaveScreenshot#1`] saves screenshots at the same
   location as [`method: ScreenshotAssertions.toMatchSnapshot#1`].
 
 

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

@@ -36,7 +36,7 @@ export default config;
 ## property: TestConfig.expect
 - type: ?<[Object]>
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
-  - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot`] method.
+  - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
     - `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). Defaults 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.
@@ -419,7 +419,7 @@ export default config;
 * experimental
 - type: ?<[string]>
 
-The base directory, relative to the config file, for screenshot files created with [`method: PageAssertions.toHaveScreenshot`]. Defaults to
+The base directory, relative to the config file, for screenshot files created with [`method: PageAssertions.toHaveScreenshot#1`]. Defaults to
 
 ```
 <directory-of-configuration-file>/__screenshots__/<platform name>/<project name>

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

@@ -107,7 +107,7 @@ export default config;
 ## property: TestProject.expect
 - type: ?<[Object]>
   - `timeout` ?<[int]> Default timeout for async expect matchers in milliseconds, defaults to 5000ms.
-  - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot`] method.
+  - `toHaveScreenshot` ?<[Object]> Configuration for the [`method: PageAssertions.toHaveScreenshot#1`] method.
     - `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). Defaults 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.