diff --git a/docs/src/api/class-locatorassertions.md b/docs/src/api/class-locatorassertions.md index 80a355b974516..df22b9d46b73b 100644 --- a/docs/src/api/class-locatorassertions.md +++ b/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 diff --git a/docs/src/api/class-pageassertions.md b/docs/src/api/class-pageassertions.md index 835bcfbf4cf7c..4e6fc70a0fbbc 100644 --- a/docs/src/api/class-pageassertions.md +++ b/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 diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md index 0c3c2ce61c4cb..8f980c3ef8553 100644 --- a/docs/src/release-notes-js.md +++ b/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`]. diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md index 14e01de17b835..88142dc48fb8c 100644 --- a/docs/src/test-api/class-testconfig.md +++ b/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 ``` /__screenshots__// diff --git a/docs/src/test-api/class-testproject.md b/docs/src/test-api/class-testproject.md index 5bf818920aeb4..04a7842a2376c 100644 --- a/docs/src/test-api/class-testproject.md +++ b/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. diff --git a/packages/playwright-test/types/test.d.ts b/packages/playwright-test/types/test.d.ts index b206e25e2145a..c7e1e050d1d26 100644 --- a/packages/playwright-test/types/test.d.ts +++ b/packages/playwright-test/types/test.d.ts @@ -486,7 +486,7 @@ interface TestConfig { /** * Configuration for the - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) + * [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. */ toHaveScreenshot?: { @@ -3327,6 +3327,82 @@ interface LocatorAssertions { timeout?: number; }): Promise; + /** + * Ensures that [Locator] resolves to a given screenshot. This function will re-take screenshots until it matches with the + * saved expectation. + * + * 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 + * const locator = page.locator('button'); + * await expect(locator).toHaveScreenshot('image.png'); + * ``` + * + * @param name Snapshot name. + * @param options + */ + toHaveScreenshot(name: string|Array, options?: { + /** + * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different treatment + * depending on their duration: + * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. + * - infinite animations are canceled to initial state, and then played over after the screenshot. + * + * Defaults to `"allow"` that leaves animations untouched. + */ + animations?: "disabled"|"allow"; + + /** + * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be changed. + * Defaults to `"hide"`. + */ + caret?: "hide"|"initial"; + + /** + * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlayed with a pink box + * `#FF00FF` that completely covers its bounding box. + */ + mask?: Array; + + /** + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixelRatio?: number; + + /** + * An acceptable amount of pixels that could be different, default is configurable with `TestConfig.expect`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixels?: number; + + /** + * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. + * Defaults to `false`. + */ + omitBackground?: boolean; + + /** + * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will + * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of + * high-dpi devices will be twice as large or even larger. Defaults to `"device"`. + */ + scale?: "css"|"device"; + + /** + * 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`. + */ + threshold?: number; + + /** + * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`. + */ + timeout?: number; + }): Promise; + /** * Ensures that [Locator] resolves to a given screenshot. This function will re-take screenshots until it matches with the * saved expectation. @@ -3481,6 +3557,112 @@ interface PageAssertions { */ not: PageAssertions; + /** + * Ensures that the page resolves to a given screenshot. This function will re-take screenshots until it matches with the + * saved expectation. + * + * 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('image.png'); + * ``` + * + * @param name Snapshot name. + * @param options + */ + toHaveScreenshot(name: string|Array, options?: { + /** + * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different treatment + * depending on their duration: + * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. + * - infinite animations are canceled to initial state, and then played over after the screenshot. + * + * Defaults to `"allow"` that leaves animations untouched. + */ + animations?: "disabled"|"allow"; + + /** + * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be changed. + * Defaults to `"hide"`. + */ + caret?: "hide"|"initial"; + + /** + * An object which specifies clipping of the resulting image. Should have the following fields: + */ + clip?: { + /** + * x-coordinate of top-left corner of clip area + */ + x: number; + + /** + * y-coordinate of top-left corner of clip area + */ + y: number; + + /** + * width of clipping area + */ + width: number; + + /** + * height of clipping area + */ + height: number; + }; + + /** + * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to + * `false`. + */ + fullPage?: boolean; + + /** + * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlayed with a pink box + * `#FF00FF` that completely covers its bounding box. + */ + mask?: Array; + + /** + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixelRatio?: number; + + /** + * An acceptable amount of pixels that could be different, default is configurable with `TestConfig.expect`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixels?: number; + + /** + * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. + * Defaults to `false`. + */ + omitBackground?: boolean; + + /** + * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will + * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of + * high-dpi devices will be twice as large or even larger. Defaults to `"device"`. + */ + scale?: "css"|"device"; + + /** + * 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`. + */ + threshold?: number; + + /** + * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`. + */ + timeout?: number; + }): Promise; + /** * Ensures that the page resolves to a given screenshot. This function will re-take screenshots until it matches with the * saved expectation. @@ -3820,7 +4002,7 @@ interface TestProject { /** * Configuration for the - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) + * [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. */ toHaveScreenshot?: { diff --git a/tests/config/experimental.d.ts b/tests/config/experimental.d.ts index 3d60ed8af997f..c1355b05ad92c 100644 --- a/tests/config/experimental.d.ts +++ b/tests/config/experimental.d.ts @@ -16662,7 +16662,7 @@ interface TestConfig { /** * Configuration for the - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) + * [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. */ toHaveScreenshot?: { @@ -16966,7 +16966,7 @@ interface TestConfig { /** * The base directory, relative to the config file, for screenshot files created with - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot). + * [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1). * Defaults to * * ``` @@ -19533,6 +19533,82 @@ interface LocatorAssertions { timeout?: number; }): Promise; + /** + * Ensures that [Locator] resolves to a given screenshot. This function will re-take screenshots until it matches with the + * saved expectation. + * + * 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 + * const locator = page.locator('button'); + * await expect(locator).toHaveScreenshot('image.png'); + * ``` + * + * @param name Snapshot name. + * @param options + */ + toHaveScreenshot(name: string|Array, options?: { + /** + * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different treatment + * depending on their duration: + * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. + * - infinite animations are canceled to initial state, and then played over after the screenshot. + * + * Defaults to `"allow"` that leaves animations untouched. + */ + animations?: "disabled"|"allow"; + + /** + * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be changed. + * Defaults to `"hide"`. + */ + caret?: "hide"|"initial"; + + /** + * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlayed with a pink box + * `#FF00FF` that completely covers its bounding box. + */ + mask?: Array; + + /** + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixelRatio?: number; + + /** + * An acceptable amount of pixels that could be different, default is configurable with `TestConfig.expect`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixels?: number; + + /** + * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. + * Defaults to `false`. + */ + omitBackground?: boolean; + + /** + * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will + * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of + * high-dpi devices will be twice as large or even larger. Defaults to `"device"`. + */ + scale?: "css"|"device"; + + /** + * 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`. + */ + threshold?: number; + + /** + * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`. + */ + timeout?: number; + }): Promise; + /** * Ensures that [Locator] resolves to a given screenshot. This function will re-take screenshots until it matches with the * saved expectation. @@ -19687,6 +19763,112 @@ interface PageAssertions { */ not: PageAssertions; + /** + * Ensures that the page resolves to a given screenshot. This function will re-take screenshots until it matches with the + * saved expectation. + * + * 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('image.png'); + * ``` + * + * @param name Snapshot name. + * @param options + */ + toHaveScreenshot(name: string|Array, options?: { + /** + * When set to `"disabled"`, stops CSS animations, CSS transitions and Web Animations. Animations get different treatment + * depending on their duration: + * - finite animations are fast-forwarded to completion, so they'll fire `transitionend` event. + * - infinite animations are canceled to initial state, and then played over after the screenshot. + * + * Defaults to `"allow"` that leaves animations untouched. + */ + animations?: "disabled"|"allow"; + + /** + * When set to `"hide"`, screenshot will hide text caret. When set to `"initial"`, text caret behavior will not be changed. + * Defaults to `"hide"`. + */ + caret?: "hide"|"initial"; + + /** + * An object which specifies clipping of the resulting image. Should have the following fields: + */ + clip?: { + /** + * x-coordinate of top-left corner of clip area + */ + x: number; + + /** + * y-coordinate of top-left corner of clip area + */ + y: number; + + /** + * width of clipping area + */ + width: number; + + /** + * height of clipping area + */ + height: number; + }; + + /** + * When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport. Defaults to + * `false`. + */ + fullPage?: boolean; + + /** + * Specify locators that should be masked when the screenshot is taken. Masked elements will be overlayed with a pink box + * `#FF00FF` that completely covers its bounding box. + */ + mask?: Array; + + /** + * An acceptable ratio of pixels that are different to the total amount of pixels, between `0` and `1`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixelRatio?: number; + + /** + * An acceptable amount of pixels that could be different, default is configurable with `TestConfig.expect`. Default is + * configurable with `TestConfig.expect`. Unset by default. + */ + maxDiffPixels?: number; + + /** + * Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images. + * Defaults to `false`. + */ + omitBackground?: boolean; + + /** + * When set to `"css"`, screenshot will have a single pixel per each css pixel on the page. For high-dpi devices, this will + * keep screenshots small. Using `"device"` option will produce a single pixel per each device pixel, so screenhots of + * high-dpi devices will be twice as large or even larger. Defaults to `"device"`. + */ + scale?: "css"|"device"; + + /** + * 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`. + */ + threshold?: number; + + /** + * Time to retry the assertion for. Defaults to `timeout` in `TestConfig.expect`. + */ + timeout?: number; + }): Promise; + /** * Ensures that the page resolves to a given screenshot. This function will re-take screenshots until it matches with the * saved expectation. @@ -20026,7 +20208,7 @@ interface TestProject { /** * Configuration for the - * [pageAssertions.toHaveScreenshot([options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot) + * [pageAssertions.toHaveScreenshot(name[, options])](https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1) * method. */ toHaveScreenshot?: {