Playwright screenshot configuration depends on what you are producing. Use page.screenshot() for an explicitly saved image, use.screenshot for automatic test artifacts, locator.screenshot() for one element, and toHaveScreenshot() for visual regression checks. The right scope, format, scale, and stabilization options prevent oversized files and flaky comparisons.
Choose the Playwright screenshot API first
There is no single universal “screenshot config.” Select the API that matches the artifact you need:
| Goal | API/configuration | What it does |
|---|---|---|
| Save an image at a specific point in code | page.screenshot() |
Captures the current page viewport by default and returns a buffer or writes a file. |
| Collect images automatically from tests | use.screenshot in playwright.config.ts |
Controls test-runner artifacts; default mode is off. |
| Capture one component or region | locator.screenshot() |
Captures the bounding box of a locator-matched element. |
| Detect visual regressions | expect(page).toHaveScreenshot() or a locator assertion |
Compares rendered output with a baseline using mismatch thresholds. |
Keep explicit captures separate from automatic artifacts: a test-runner setting does not call page.screenshot() for you, and an explicit call does not change the runner’s failure-artifact policy.
Direct page screenshots with page.screenshot()
The Page API captures the visible viewport unless you change the scope. With no path, it returns an image buffer; with a path, it writes the file relative to the current working directory.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Minimal TypeScript example
import { chromium } from 'playwright';
const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
await page.goto('https://example.com', { waitUntil: 'networkidle' });
await page.screenshot({ path: 'artifacts/home.webp', type: 'webp' });
await browser.close();Viewport versus full page
fullPage: false (the default) captures what is currently visible. Set fullPage: true to capture the full scrollable page. A full-page shot can be very tall and may trigger lazy-loading behavior as Playwright scrolls through the document.
await page.screenshot({ path: 'artifacts/full.png', fullPage: true });Use clip when you need a fixed rectangle rather than the viewport or entire document:
await page.screenshot({
path: 'artifacts/hero.png',
clip: { x: 0, y: 0, width: 1200, height: 500 }
});Format, quality, and scale
- PNG is lossless; its quality setting is ignored.
- JPEG uses a documented default quality of 80. It cannot preserve transparency.
- WebP uses a documented default quality of 100 and is lossless by default.
- The
typeoption selects the format. Whenpathis supplied, the file extension can also determine the type. scale: 'device'is the Page screenshot default and produces one pixel per device pixel. On a high-DPI display this can make images and comparisons much larger.scale: 'css'produces one pixel per CSS pixel, usually making deterministic fixtures smaller.
await page.screenshot({
path: 'artifacts/card.jpg',
type: 'jpeg',
quality: 75,
scale: 'css'
});Background and transparency
omitBackground: true hides the default white page background, allowing transparency in PNG or WebP output. It does not apply to JPEG.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
await page.screenshot({ path: 'artifacts/logo.png', omitBackground: true });Stabilize dynamic pages
Animations, blinking carets, timestamps, ads, and personalized data can make otherwise identical captures differ. The screenshot options let you disable animations, hide the caret, mask locators, and inject a capture-only stylesheet.
Free tools Windows power users keep installed
One-click scans. No signup required.
await page.screenshot({
path: 'artifacts/stable.png',
animations: 'disabled',
caret: 'hide',
mask: [page.locator('[data-testid="user-name"]')],
style: `video, [data-live-clock] { visibility: hidden !important; }`
});When animations are disabled, finite animations are fast-forwarded and infinite animations are canceled to their initial state. A mask covers each target locator’s bounding box; the documented default mask color is pink (#FF00FF). Set a timeout when the page or a masked locator may take longer than the default.
Automatic screenshots in Playwright Test
Configure automatic artifacts in playwright.config.ts. The documented modes are off, on, only-on-failure, and on-first-failure; off is the default.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: 'only-on-failure'
}
});Which mode should you use?
off: fastest and least storage for routine runs where images are not needed.only-on-failure: a practical default for CI diagnosis; successful tests produce no screenshot.on-first-failure: captures the first failing retry rather than every retry, reducing duplicate artifacts.on: captures every test, useful for an audit trail but potentially expensive in storage and CI transfer time.
The object form accepts screenshot options such as fullPage and omitBackground:
export default defineConfig({
use: {
screenshot: {
mode: 'only-on-failure',
fullPage: true,
omitBackground: false
}
}
});Use this setting for runner-managed artifacts. For a screenshot at a precise point—after opening a menu, submitting a form, or waiting for a specific response—call page.screenshot() in the test itself.
Capture one element with a locator
locator.screenshot() is the recommended element API. It waits for the locator, scrolls it into view, and captures its bounding box. Prefer it over the older ElementHandle screenshot method.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
import { test } from '@playwright/test';
test('save the pricing card', async ({ page }) => {
await page.goto('https://example.com/pricing');
await page.getByRole('heading', { name: 'Pro' }).screenshot({
path: 'artifacts/pro-heading.png',
animations: 'disabled'
});
});Choose a stable role, label, or test ID. A locator that matches multiple elements or disappears during a transition can time out; narrow it with getByRole, getByTestId, or .nth() only when the order is intentional.
Visual regression assertions
Use an assertion when the goal is comparison, not merely saving an image. Playwright Test stores a baseline and fails when the new rendering exceeds the configured difference.
import { test, expect } from '@playwright/test';
test('homepage remains visually stable', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('homepage.png', {
fullPage: true,
animations: 'disabled',
caret: 'hide',
threshold: 0.2,
maxDiffPixels: 100
});
});A locator assertion targets a component:
await expect(page.getByTestId('checkout-summary')).toHaveScreenshot('summary.png');Comparison options include a color-difference threshold and acceptable different-pixel counts or ratios. Keep browser, operating-system, fonts, viewport, locale, timezone, and data consistent between baseline and test runs. Configure shared screenshot-expectation defaults at project or test level rather than repeating them in every assertion.
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 & 11Outdated 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 matchBest Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Configuration recipes by requirement
How do I save a full-page WebP?
await page.goto('https://example.com/docs', { waitUntil: 'networkidle' });
await page.screenshot({ path: 'docs.webp', fullPage: true, type: 'webp', scale: 'css' });How do I capture after a selector appears?
await page.goto('https://example.com/dashboard');
await page.locator('[data-testid="report"]').waitFor({ state: 'visible' });
await page.screenshot({ path: 'report.png', fullPage: true });How do I hide sensitive or changing content?
await page.screenshot({
path: 'safe.png',
mask: [page.locator('[data-private]'), page.locator('.live-price')],
animations: 'disabled',
caret: 'hide'
});How do I return bytes instead of writing a file?
const buffer = await page.screenshot({ type: 'png' });
await uploadToObjectStorage(buffer);Troubleshooting Playwright screenshot failures
- Image is only the visible area: add
fullPage: true; a locator screenshot is intentionally limited to that element. - File is unexpectedly huge: use
scale: 'css', JPEG/WebP, a clip rectangle, or an element capture. - Transparent output is white: use PNG or WebP with
omitBackground: true; JPEG cannot be transparent. - Visual assertion is flaky: disable animations, hide the caret, mask dynamic regions, wait for a meaningful selector, and keep browser/font/data inputs identical.
- Full-page image misses lazy content: wait for the page’s content-ready selector and verify that the application loads images when scrolled.
- Element capture times out: check that the locator resolves to one visible element, then increase the screenshot timeout only if slow rendering is expected.
- Automatic screenshots are missing: inspect
use.screenshot; its default isoff, and it does not replace explicitpage.screenshot()calls. - Baselines differ across machines: pin the browser version and viewport, install identical fonts, and run visual tests in a consistent environment.
Performance, reliability, and cost decisions
Viewport captures are normally cheaper in time and storage than full-page images. Full-page mode can require additional layout and scrolling work, especially on long documents with lazy resources. CSS-pixel scale reduces bytes and makes cross-device comparisons less surprising; device-pixel scale preserves high-DPI detail but can multiply dimensions. Failure-only runner artifacts keep routine CI output small, while visual assertions should be limited to stable pages or components. Masking secrets also prevents test artifacts from becoming an unintended data store.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API when you need a rendered URL without maintaining Playwright launch, browser binaries, and stabilization code. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. 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 exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
One GET request returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to try it.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteFrequently Asked Questions
Can I combine a full-page capture with an element mask?
Yes. Pass fullPage: true and a mask array in the same page.screenshot() call; the mask covers each matched locator wherever it appears in the captured page.
Should visual tests use PNG or JPEG?
PNG is the safer default for pixel comparisons because it is lossless. JPEG is useful for smaller photographic artifacts but introduces compression differences.
Does use.screenshot capture every explicit screenshot?
No. It controls screenshots that Playwright Test creates automatically. Explicit page.screenshot() and locator calls remain under your test code’s control.
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.
Recommended Free Tools
