How to Take a WebP Screenshot with Playwright
Save Playwright screenshots as WebP with a filename or explicit type. Learn quality, full-page and element capture, visual tests, and troubleshooting.
To save a WebP screenshot with Playwright, give page.screenshot() a path ending in .webp. Playwright infers the image format from the extension:
await page.screenshot({ path: 'screenshot.webp' });You can also set type: 'webp' explicitly. Use a .webp filename so the extension matches the file contents. See the Playwright Page API for the documented options.
1. Set up a runnable Playwright example
This JavaScript example opens a page and writes a WebP screenshot. It uses Playwright’s library API rather than the test runner.
import { chromium } from 'playwright';
const browser = await chromium.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'load' });
await page.screenshot({ path: 'example.webp' });
} finally {
await browser.close();
}Install Playwright and its browser using the official installation instructions. Run the script in an environment where the selected browser is installed. For a shorter capture-only snippet, once you have a page ready:
await page.screenshot({ path: 'screenshot.webp' });The filename extension is sufficient to request WebP. The explicit form is useful when you want the format choice visible in the options:
await page.screenshot({ path: 'screenshot.webp', type: 'webp' });2. Choose the capture scope
Viewport screenshot
The basic call captures the page’s current viewport. Set the viewport before navigation or capture if output dimensions matter:
await page.setViewportSize({ width: 1440, height: 900 });
await page.screenshot({ path: 'viewport.webp' });Full scrollable page
Pass fullPage: true to capture the full scrollable page rather than only the visible viewport:
await page.screenshot({
path: 'full-page.webp',
fullPage: true
});For pages with content that appears only as you scroll, make sure that content has loaded before capturing. Full-page capture can produce large images and take longer than a viewport capture.
A single element
Use a locator’s screenshot method to capture one element. The filename can infer WebP here as well:
const card = page.locator('.product-card').first();
await card.waitFor({ state: 'visible' });
await card.screenshot({ path: 'product-card.webp' });Choose a selector that identifies the intended element. If it matches multiple elements, use an index or a more specific selector.
3. Set WebP quality and output scale
Playwright documents WebP quality on a 0–100 scale. The default is 100, which produces lossless output; lower values use lossy compression. A lower setting may reduce file size, but the reduction depends on the image, so inspect the result for your use case.
await page.screenshot({
path: 'homepage.webp',
quality: 70
});Use scale: 'css' to make the output one pixel per CSS pixel, or scale: 'device' to use device pixels. The latter can create a higher-resolution image on a high-DPI device and may increase its dimensions and file size.
await page.screenshot({
path: 'homepage.webp',
type: 'webp',
quality: 85,
scale: 'css'
});Other useful screenshot options include:
fullPage: capture the complete scrollable page.omitBackground: omit the default white background where supported. This is not applicable to JPEG.animations: control how animations are handled during capture.clip: capture a specified rectangular area.timeout: set the screenshot operation timeout.
Check the Page screenshot API reference for exact option types and behavior in your installed version.
4. Use WebP in Playwright Test visual comparisons
For a visual regression baseline managed by Playwright Test, use toHaveScreenshot() with a WebP filename:
import { test, expect } from '@playwright/test';
test('landing page visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('landing.webp');
});This is different from writing a standalone screenshot file with page.screenshot(): the assertion belongs to the test runner and compares against an expected snapshot. Playwright waits for consecutive screenshots to stabilize before comparing. Keep baseline creation and comparison environments consistent, because browser rendering can vary with the host operating system, browser version, settings, hardware, power source, and headless mode. See the visual comparisons documentation.
5. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Send one GET request with a URL to receive an image, including WebP, or a PDF. Its options include full-page and element capture, viewport and device settings, quality-related image controls, custom CSS and JavaScript, wait conditions, and more. See the ScreenshotNeo API documentation for the request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-d format=webp \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={
"access_key": "YOUR_API_KEY",
"url": "https://stripe.com",
"format": "webp",
},
timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
f.write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com',
format: 'webp'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(async fs =>
fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
);ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month with no card.
6. Troubleshooting WebP screenshots
| Problem | Likely cause | What to do |
|---|---|---|
| Screenshot is PNG instead of WebP | The output path ends in .png, or the installed version does not support the requested format. |
Use a .webp path and, if desired, set type: 'webp'. Check the installed binding’s documentation and release notes if WebP is rejected. |
| Type or quality option is rejected | The installed Playwright version or language binding may not support WebP capture. | Check the version and that binding’s API documentation. The Playwright 1.62 release notes announce WebP support for page and locator screenshots; they do not provide a complete compatibility matrix for all older versions, bindings, and browsers. See the 1.62 release notes. |
| Image is larger than expected | Quality is high, the page is large, or device-pixel scale produces more pixels. | Try a lower quality value, compare scale: 'css' with scale: 'device', or capture only the needed element. Review image quality and dimensions after changing settings. |
| Some content is missing | The page or lazy-loaded content was not ready at capture time, or the screenshot covers only the viewport. | Wait for the relevant content or selector, scroll where needed to trigger lazy loading, and use fullPage: true for the full scrollable page. |
| Visual snapshot differs across machines | Rendering can change across operating systems, browser versions, settings, hardware, power sources, and headless modes. | Generate and compare snapshots in a consistent environment, including the same browser version and settings. |
7. Performance, reliability, and format choices
Capture only the area you need: viewport or element screenshots generally involve less output than a full-page capture. Large pages and device-pixel output can increase image dimensions and the time and storage needed to handle the result. Lower WebP quality can help reduce output size, but measure it against your own page and visual requirements.
For repeatable visual tests, use stable page state and a consistent browser environment. Wait for important elements and data rather than relying on an arbitrary short delay. WebP is suitable when your downstream system accepts it; if a consumer requires PNG or JPEG, select that format instead. Playwright documents PNG, JPEG, and WebP screenshot types.
8. FAQ
Can Playwright save a screenshot directly as WebP?
Yes. Use a .webp path, or specify type: 'webp' in a version and binding that supports WebP screenshots.
What is the default WebP quality?
The documented default is 100, which produces lossless output. Lower values use lossy compression.
How do I capture the whole page as WebP?
Combine a WebP path with fullPage: true, for example await page.screenshot({ path: 'full.webp', fullPage: true }).
Should I use page.screenshot() or toHaveScreenshot()?
Use page.screenshot() to write an image file. Use toHaveScreenshot() in Playwright Test when the goal is a visual snapshot assertion.
