Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Playwright can capture the current browser viewport, an entire scrollable page, a clipped rectangle, or one element. The reliable workflow is to control the page state first, choose the capture scope and image format deliberately, then use Playwright Test’s screenshot assertions when the goal is visual regression rather than a one-off image.
How do I take a screenshot with Playwright?
Install Playwright, launch a browser, open a page, save the image, and close the browser. This Node.js example captures the visible viewport:
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();
})();page.screenshot() captures the current viewport unless you add options. Wait for the content that matters to your image before calling it; navigation completing does not guarantee that every image, font, or client-rendered component is visually ready.
Choose the capture area
Viewport screenshot
Use the default call when you need exactly what a user can see at the current viewport size:
#1 Best Overall
await page.screenshot({ path: 'viewport.png' });Full-page screenshot
Set fullPage: true to capture the page’s full scrollable extent rather than only the visible viewport:
await page.screenshot({
path: 'full.png',
fullPage: true
});Full-page capture changes the image’s height; it does not turn an element screenshot into a full-page capture.
Rectangular clip
Supply a clip rectangle when you need a fixed region. The coordinates and dimensions are in CSS pixels:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
await page.screenshot({
path: 'region.png',
clip: { x: 40, y: 120, width: 800, height: 500 }
});Element screenshot
Use a locator when the target is a card, form, button, or other component. Playwright waits for actionability, scrolls the element into view, and captures its bounds:
await page.getByRole('form', { name: 'Sign in' }).screenshot({
path: 'sign-in-form.png',
animations: 'disabled'
});A locator screenshot is not a way to reveal all content inside a scrollable container: it captures the portion currently visible after the element is brought into view. If another element covers part of the target, the covered pixels are not visible.
Pick PNG, JPEG, or WebP
| Format or option | Use it when | Important behavior |
|---|---|---|
| PNG | You need lossless output, crisp text, or transparency. | quality does not affect PNG. |
| JPEG | You need a smaller photographic image and do not need transparency. | quality controls compression. |
| WebP | You want modern compression with optional quality control. | quality: 100 is lossless according to the API reference. |
scale: 'css' |
Your downstream layout expects one image pixel per CSS pixel. | Output dimensions track CSS dimensions. |
scale: 'device' |
You need device-pixel detail for high-DPI output. | Images can be twice as large or larger; check the interface’s default before relying on it. |
The format can be inferred from the filename extension. JPEG cannot carry transparency. For a transparent PNG, use omitBackground: true.
Remove transient visual state
caret: 'hide'removes a blinking text caret.animations: 'disabled'suppresses animation during capture.maskcan cover dynamic locators.stylecan inject CSS that hides or normalizes unstable regions.
Disabling animation is a state change: finite animations are fast-forwarded, while infinite animations are canceled and then resumed. Do it for stable documentation or tests, but leave animation enabled when the animation state itself is what you are documenting.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchMake captures repeatable
A screenshot is determined by both the page state and the rendering environment. For repeatable output:
- Use the same browser version, operating system, viewport, device scale, headed/headless mode, and relevant settings for baselines and comparisons.
- Wait for the content you need, and control delayed network work or client-side rendering.
- Freeze or mask timestamps, rotating content, ads, cursors, and other dynamic regions.
- Choose whether images should reflect motion or a settled state before setting
animations: 'disabled'.
Different hardware, operating-system rendering, browser versions, power conditions, and headless modes can create legitimate pixel differences. Stabilize those variables before increasing visual-diff tolerances.
How do I compare screenshots in Playwright?
For visual regression, use Playwright Test’s toHaveScreenshot() assertion, not a standalone page.screenshot() call. The assertion waits for two consecutive identical captures, then compares the stable result with the stored expectation. The first run creates the baseline; later runs report differences.
import { test, expect } from '@playwright/test';
test('home page is visually stable', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('home.png');
});You can assert a page or a locator. Set tolerances only after the environment and dynamic content are controlled. The assertion API supports a perceived YIQ color-difference threshold and pixel-count allowances; values should reflect the changes your project accepts, not an arbitrary copied setting.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsFailure screenshots are different
Test options such as screenshot: 'on' and screenshot: 'only-on-failure' create artifacts at test completion. They help diagnose failures, and fullPage can be enabled for those artifacts, but they are not a replacement for an explicit toHaveScreenshot() visual assertion.
Common mistakes and fixes
Capturing the wrong extent
If you expected the whole document but got only the visible area, add fullPage: true. If you wanted one component, use a locator instead of full-page capture.
Assuming an element screenshot captures hidden scroll content
It does not. Scroll the container deliberately and capture each required state, or redesign the artifact so the content is visible at once.
Tuning thresholds before fixing rendering differences
First align browser, host, viewport, scale, fonts, animation, and dynamic data. Only then decide whether a remaining difference is acceptable and set a narrow tolerance.
Using a screenshot as a semantic test
Visual output can show layout and styling changes, but it does not prove that labels, roles, keyboard behavior, or other semantics are correct. Pair visual assertions with semantic and interaction tests.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API when you want a clean capture without managing Playwright locally. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also offers an MCP server for AI agents with take_screenshot, get_page_info, and capture_pdf.
One GET request returns an image or PDF. See the ScreenshotNeo API documentation for parameters and response details:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
