Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Playwright Test’s built-in screenshot option for automatic failure evidence, and use testInfo.attach() or step.attach() when the image must be taken at a precise point. Configure the HTML reporter so those attachments appear in a browsable report, then open it with npx playwright show-report.
This guide covers failure-only capture, deliberately timed screenshots, step-level attachments, CI storage, missing images, and an API alternative when you do not want to maintain browser-capture code.
Which Playwright screenshot method should you use?
There are three practical choices in Playwright Test. The right one depends on when the image must be captured and where it should appear in the report.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →| Method | Trigger and timing | Report scope | Best use |
|---|---|---|---|
use.screenshot |
Automatic: on, only-on-failure, or on-first-failure |
Test result | Hands-off diagnostics |
testInfo.attach() |
Exactly where your test calls it | Test result | A known application state, such as a confirmation screen |
step.attach() |
Exactly where it is called inside test.step() |
Named step | Showing which action produced the evidence |
Screenshot capture is off by default. Automatic capture is convenient, but it happens as part of test-result handling rather than at the business event you are trying to document. For a screenshot of a specific state, take it explicitly and attach the returned bytes.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Prerequisites
- Install and run
@playwright/test, not only the lower-level Playwright browser library. The screenshot settings andtestInfoAPIs described here belong to the Test runner. - Use a Playwright configuration file such as
playwright.config.ts. - Enable the HTML reporter if you want the standard browsable report.
The examples use TypeScript, but the configuration concepts are the same in JavaScript.
How do I take a screenshot only when a test fails?
Set screenshot: 'only-on-failure' under use. The following configuration also enables the HTML reporter and prevents the report from opening automatically on every run:
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: [['html', { outputFolder: 'playwright-report', open: 'never' }]],
use: {
screenshot: 'only-on-failure',
},
});With this setting, Playwright Test requests a screenshot after a failed test. If you want an image for every test, use screenshot: 'on'. If you want only the first failure captured, use screenshot: 'on-first-failure'. These are documented screenshot modes in the TestOptions API.
Use automatic capture for broad diagnostics. Do not rely on it when timing matters—for example, when you need the page immediately after clicking “Place order” but before a later assertion or cleanup changes the state. In that case, attach a deliberate screenshot inside the test.
How do I generate and open the HTML report?
The HTML reporter writes a report directory containing the report page and its attachment assets. With the configuration above, run your tests normally:
npx playwright testThen serve and open the most recent report with:
npx playwright show-reportThe standard output directory is playwright-report, but the reporter’s outputFolder option can change it. The HTML reporter documentation also documents the PLAYWRIGHT_HTML_OUTPUT_DIR environment variable. Automatic opening can be controlled with the reporter’s open setting or PLAYWRIGHT_HTML_OPEN, whose documented values are always, never, and on-failure.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
If you enable the HTML reporter from the command line or another configuration layer, make sure the effective configuration still selects html; otherwise a different reporter may not render a browsable report.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How do I attach a screenshot to a Playwright test?
Call page.screenshot() at the exact state you want, then pass its buffer to testInfo.attach() with an image content type. This attaches the image to the test result:
import { test, expect } from '@playwright/test';
test('checkout confirmation', async ({ page }, testInfo) => {
await page.goto('/checkout/confirmation');
await expect(
page.getByRole('heading', { name: 'Order confirmed' })
).toBeVisible();
const screenshot = await page.screenshot();
await testInfo.attach('confirmation', {
body: screenshot,
contentType: 'image/png',
});
});The TestInfo reference supports either a file path or a buffer. For screenshot bytes, use an image content type such as image/png. Await attach(): Playwright copies a path-based attachment to a location reporters can access, so deleting or moving the source file before the promise resolves can leave the report without the asset.
Give attachments stable, descriptive names such as confirmation, cart-before-submit, or validation-error. The name is what readers see in the report’s attachment list.
How do I attach a screenshot to a specific test step?
Wrap the relevant action in test.step() and call step.attach() inside the callback:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →await test.step('verify confirmation page', async step => {
const screenshot = await page.screenshot();
await step.attach('confirmation', {
body: screenshot,
contentType: 'image/png',
});
});This attribution places the image under the named step rather than at test level. The step attachment API was added in Playwright v1.51; if step.attach() is unavailable, check the version installed in the project and its lockfile. The TestStepInfo reference documents the API.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
How should you choose between automatic and manual capture?
Use automatic capture for failure triage
only-on-failure keeps ordinary passing runs free of unnecessary screenshot attachments while preserving a visual artifact when a test fails. on is useful when every result needs visual evidence; on-first-failure limits capture to the first failure in the documented mode set.
Use testInfo.attach() for a business checkpoint
Manual capture is deterministic: the screenshot is taken after the assertion or action you choose. It remains attached to the test result, which is useful when the report consumer does not need step-level attribution.
Use step.attach() for a narrated workflow
Step scope makes a long test easier to inspect because the image appears alongside the named operation that produced it. Keep the step name meaningful and capture after the page reaches the intended state.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesWhy don’t my screenshots show up in the HTML report?
Automatic capture is still off
The default is off. Confirm that the effective configuration contains use: { screenshot: 'only-on-failure' }, 'on', or 'on-first-failure'. Check for another configuration file or command-line project overriding the setting.
The test uses the wrong package
testInfo, screenshot modes, and the HTML reporter are Playwright Test features. A script that imports only the lower-level Playwright library will not provide the Test runner’s result attachments.
The screenshot call or attachment is not awaited
Use await page.screenshot() and await testInfo.attach() (or await step.attach()). Also verify that the attachment has a name and the correct image/png content type.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
A non-HTML reporter is active
If you expect a browsable report, confirm that the reporter is configured as html and open the generated result with npx playwright show-report. A custom or console-only reporter may receive attachments without rendering an HTML page.
Report files and attachments were uploaded separately
When the HTML report references attachment files hosted somewhere else, configure the reporter’s attachmentsBaseURL to that location. The report can only display assets that remain reachable at the configured base URL. See the reporter documentation for the option and its expected URL behavior.
The custom destination ignores attachments
Custom reporters must inspect the attachments on each test result. The Reporter API exposes test results and their attachments; a destination that serializes only titles and statuses will omit images. Consult the Reporter API and ensure the destination copies or publishes the attachment files.
Publishing reports in CI
Treat the generated report directory and its attachment files as one artifact unless your CI design deliberately separates them. If you upload the HTML files to one location and images to another, set attachmentsBaseURL to the public or internally reachable attachment location before publishing. Keep that location available for as long as the report is meant to be read; removing the assets produces broken image links even though the HTML page still loads.
Choose the screenshot mode according to artifact volume and diagnostic value. Capturing every passing test creates more files than failure-only capture, while a manually attached checkpoint gives you evidence at a precise point without changing the global mode. No documented statistic establishes a universal runtime or storage penalty, so measure the effect in your own suite and retention policy rather than applying a generic percentage.
Recommended Free Tools
Custom reporters and attachment processing
Most projects should start with the built-in configuration and HTML reporter. A custom reporter is appropriate when your organization must publish results into another system, enforce a naming convention, or copy attachments to a separate store. Implement it against the Reporter API’s test-result attachments, and verify that the destination preserves both the attachment metadata and the binary file. If the destination has its own report viewer, it—not Playwright—determines how the image is displayed.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Or skip the browser setup
If you need a clean image of a URL rather than a screenshot tied to a Playwright test lifecycle, ScreenshotNeo provides a single-request screenshot API and an MCP server for AI agents. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or 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. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.
See the ScreenshotNeo documentation for all options. A basic call is:
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import 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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets plus custom viewports, retina scale, PDF output, custom CSS and JavaScript, clicks before capture, selector or network-idle waits, request and resource blocking, custom headers/cookies/user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, an OpenAPI specification, and compatibility with parameter names used by other screenshot APIs.
Free tools Windows power users keep installed
One-click scans. No signup required.
Every feature is available on every plan: 1,000 screenshots per month free with no card, then Starter at $5 for 3,000, Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000. Yearly billing gives two months free. Create a free ScreenshotNeo account to get 1,000 screenshots a month without a card.
FAQ
Can I keep the report closed during a CI run?
Yes. Set the HTML reporter’s open option to never; the files are still generated for later artifact upload and can be opened with npx playwright show-report or served by your report host.
What should I check before upgrading for step attachments?
Check the installed Playwright version first. The documented step.attach() API was added in v1.51; older installations may require a test-level testInfo.attach() call instead.
Frequently Asked Questions
Can I keep the report closed during a CI run?
Yes. Set the HTML reporter’s open option to never; the files are still generated for later artifact upload and can be opened with npx playwright show-report or served by your report host.
What should I check before upgrading for step attachments?
Check the installed Playwright version first. The documented step.attach() API was added in v1.51; older installations may require a test-level testInfo.attach() call instead.
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.
