Use page.screenshot() for a viewport or full-page image, and locator.screenshot() for a single element. Set a path to save the file; omit it when you want the returned image buffer. For a repeatable capture, establish the page state and viewport first, then control animations and mask only the content that is expected to vary.
Capture a page in Playwright
The basic sequence is to navigate, then call the Page API’s screenshot() method. This JavaScript example saves the visible viewport to a PNG file:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();
})();Playwright’s documented example uses WebKit; Chromium, Firefox, and WebKit are available browser choices. Choose the engine that matches your test or capture needs rather than assuming the output will be identical across engines. The Page API reference documents screenshot behavior and options.
With path, Playwright writes the image to disk. Without path, the method returns a buffer that you can pass to other code, upload, or process:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches#1 Best Overall
const imageBuffer = await page.screenshot();Use await so the capture finishes before the script exits or closes the browser. The examples below assume an initialized page and use the same page.screenshot() method unless noted.
Choose what to capture
The default is the visible viewport. Choose full-page, a rectangle, or an element when you need a different scope.
Visible viewport
await page.screenshot({ path: 'viewport.png' });fullPage defaults to false, so this captures the currently visible browser area, not the entire scrollable document.
Full scrollable page
await page.screenshot({ path: 'full-page.png', fullPage: true });The Page API describes fullPage: true as taking a screenshot of “the full scrollable page, instead of the currently visible viewport.” A tall page can produce a large image; use a viewport capture or a selected element if you only need a portion.
Recommended Free Tools
Rectangular clip
Pass a rectangle in page coordinates with x, y, width, and height:
await page.screenshot({
path: 'region.png',
clip: { x: 0, y: 120, width: 800, height: 500 }
});Use a clip when you need a defined region rather than a locator-based element. Ensure the rectangle has positive dimensions and covers the area you intend to capture.
One element
For current element-based usage, take a locator screenshot:
await page.locator('.header').screenshot({ path: 'header.png' });Playwright performs actionability checks and scrolls the element into view before capture. If an overlay covers it, the overlay can obscure it in the image. A scrollable container contributes only the content currently scrolled into view; an element screenshot does not mean that every internal scroll position is captured. The Locator API reference describes locator screenshots.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Choose image format and pixel scale
PNG is the default. Choose another format or scale to suit the output destination, transparency needs, and image size.
- PNG: the default, with no screenshot
qualitysetting applied. - JPEG: useful when a smaller lossy image is acceptable. The documented default quality is 80.
- WebP: supports the
qualityoption; quality 100 is lossless, while lower values are lossy.
Set the output format and quality explicitly when relevant:
await page.screenshot({
path: 'page.webp',
type: 'webp',
quality: 85
});quality applies to JPEG and WebP, not PNG. For transparency, omitBackground: true removes the default background, but this option does not apply to JPEG:
await page.screenshot({ path: 'transparent.png', omitBackground: true });Pixel scale changes output dimensions. Use scale: 'css' for one output pixel per CSS pixel, which keeps high-DPI captures smaller. Use scale: 'device' for device-pixel output; on a high-DPI display, that can make the image twice as large or larger:
Free tools Windows power users keep installed
One-click scans. No signup required.
await page.screenshot({ path: 'css-scale.png', scale: 'css' });Check downstream requirements before choosing: a visual test may expect device-pixel output, while a compact artifact may be better at CSS scale.
Make captures more repeatable
A screenshot is only as stable as the browser state that produces it. Fix the viewport, page data, navigation state, and other relevant inputs before capture. Network-loaded content, fonts, application state, browser engine, viewport, and test data can all affect the result; screenshot options do not make an unpredictable page deterministic.
Disable or normalize animation
Use animations: 'disabled' to avoid capturing an animation mid-frame. Playwright fast-forwards finite animations to completion, firing transitionend, and cancels infinite animations to their initial state for the screenshot; animations then resume.
await page.screenshot({
path: 'stable.png',
animations: 'disabled'
});Hide the caret and mask variable regions
caret: 'hide' is the default. To cover dynamic or sensitive content, pass locators in mask. The mask covers each matched element’s bounding box and also applies to invisible matched elements. Set maskColor to choose the overlay color:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →await page.screenshot({
path: 'masked.png',
mask: [page.locator('.timestamp'), page.locator('.account-name')],
maskColor: '#808080'
});Mask only regions whose variation should not count as a visual change. Masking a region that matters to the test can hide a real regression.
Apply screenshot-only styles
The style option applies a stylesheet during capture. It can adjust or hide dynamic content; its documented behavior pierces Shadow DOM and applies to inner frames as well:
await page.screenshot({
path: 'without-banners.png',
style: '.volatile-banner { visibility: hidden !important; }'
});Use styles narrowly. Hiding an element is appropriate only when that element is outside the behavior you intend to verify.
Capture files automatically or assert against an expected image
Playwright Test offers two related but different mechanisms: automatic screenshots attached to test runs and visual assertions that compare a capture to an expected snapshot.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteConfigure automatic screenshots
In Playwright Test, the use.screenshot setting defaults to 'off'. It accepts 'on', 'only-on-failure', and 'on-first-failure', as well as options such as fullPage and omitBackground. For example, a configuration can enable captures only when tests fail:
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
use: {
screenshot: 'only-on-failure'
}
});See the TestOptions screenshot reference for the configuration shape and supported settings.
Use a visual assertion for comparison
page.screenshot() creates an image. await expect(page).toHaveScreenshot() compares the page with an expected snapshot and is available with the Playwright test runner:
const { test, expect } = require('@playwright/test');
test('home page visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('home.png');
});The assertion waits until two consecutive screenshots produce the same result, then compares the last image with the expected snapshot. A locator equivalent is available for element-level comparisons. Set thresholds such as maxDiffPixels or maxDiffPixelRatio deliberately: overly broad tolerances can allow meaningful visual changes to pass. The visual comparisons guide covers screenshot assertions.
Check option availability in your installed Playwright version
Options have version histories, so confirm that the installed release supports the one you plan to use. The current official reference labels maskColor as added in v1.35, screenshot style in v1.41, TestOptions reducedMotion in v1.50, and screenshot signal in v1.62. These are documented introduction versions, not a claim that every project is using that release. Check the reference for the version installed in your project before depending on a version-specific option.
ElementHandle.screenshot() is marked discouraged in the API reference, which recommends Locator.screenshot() instead. Prefer a locator for new element-based capture code.
Troubleshoot common capture problems
- The image shows only the top of the page. The default is a viewport screenshot. Add
fullPage: trueif you need the full scrollable page. - The target element is missing or obscured. A locator screenshot scrolls the element into view, but a covering overlay can still hide it. Inspect the page state and handle the overlay or capture a different scope.
- An element screenshot omits content inside a scroll area. Only the container’s currently scrolled content contributes. Scroll the container to the required position before taking the screenshot, or capture separate states if several positions matter.
- The PNG is unexpectedly large or output dimensions differ. Review the viewport and
scale. Device-pixel scale can create larger images on high-DPI displays; CSS scale uses one image pixel per CSS pixel. - A transparent background was not produced. Use
omitBackground: truewith a format that supports transparency, such as PNG; it does not apply to JPEG. - A visual assertion changes between runs. Fix page state, viewport, test data, and relevant loaded content. Disable animation, then mask or style only expected variability. Do not widen assertion tolerances without considering which changes they could conceal.
- An option is rejected or unavailable. Check the Playwright version installed by the project and confirm the option’s availability in that release’s API reference.
- The script exits before the image is ready. Await the screenshot call before closing the browser or ending the test.
Or skip the browser setup
If you need an image from a URL without managing a Playwright browser, ScreenshotNeo provides a screenshot API and MCP server. Its one-call GET endpoint can return PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or consent banners as a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots per month with no card required. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free, and every feature is on every plan.
Sign up free for 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I use `page.screenshot()` without saving a file?
Yes. Omit `path`; the method returns a buffer you can process or send elsewhere.
Can Playwright take screenshots of a specific element?
Yes. Use `locator.screenshot()` for a locator-based capture; it scrolls the element into view and performs actionability checks.
Does `toHaveScreenshot()` work outside Playwright Test?
No. Playwright’s screenshot assertions are available with its test runner.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
