Skip to content

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

fix(screenshot): fix webp transparency and lossless detection, add tests (#41781)

Yury Semikhatskye71a5bf6022b
diff --git a/packages/playwright-core/src/server/screenshotter.ts b/packages/playwright-core/src/server/screenshotter.ts
index 1248dd3c99..d96c32c5fb 100644
--- a/packages/playwright-core/src/server/screenshotter.ts
+++ b/packages/playwright-core/src/server/screenshotter.ts
@@ -292,7 +292,8 @@ export class Screenshotter {
if ((options as any).__testHookBeforeScreenshot)
await progress.race((options as any).__testHookBeforeScreenshot());
- const shouldSetDefaultBackground = options.omitBackground && format === 'png';
+ // jpeg does not support transparency.
+ const shouldSetDefaultBackground = options.omitBackground && format !== 'jpeg';
if (shouldSetDefaultBackground)
await progress.race(this._page.delegate.setBackgroundColor({ r: 0, g: 0, b: 0, a: 0 }));
const cleanupHighlight = await this._maskElements(progress, options);
diff --git a/packages/playwright/src/matchers/toMatchSnapshot.ts b/packages/playwright/src/matchers/toMatchSnapshot.ts
index 683a6a7b35..2b7a088c95 100644
--- a/packages/playwright/src/matchers/toMatchSnapshot.ts
+++ b/packages/playwright/src/matchers/toMatchSnapshot.ts
@@ -460,6 +460,9 @@ function determineFileExtension(file: string | Buffer): string {
return 'png';
if (compareMagicBytes(file, [0xff, 0xd8, 0xff]))
return 'jpg';
+ // A WebP bitstream is a RIFF container tagged 'WEBP': "RIFF????WEBP".
+ if (file.length >= 12 && file.toString('ascii', 0, 4) === 'RIFF' && file.toString('ascii', 8, 12) === 'WEBP')
+ return 'webp';
return 'dat';
}
diff --git a/packages/utils/webp/webp.ts b/packages/utils/webp/webp.ts
index e308bd3a07..b69ad6548c 100644
--- a/packages/utils/webp/webp.ts
+++ b/packages/utils/webp/webp.ts
@@ -99,8 +99,9 @@ export function decodeWebp(buffer: Buffer): WebpImage {
// Whether a WebP bitstream is lossless, determined by parsing the RIFF header.
// The frame is 'VP8L' (lossless) or 'VP8 ' (lossy); the 'VP8X' extended format
-// wraps one of those, so scan its chunks. (The lossy quality factor is an
-// encoder input and is not stored in the bitstream, so it cannot be recovered.)
+// wraps one of those along with metadata chunks like 'ICCP' or 'EXIF', so skip
+// chunks until a frame is found. (The lossy quality factor is an encoder input
+// and is not stored in the bitstream, so it cannot be recovered.)
export function isLosslessWebp(buffer: Buffer): boolean {
if (buffer.length < 16 || buffer.toString('ascii', 0, 4) !== 'RIFF' || buffer.toString('ascii', 8, 12) !== 'WEBP')
return false;
@@ -111,10 +112,7 @@ export function isLosslessWebp(buffer: Buffer): boolean {
return true;
if (fourcc === 'VP8 ')
return false;
- // Skip this chunk (8-byte header + payload, padded to an even size) and
- // keep scanning — only 'VP8X' is expected to lead here.
- if (fourcc !== 'VP8X')
- return false;
+ // Skip this chunk (8-byte header + payload, padded to an even size).
const size = buffer.readUInt32LE(offset + 4);
offset += 8 + size + (size & 1);
}
diff --git a/tests/page/elementhandle-screenshot.spec.ts b/tests/page/elementhandle-screenshot.spec.ts
index 3d5d7c5709..a5b206e98c 100644
--- a/tests/page/elementhandle-screenshot.spec.ts
+++ b/tests/page/elementhandle-screenshot.spec.ts
@@ -17,6 +17,8 @@
import { test as it, expect, rafraf } from './pageTest';
import { verifyViewport } from '../config/utils';
+import { PNG } from '../../packages/playwright-core/lib/utilsBundle';
+import { utils } from '../../packages/playwright-core/lib/coreBundle';
import path from 'path';
import fs from 'fs';
@@ -33,6 +35,20 @@ it.describe('element screenshot', () => {
expect(screenshot).toMatchSnapshot('screenshot-element-bounding-box.png');
});
+ it('should work with webp', async ({ page, server, isBidi }) => {
+ it.skip(isBidi, 'webp screenshots are not supported via WebDriver BiDi');
+
+ await page.setViewportSize({ width: 500, height: 500 });
+ await page.goto(server.PREFIX + '/grid.html');
+ const elementHandle = await page.$('.box:nth-of-type(3)');
+ const webpImage = utils.decodeWebp(await elementHandle.screenshot({ type: 'webp' }));
+ // The default webp screenshot is lossless, so it must decode to the exact same pixels as png.
+ const pngImage = PNG.sync.read(await elementHandle.screenshot({ type: 'png' }));
+ expect(webpImage.width).toBe(pngImage.width);
+ expect(webpImage.height).toBe(pngImage.height);
+ expect(webpImage.data.equals(pngImage.data)).toBe(true);
+ });
+
it('should work when main world busts JSON.stringify', async ({ page, server }) => {
await page.setViewportSize({ width: 500, height: 500 });
await page.goto(server.PREFIX + '/grid.html');
diff --git a/tests/page/page-screenshot.spec.ts b/tests/page/page-screenshot.spec.ts
index 4619b5ece1..1810515829 100644
--- a/tests/page/page-screenshot.spec.ts
+++ b/tests/page/page-screenshot.spec.ts
@@ -22,6 +22,7 @@ import type { Route } from 'playwright-core';
import path from 'path';
import fs from 'fs';
import { comparePNGs } from '../config/comparator';
+import { utils } from '../../packages/playwright-core/lib/coreBundle';
it.describe('page screenshot', () => {
it.skip(({ browserName, headless }) => browserName === 'firefox' && !headless, 'Firefox headed produces a different image.');
@@ -288,6 +289,64 @@ it.describe('page screenshot', () => {
expect(screenshot).toMatchSnapshot('red.webp');
});
+ it('path option should detect webp', async ({ page, server, isBidi }, testInfo) => {
+ it.skip(isBidi, 'webp screenshots are not supported via WebDriver BiDi');
+
+ await page.setViewportSize({ width: 300, height: 300 });
+ await page.goto(server.EMPTY_PAGE);
+ await page.evaluate(() => (document.body.style.background = 'rgb(255, 0, 0)'));
+ const outputPath = testInfo.outputPath('screenshot.webp');
+ const screenshot = await page.screenshot({ path: outputPath });
+ expect(await fs.promises.readFile(outputPath)).toMatchSnapshot('red.webp');
+ expect(screenshot).toMatchSnapshot('red.webp');
+ });
+
+ it('quality option should work for webp', async ({ page, server, isBidi }) => {
+ it.skip(isBidi, 'webp screenshots are not supported via WebDriver BiDi');
+
+ await page.goto(server.PREFIX + '/grid.html');
+ const lowQuality = await page.screenshot({ type: 'webp', quality: 0 });
+ const highQuality = await page.screenshot({ type: 'webp', quality: 100 });
+ expect(lowQuality.byteLength).toBeLessThan(highQuality.byteLength);
+ });
+
+ it('webp screenshots should be lossless by default', async ({ page, server, isBidi }) => {
+ it.skip(isBidi, 'webp screenshots are not supported via WebDriver BiDi');
+
+ await page.goto(server.PREFIX + '/grid.html');
+ expect(utils.isLosslessWebp(await page.screenshot({ type: 'webp' }))).toBe(true);
+ expect(utils.isLosslessWebp(await page.screenshot({ type: 'webp', quality: 80 }))).toBe(false);
+ });
+
+ it('should allow transparency with webp', async ({ page, browserName, isBidi }) => {
+ it.skip(isBidi, 'webp screenshots are not supported via WebDriver BiDi');
+ it.fail(browserName === 'firefox');
+
+ await page.setViewportSize({ width: 300, height: 300 });
+ await page.setContent(`
+ <style>
+ body { margin: 0 }
+ div { width: 300px; height: 100px; }
+ </style>
+ <div style="background:black"></div>
+ <div style="background:white"></div>
+ <div style="background:transparent"></div>
+ `);
+ const screenshot = await page.screenshot({ omitBackground: true, type: 'webp' });
+ const { width, height, data } = utils.decodeWebp(screenshot);
+ expect(width).toBe(300);
+ expect(height).toBe(300);
+ const pixel = (x: number, y: number) => [...data.subarray((y * width + x) * 4, (y * width + x) * 4 + 4)];
+ expect(pixel(150, 50)).toEqual([0, 0, 0, 255]);
+ expect(pixel(150, 150)).toEqual([255, 255, 255, 255]);
+ expect(pixel(150, 250)[3]).toBe(0);
+ });
+
+ it('quality option should throw for webp when out of range', async ({ page }) => {
+ const error = await page.screenshot({ type: 'webp', quality: 101 }).catch(e => e);
+ expect(error.message).toContain('Expected options.quality to be between 0 and 100');
+ });
+
it('should work with odd clip size on Retina displays', async ({ page, isElectron }) => {
it.skip(isElectron, 'electron does not set device scale factor to 1');
diff --git a/tests/playwright-test/golden.spec.ts b/tests/playwright-test/golden.spec.ts
index 29444d6384..e234b95ffb 100644
--- a/tests/playwright-test/golden.spec.ts
+++ b/tests/playwright-test/golden.spec.ts
@@ -17,7 +17,7 @@
import colors from 'colors/safe';
import * as fs from 'fs';
import * as path from 'path';
-import { test, expect, createWhiteImage, paintBlackPixels } from './playwright-test-fixtures';
+import { test, expect, createWebpImage, createWhiteImage, paintBlackPixels } from './playwright-test-fixtures';
const files = {
'helper.ts': `
@@ -700,6 +700,59 @@ test('should compare different PNG images', async ({ runInlineTest }, testInfo)
expect(fs.existsSync(diffSnapshotArtifactPath)).toBe(true);
});
+test('should compare WEBP images', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ ...files,
+ 'a.spec.js-snapshots/snapshot.webp': createWebpImage(1, 1, 255, 255, 255),
+ 'a.spec.js': `
+ const { test, expect } = require('./helper');
+ test('is a test', async ({ page }) => {
+ expect(await page.screenshot({ type: 'webp', clip: { x: 0, y: 0, width: 1, height: 1 } })).toMatchSnapshot('snapshot.webp');
+ });
+ `
+ });
+ expect(result.exitCode).toBe(0);
+});
+
+test('should compare different WEBP images', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...files,
+ 'a.spec.js-snapshots/snapshot.webp': createWebpImage(1, 1, 255, 0, 0),
+ 'a.spec.js': `
+ const { test, expect } = require('./helper');
+ test('is a test', ({}) => {
+ expect(Buffer.from([${createWebpImage(1, 1, 0, 0, 255).join(',')}])).toMatchSnapshot('snapshot.webp');
+ });
+ `
+ });
+
+ const outputText = result.output;
+ expect(result.exitCode).toBe(1);
+ expect(outputText).toContain('Error: expect(Buffer).toMatchSnapshot(expected)');
+ expect(outputText).toContain('1 pixels (ratio 1.00 of all image pixels) are different.');
+ const expectedSnapshotArtifactPath = testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-expected.webp');
+ const actualSnapshotArtifactPath = testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-actual.webp');
+ const diffSnapshotArtifactPath = testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-diff.webp');
+ expect(fs.existsSync(expectedSnapshotArtifactPath)).toBe(true);
+ expect(fs.existsSync(actualSnapshotArtifactPath)).toBe(true);
+ expect(fs.existsSync(diffSnapshotArtifactPath)).toBe(true);
+});
+
+test('should use webp extension for anonymous webp snapshots', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...files,
+ 'a.spec.js': `
+ const { test, expect } = require('./helper');
+ test('is a test', async ({ page }) => {
+ expect(await page.screenshot({ type: 'webp' })).toMatchSnapshot();
+ });
+ `
+ });
+ expect(result.exitCode).toBe(1);
+ expect(fs.existsSync(testInfo.outputPath('test-results', 'a-is-a-test', 'is-a-test-1-actual.webp'))).toBe(true);
+ expect(fs.existsSync(testInfo.outputPath('a.spec.js-snapshots', 'is-a-test-1.webp'))).toBe(true);
+});
+
test('should correctly handle different JPEG image signatures', async ({ runInlineTest }, testInfo) => {
const result = await runInlineTest({
...files,
diff --git a/tests/playwright-test/playwright-test-fixtures.ts b/tests/playwright-test/playwright-test-fixtures.ts
index dba9934c2b..28ef919e29 100644
--- a/tests/playwright-test/playwright-test-fixtures.ts
+++ b/tests/playwright-test/playwright-test-fixtures.ts
@@ -20,6 +20,7 @@ import * as os from 'os';
import * as path from 'path';
import { execSync } from 'node:child_process';
import { PNG } from 'playwright-core/lib/utilsBundle';
+import { utils } from '../../packages/playwright-core/lib/coreBundle';
import type { CommonFixtures, CommonWorkerFixtures, TestChildProcess } from '../config/commonFixtures';
import { commonFixtures } from '../config/commonFixtures';
import type { ServerFixtures, ServerWorkerOptions } from '../config/serverFixtures';
@@ -392,6 +393,11 @@ export function createWhiteImage(width: number, height: number) {
return createImage(width, height, 255, 255, 255);
}
+export function createWebpImage(width: number, height: number, r: number = 0, g: number = 0, b: number = 0): Buffer {
+ const png = PNG.sync.read(createImage(width, height, r, g, b));
+ return utils.encodeWebp({ width: png.width, height: png.height, data: png.data }, { lossless: true });
+}
+
export function paintBlackPixels(image: Buffer, blackPixelsCount: number): Buffer {
const png = PNG.sync.read(image);
for (let i = 0; i < blackPixelsCount; ++i) {
diff --git a/tests/playwright-test/to-have-screenshot.spec.ts b/tests/playwright-test/to-have-screenshot.spec.ts
index 26ba659bde..79f33f5182 100644
--- a/tests/playwright-test/to-have-screenshot.spec.ts
+++ b/tests/playwright-test/to-have-screenshot.spec.ts
@@ -18,7 +18,8 @@ import * as fs from 'fs';
import { PNG } from 'playwright-core/lib/utilsBundle';
import * as path from 'path';
import { pathToFileURL } from 'url';
-import { test, expect, createImage, paintBlackPixels } from './playwright-test-fixtures';
+import { test, expect, createImage, createWebpImage, paintBlackPixels } from './playwright-test-fixtures';
+import { utils } from '../../packages/playwright-core/lib/coreBundle';
import { comparePNGs } from '../config/comparator';
test.describe.configure({ mode: 'parallel' });
@@ -570,6 +571,86 @@ test('should fail when given unsupported snapshot name', async ({ runInlineTest
expect(result.output).toContain(`Screenshot name "snapshot.jpeg" must have a '.png' or '.webp' extension`);
});
+test('should pass when webp screenshot matches expectation', async ({ runInlineTest }) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ snapshotPathTemplate: '__screenshots__/{testFilePath}/{arg}{ext}',
+ }),
+ '__screenshots__/a.spec.js/snapshot.webp': createWebpImage(IMG_WIDTH, IMG_HEIGHT, 255, 255, 255),
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ await expect(page).toHaveScreenshot('snapshot.webp');
+ });
+ `
+ });
+ expect(result.exitCode).toBe(0);
+});
+
+test('should write missing webp expectation', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ snapshotPathTemplate: '__screenshots__/{testFilePath}/{arg}{ext}',
+ }),
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ await expect(page).toHaveScreenshot('snapshot.webp');
+ });
+ `
+ });
+ expect(result.exitCode).toBe(1);
+ const snapshotOutputPath = testInfo.outputPath('__screenshots__', 'a.spec.js', 'snapshot.webp');
+ expect(result.output).toContain(`A snapshot doesn't exist at ${snapshotOutputPath}, writing actual`);
+ const image = utils.decodeWebp(fs.readFileSync(snapshotOutputPath));
+ expect(image.width).toBe(IMG_WIDTH);
+ expect(image.height).toBe(IMG_HEIGHT);
+});
+
+test('should fail when webp screenshot is different pixels', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ snapshotPathTemplate: '__screenshots__/{testFilePath}/{arg}{ext}',
+ }),
+ '__screenshots__/a.spec.js/snapshot.webp': createWebpImage(IMG_WIDTH, IMG_HEIGHT, 255, 0, 0),
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ await expect(page).toHaveScreenshot('snapshot.webp', { timeout: 2000 });
+ });
+ `
+ });
+ expect(result.exitCode).toBe(1);
+ expect(result.output).toContain('Error: expect(page).toHaveScreenshot(expected)');
+ expect(result.output).toContain('are different');
+ expect(fs.existsSync(testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-actual.webp'))).toBe(true);
+ expect(fs.existsSync(testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-expected.webp'))).toBe(true);
+ expect(fs.existsSync(testInfo.outputPath('test-results', 'a-is-a-test', 'snapshot-diff.webp'))).toBe(true);
+});
+
+test('should update webp snapshot with the update-snapshots flag', async ({ runInlineTest }, testInfo) => {
+ const result = await runInlineTest({
+ ...playwrightConfig({
+ snapshotPathTemplate: '__screenshots__/{testFilePath}/{arg}{ext}',
+ }),
+ '__screenshots__/a.spec.js/snapshot.webp': createWebpImage(IMG_WIDTH, IMG_HEIGHT, 255, 0, 0),
+ 'a.spec.js': `
+ const { test, expect } = require('@playwright/test');
+ test('is a test', async ({ page }) => {
+ await expect(page).toHaveScreenshot('snapshot.webp');
+ });
+ `
+ }, { 'update-snapshots': true });
+ expect(result.exitCode).toBe(0);
+ const snapshotOutputPath = testInfo.outputPath('__screenshots__', 'a.spec.js', 'snapshot.webp');
+ expect(result.output).toContain(`${snapshotOutputPath} is re-generated, writing actual.`);
+ const image = utils.decodeWebp(fs.readFileSync(snapshotOutputPath));
+ expect(image.width).toBe(IMG_WIDTH);
+ expect(image.height).toBe(IMG_HEIGHT);
+ // The red expectation should have been replaced with the actual white page.
+ expect([...image.data.subarray(0, 4)]).toEqual([255, 255, 255, 255]);
+});
+
test('should fail when given buffer', async ({ runInlineTest }) => {
const result = await runInlineTest({
...playwrightConfig({}),