Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(test-runner): add expect.toHaveScreenshot.type config option (#42865)

Yury Semikhatsky7b4b3b0828ad
diff --git a/docs/src/test-api/class-testconfig.md b/docs/src/test-api/class-testconfig.md
index 443333a8f2..d84e3e2ab3 100644
--- a/docs/src/test-api/class-testconfig.md
+++ b/docs/src/test-api/class-testconfig.md
@@ -80,6 +80,7 @@ The structure of the git commit metadata is subject to change.
- `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: Page.screenshot.scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
- `stylePath` ?<[string]|[Array]<[string]>> See [`option: Page.screenshot.style`] in [`method: Page.screenshot`].
- `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`.
+ - `type` ?<[ScreenshotType]<"png"|"webp">> Format of the screenshots taken when the snapshot name is omitted, defaults to `"png"`. Snapshots with an explicit name use the format matching their `.png` or `.webp` extension.
- `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestConfig.snapshotPathTemplate`] for details.
- `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.
- `pathTemplate` ?<[string]> A template controlling location of the aria snapshots. See [`property: TestConfig.snapshotPathTemplate`] for details.
diff --git a/docs/src/test-api/class-testproject.md b/docs/src/test-api/class-testproject.md
index 59dce2f16f..dc75000c0b 100644
--- a/docs/src/test-api/class-testproject.md
+++ b/docs/src/test-api/class-testproject.md
@@ -130,6 +130,7 @@ Now `npx playwright test` only runs `chromium`, while `npx playwright test --pro
- `caret` ?<[ScreenshotCaret]<"hide"|"initial">> See [`option: Page.screenshot.caret`] in [`method: Page.screenshot`]. Defaults to `"hide"`.
- `scale` ?<[ScreenshotScale]<"css"|"device">> See [`option: Page.screenshot.scale`] in [`method: Page.screenshot`]. Defaults to `"css"`.
- `stylePath` ?<[string]|[Array]<[string]>> See [`option: Page.screenshot.style`] in [`method: Page.screenshot`].
+ - `type` ?<[ScreenshotType]<"png"|"webp">> Format of the screenshots taken when the snapshot name is omitted, defaults to `"png"`. Snapshots with an explicit name use the format matching their `.png` or `.webp` extension.
- `pathTemplate` ?<[string]> A template controlling location of the screenshots. See [`property: TestProject.snapshotPathTemplate`] for details.
- `timeout` ?<[int]> Default timeout for [`method: PageAssertions.toHaveScreenshot#1`] in milliseconds, defaults to the global expect timeout. Setting to `0` disables the timeout.
- `toMatchAriaSnapshot` ?<[Object]> Configuration for the [`method: LocatorAssertions.toMatchAriaSnapshot#2`] method.
diff --git a/docs/src/test-snapshots-js.md b/docs/src/test-snapshots-js.md
index 314dbddd4d..95d8fbc4b4 100644
--- a/docs/src/test-snapshots-js.md
+++ b/docs/src/test-snapshots-js.md
@@ -56,6 +56,20 @@ Snapshots are stored as PNG by default. Give the snapshot a name with the `.webp
await expect(page).toHaveScreenshot('landing.webp');
```
+To store all unnamed snapshots as WebP, set the `type` option in the [`property: TestConfig.expect`] configuration:
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ expect: {
+ toHaveScreenshot: {
+ type: '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/src/common/configLoader.ts b/packages/playwright/src/common/configLoader.ts
index 2cc4606103..6e2fa63afb 100644
--- a/packages/playwright/src/common/configLoader.ts
+++ b/packages/playwright/src/common/configLoader.ts
@@ -284,6 +284,11 @@ function validateProject(file: string, project: Project, title: string) {
throw errorWithFile(file, `${title}.testDir must be a string`);
}
+ if (project.expect?.toHaveScreenshot?.type !== undefined) {
+ if (!['png', 'webp'].includes(project.expect.toHaveScreenshot.type))
+ throw errorWithFile(file, `${title}.expect.toHaveScreenshot.type must be one of "png" or "webp"`);
+ }
+
for (const prop of ['testIgnore', 'testMatch'] as const) {
if (prop in project && project[prop] !== undefined) {
const value = project[prop];
diff --git a/packages/playwright/src/matchers/expect.ts b/packages/playwright/src/matchers/expect.ts
index a9e8191b08..11191bd59b 100644
--- a/packages/playwright/src/matchers/expect.ts
+++ b/packages/playwright/src/matchers/expect.ts
@@ -124,6 +124,7 @@ export type ExpectConfig = {
caret?: 'hide' | 'initial';
scale?: 'css' | 'device';
stylePath?: string | string[];
+ type?: 'png' | 'webp';
pathTemplate?: string;
timeout?: number;
_comparator?: string;
diff --git a/packages/playwright/src/worker/testInfo.ts b/packages/playwright/src/worker/testInfo.ts
index 2d8bbd6f36..af9eb9a629 100644
--- a/packages/playwright/src/worker/testInfo.ts
+++ b/packages/playwright/src/worker/testInfo.ts
@@ -566,7 +566,7 @@ export class TestInfoImpl implements TestInfo {
// NOTE: snapshot path must not ever change for backwards compatibility!
const snapshotNames = kind === 'aria' ? this._ariaSnapshotNames : this._snapshotNames;
- const defaultExtensions = { 'aria': '.aria.yml', 'screenshot': '.png', 'snapshot': '.txt' };
+ const defaultExtensions = { 'aria': '.aria.yml', 'screenshot': '.' + (this._projectInternal.expect?.toHaveScreenshot?.type ?? 'png'), 'snapshot': '.txt' };
const ariaAwareExtname = (filePath: string) => kind === 'aria' && filePath.endsWith('.aria.yml') ? '.aria.yml' : path.extname(filePath);
let subPath: string;
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 3c26c1be5a..322b41f8fe 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -271,6 +271,12 @@ interface TestProject<TestArgs = {}, WorkerArgs = {}> {
*/
stylePath?: string|Array<string>;
+ /**
+ * Format of the screenshots taken when the snapshot name is omitted, defaults to `"png"`. Snapshots with an explicit
+ * name use the format matching their `.png` or `.webp` extension.
+ */
+ type?: "png"|"webp";
+
/**
* A template controlling location of the screenshots. See
* [testProject.snapshotPathTemplate](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)
@@ -1218,6 +1224,12 @@ interface TestConfig<TestArgs = {}, WorkerArgs = {}> {
*/
threshold?: number;
+ /**
+ * Format of the screenshots taken when the snapshot name is omitted, defaults to `"png"`. Snapshots with an explicit
+ * name use the format matching their `.png` or `.webp` extension.
+ */
+ type?: "png"|"webp";
+
/**
* A template controlling location of the screenshots. See
* [testConfig.snapshotPathTemplate](https://playwright.dev/docs/api/class-testconfig#test-config-snapshot-path-template)
diff --git a/tests/playwright-test/to-have-screenshot.spec.ts b/tests/playwright-test/to-have-screenshot.spec.ts
index 642f991c5b..c725b2a130 100644
--- a/tests/playwright-test/to-have-screenshot.spec.ts
+++ b/tests/playwright-test/to-have-screenshot.spec.ts
@@ -688,6 +688,59 @@ test('should update webp snapshot with the update-snapshots flag', async ({ runI
expect([...image.data.subarray(0, 4)]).toEqual([255, 255, 255, 255]);
});
+test('should use configured webp type', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ snapshotPathTemplate: '__screenshots__/{testFilePath}/{arg}{ext}',
+ expect: {
+ toHaveScreenshot: {
+ type: 'webp',
+ },
+ },
+ }),
+ '__screenshots__/a.spec.js/is-a-test-1.webp': createWebpImage(IMG_WIDTH, IMG_HEIGHT, 255, 255, 255),
+ '__screenshots__/a.spec.js/snapshot.png': whiteImage,
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ expect(test.info().snapshotPath({ kind: 'screenshot' })).toMatch(/is-a-test-1\\.webp$/);
+ // Anonymous and explicit .png name both match existing snapshots.
+ await expect(page).toHaveScreenshot();
+ await expect(page).toHaveScreenshot('snapshot.png');
+ // Anonymous locator snapshot is written as webp.
+ await expect(page.locator('body')).toHaveScreenshot();
+ });
+ `
+ });
+ expect(result.exitCode).toBe(1);
+ for (const name of ['is-a-test-1.webp', 'snapshot.png'])
+ expect(result.output).not.toContain(`A snapshot doesn't exist at ${testInfo.outputPath('__screenshots__', 'a.spec.js', name)}`);
+ const snapshotOutputPath = testInfo.outputPath('__screenshots__', 'a.spec.js', 'is-a-test-2.webp');
+ expect(result.output).toContain(`A snapshot doesn't exist at ${snapshotOutputPath}, writing actual`);
+ expect(utils.decodeWebp(fs.readFileSync(snapshotOutputPath)).width).toBeGreaterThan(0);
+ expect(fs.existsSync(testInfo.outputPath('test-results', 'a-is-a-test', 'is-a-test-2-actual.webp'))).toBe(true);
+});
+
+test('should fail on unsupported configured type', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ expect: {
+ toHaveScreenshot: {
+ type: 'jpeg',
+ },
+ },
+ }),
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ await expect(page).toHaveScreenshot();
+ });
+ `
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.output).toContain(`config.expect.toHaveScreenshot.type must be one of "png" or "webp"`);
+});
+
test('should fail when given buffer', async ({ runInlineTest }) => {
const result = await runInlineTest({
...playwrightConfig({}),