From 52d6c29e289bc8e66bd7467af1706d9e0e3bb8c3 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Tue, 14 Jul 2026 12:36:13 -0700 Subject: [PATCH 1/2] docs(test): mention webp as alternative snapshot format in toHaveScreenshot Reference: https://github.com/microsoft/playwright/issues/22984 --- docs/src/api/class-locatorassertions.md | 7 ++++++- docs/src/api/class-pageassertions.md | 7 ++++++- docs/src/test-snapshots-js.md | 6 ++++++ packages/playwright/types/test.d.ts | 18 ++++++++++++++++-- 4 files changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/src/api/class-locatorassertions.md b/docs/src/api/class-locatorassertions.md index 1c03272347166..b44cf3c9dbbbe 100644 --- a/docs/src/api/class-locatorassertions.md +++ b/docs/src/api/class-locatorassertions.md @@ -1992,6 +1992,9 @@ yield the same result, and then compare the last screenshot with the expectation ```js const locator = page.getByRole('button'); await expect(locator).toHaveScreenshot('image.png'); + +// Store the snapshot in the WebP format to reduce the file size. +await expect(locator).toHaveScreenshot('image.webp'); ``` Note that screenshot assertions only work with Playwright test runner. @@ -2000,7 +2003,7 @@ Note that screenshot assertions only work with Playwright test runner. * since: v1.23 - `name` <[string]|[Array]<[string]>> -Snapshot name. +Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless, but WebP files are usually smaller. ### option: LocatorAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%% * since: v1.23 @@ -2042,6 +2045,8 @@ Snapshot name. This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation. +The snapshot is stored in the PNG format. To store it in the WebP format instead, pass a snapshot name with the `.webp` extension. + **Usage** ```js diff --git a/docs/src/api/class-pageassertions.md b/docs/src/api/class-pageassertions.md index 2965f9a715561..96dc90f299e80 100644 --- a/docs/src/api/class-pageassertions.md +++ b/docs/src/api/class-pageassertions.md @@ -242,6 +242,9 @@ yield the same result, and then compare the last screenshot with the expectation ```js await expect(page).toHaveScreenshot('image.png'); + +// Store the snapshot in the WebP format to reduce the file size. +await expect(page).toHaveScreenshot('image.webp'); ``` Note that screenshot assertions only work with Playwright test runner. @@ -250,7 +253,7 @@ Note that screenshot assertions only work with Playwright test runner. * since: v1.23 - `name` <[string]|[Array]<[string]>> -Snapshot name. +Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless, but WebP files are usually smaller. ### option: PageAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%% * since: v1.23 @@ -298,6 +301,8 @@ Snapshot name. This function will wait until two consecutive page screenshots yield the same result, and then compare the last screenshot with the expectation. +The snapshot is stored in the PNG format. To store it in the WebP format instead, pass a snapshot name with the `.webp` extension. + **Usage** ```js diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index 5c64eccfbb762..71e3827da6997 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -50,6 +50,12 @@ The snapshot name `example-test-1-chromium-darwin.png` consists of a few parts: The snapshot name and path can be configured with [`property: TestConfig.snapshotPathTemplate`] in the playwright config. +Snapshots are stored as PNG by default. Give the snapshot a name with the `.webp` extension to store it in the WebP format instead — it is also lossless, but produces smaller files: + +```js +await expect(page).toHaveScreenshot('landing.webp'); +``` + > Note that `toHaveScreenshot()` also accepts an array of path segments to the snapshot file such as `expect().toHaveScreenshot(['relative', 'path', 'to', 'snapshot.png'])`. > However, this path must stay within the snapshots directory for each test file (i.e. `a.spec.js-snapshots`), otherwise it will throw. diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 70a6d41cd09a7..2b0907d0a5fee 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -9549,10 +9549,14 @@ interface LocatorAssertions { * ```js * const locator = page.getByRole('button'); * await expect(locator).toHaveScreenshot('image.png'); + * + * // Store the snapshot in the WebP format to reduce the file size. + * await expect(locator).toHaveScreenshot('image.webp'); * ``` * * Note that screenshot assertions only work with Playwright test runner. - * @param name Snapshot name. + * @param name Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. + * Both formats are lossless, but WebP files are usually smaller. * @param options */ toHaveScreenshot(name: string|ReadonlyArray, options?: { @@ -9638,6 +9642,9 @@ interface LocatorAssertions { * This function will wait until two consecutive locator screenshots yield the same result, and then compare the last * screenshot with the expectation. * + * The snapshot is stored in the PNG format. To store it in the WebP format instead, pass a snapshot name with the + * `.webp` extension. + * * **Usage** * * ```js @@ -9976,10 +9983,14 @@ interface PageAssertions { * * ```js * await expect(page).toHaveScreenshot('image.png'); + * + * // Store the snapshot in the WebP format to reduce the file size. + * await expect(page).toHaveScreenshot('image.webp'); * ``` * * Note that screenshot assertions only work with Playwright test runner. - * @param name Snapshot name. + * @param name Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. + * Both formats are lossless, but WebP files are usually smaller. * @param options */ toHaveScreenshot(name: string|ReadonlyArray, options?: PageAssertionsToHaveScreenshotOptions): Promise; @@ -9988,6 +9999,9 @@ interface PageAssertions { * This function will wait until two consecutive page screenshots yield the same result, and then compare the last * screenshot with the expectation. * + * The snapshot is stored in the PNG format. To store it in the WebP format instead, pass a snapshot name with the + * `.webp` extension. + * * **Usage** * * ```js From 62a994e6e5a7773923b98e15cdcf0dfc5f8a9cd6 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Tue, 14 Jul 2026 14:02:44 -0700 Subject: [PATCH 2/2] docs(test): drop file size claims from webp snapshot docs --- docs/src/api/class-locatorassertions.md | 4 ++-- docs/src/api/class-pageassertions.md | 4 ++-- docs/src/test-snapshots-js.md | 2 +- packages/playwright/types/test.d.ts | 8 ++++---- 4 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/src/api/class-locatorassertions.md b/docs/src/api/class-locatorassertions.md index b44cf3c9dbbbe..3a91e540a8a25 100644 --- a/docs/src/api/class-locatorassertions.md +++ b/docs/src/api/class-locatorassertions.md @@ -1993,7 +1993,7 @@ yield the same result, and then compare the last screenshot with the expectation const locator = page.getByRole('button'); await expect(locator).toHaveScreenshot('image.png'); -// Store the snapshot in the WebP format to reduce the file size. +// Store the snapshot in the WebP format. await expect(locator).toHaveScreenshot('image.webp'); ``` @@ -2003,7 +2003,7 @@ Note that screenshot assertions only work with Playwright test runner. * since: v1.23 - `name` <[string]|[Array]<[string]>> -Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless, but WebP files are usually smaller. +Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless. ### option: LocatorAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%% * since: v1.23 diff --git a/docs/src/api/class-pageassertions.md b/docs/src/api/class-pageassertions.md index 96dc90f299e80..5747aa609b597 100644 --- a/docs/src/api/class-pageassertions.md +++ b/docs/src/api/class-pageassertions.md @@ -243,7 +243,7 @@ yield the same result, and then compare the last screenshot with the expectation ```js await expect(page).toHaveScreenshot('image.png'); -// Store the snapshot in the WebP format to reduce the file size. +// Store the snapshot in the WebP format. await expect(page).toHaveScreenshot('image.webp'); ``` @@ -253,7 +253,7 @@ Note that screenshot assertions only work with Playwright test runner. * since: v1.23 - `name` <[string]|[Array]<[string]>> -Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless, but WebP files are usually smaller. +Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. Both formats are lossless. ### option: PageAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%% * since: v1.23 diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md index 71e3827da6997..ed69bbcde2856 100644 --- a/docs/src/test-snapshots-js.md +++ b/docs/src/test-snapshots-js.md @@ -50,7 +50,7 @@ The snapshot name `example-test-1-chromium-darwin.png` consists of a few parts: The snapshot name and path can be configured with [`property: TestConfig.snapshotPathTemplate`] in the playwright config. -Snapshots are stored as PNG by default. Give the snapshot a name with the `.webp` extension to store it in the WebP format instead — it is also lossless, but produces smaller files: +Snapshots are stored as PNG by default. Give the snapshot a name with the `.webp` extension to store it in the WebP format instead, it is also lossless: ```js await expect(page).toHaveScreenshot('landing.webp'); diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts index 2b0907d0a5fee..d30c7f240de59 100644 --- a/packages/playwright/types/test.d.ts +++ b/packages/playwright/types/test.d.ts @@ -9550,13 +9550,13 @@ interface LocatorAssertions { * const locator = page.getByRole('button'); * await expect(locator).toHaveScreenshot('image.png'); * - * // Store the snapshot in the WebP format to reduce the file size. + * // Store the snapshot in the WebP format. * await expect(locator).toHaveScreenshot('image.webp'); * ``` * * Note that screenshot assertions only work with Playwright test runner. * @param name Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. - * Both formats are lossless, but WebP files are usually smaller. + * Both formats are lossless. * @param options */ toHaveScreenshot(name: string|ReadonlyArray, options?: { @@ -9984,13 +9984,13 @@ interface PageAssertions { * ```js * await expect(page).toHaveScreenshot('image.png'); * - * // Store the snapshot in the WebP format to reduce the file size. + * // Store the snapshot in the WebP format. * await expect(page).toHaveScreenshot('image.webp'); * ``` * * Note that screenshot assertions only work with Playwright test runner. * @param name Snapshot name. Must have a `.png` or `.webp` extension, the screenshot is captured in the corresponding format. - * Both formats are lossless, but WebP files are usually smaller. + * Both formats are lossless. * @param options */ toHaveScreenshot(name: string|ReadonlyArray, options?: PageAssertionsToHaveScreenshotOptions): Promise;