Recommended Free Tools
For Playwright Test, set use.screenshot to 'only-on-failure' in playwright.config.ts. Playwright then captures a screenshot automatically when a test fails; you do not need to add error-handling code to every test. The setting is off by default. Use page.screenshot() with testInfo.attach() when you need a screenshot at a specific point, and consider a trace on the first retry when a CI failure needs more context.
Automatically capture screenshots for failed tests
In a Playwright Test project, configure the screenshot option in the use section of the configuration file. The following TypeScript example uses the standard @playwright/test package:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: 'only-on-failure',
},
});Save this as playwright.config.ts in the project root, or merge the use property into the existing configuration. The equivalent option can be used in JavaScript configuration as well; keep the file extension and syntax consistent with the project. Playwright documents the option in its configuration reference.
With 'only-on-failure', Playwright captures after each failed test. The image is a test artifact and is written under the test output directory, typically test-results. The exact folder structure depends on the project and its reporter/output configuration. See the TestOptions API for the documented behavior and options.
#1 Best Overall
Choose between the screenshot modes
The documented screenshot modes are 'off', 'on', 'only-on-failure', and 'on-first-failure'. The default is 'off', so no screenshot is captured unless you opt in.
'off': do not capture screenshots through this option.'on': capture for every test, whether it passes or fails.'only-on-failure': capture after each failed test.'on-first-failure': limit capture to the first failure of a test.
For the common goal of retaining an image for failed tests, 'only-on-failure' is the direct choice. Use 'on-first-failure' when a test can fail repeatedly, such as during retries, and you want to avoid capturing an image for every failure. Refer to the installed Playwright version’s documentation if you are working with a version that may not match the current API pages.
Viewport or full-page capture
The automatic screenshot is a viewport capture by default. The screenshot option also supports screenshot settings such as fullPage and omitBackground. For example, to capture the full scrollable page after a failure:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: {
mode: 'only-on-failure',
fullPage: true,
},
},
});Use this object form only where supported by the Playwright version installed in your project; the mode form is documented in the TestOptions API. Full-page images can be much taller and larger than viewport captures. They help when the defect is below the fold, but may be harder to inspect and store.
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 →Capture and attach an image at a chosen point
Use a manual screenshot when the useful state occurs before the test finishes—for example, immediately after navigating, after opening a menu, or before a destructive action. Call page.screenshot() and attach its returned buffer with testInfo.attach() so a reporter can expose it as a test attachment.
import { test, expect } from '@playwright/test';
test('shows the expected result', async ({ page }, testInfo) => {
await page.goto('https://playwright.dev');
const screenshot = await page.screenshot();
await testInfo.attach('screenshot', {
body: screenshot,
contentType: 'image/png',
});
await expect(page).toHaveTitle(/Playwright/);
});This example attaches an in-memory PNG rather than asking the test to save a file path. Playwright’s TestInfo API also allows an attachment from a file path. TestInfo is available in test functions, beforeEach/afterEach and beforeAll/afterAll hooks, and test-scoped fixtures.
A manual screenshot is only taken if execution reaches the screenshot call. If an assertion throws first, code later in the test body is skipped. For routine capture of failures occurring anywhere in a test, configure the built-in failure mode; add manual capture when you need a named attachment or a precise point-in-time image.
Take a screenshot in cleanup code
An afterEach hook can inspect the test result and attach an image when the test failed. This offers control over the attachment name and timing, but it is not a replacement for the built-in option if all you need is a standard failure screenshot. If using a hook, check the installed version’s TestInfo properties and ensure the page is still available at the time the hook runs. A page that has already closed cannot produce a new screenshot.
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 matchUse traces for failures that need more context
A screenshot is a single visual state. It usually cannot show which actions led to the failure, the sequence of page changes, or the surrounding network activity. For CI diagnosis, Playwright recommends Trace Viewer and configuring tracing on the first retry. Its Best Practices guidance cautions that tracing every test is performance-heavy.
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 1,
use: {
trace: 'on-first-retry',
},
});This enables one retry and records a trace on that first retry. If the retry passes, its trace can still help explain a flaky initial failure; if it fails again, the trace documents the retry. The retry policy is a separate decision from screenshot mode. Configure both when you want a failure image and a richer retry artifact:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 1,
use: {
screenshot: 'only-on-failure',
trace: 'on-first-retry',
},
});Trace Viewer presents actions, DOM snapshots, network requests, metadata, attachments, and a screenshot filmstrip when screenshots are enabled. The Trace Viewer guide explains how to open and inspect traces. For a local diagnostic run, the documented commands are:
npx playwright test --trace on
npx playwright show-trace trace.zipThe first command runs tests with tracing enabled; the second opens the resulting trace archive. Traces can contain substantially more information about the test than a single screenshot, so consider what page and network data they may retain before sharing artifacts outside your team.
Do not confuse Test tracing with the browser-context tracing API
Playwright’s lower-level browserContext.tracing API captures browser operations and network activity but does not record test assertions. For a failure trace tied to Playwright Test, use the test runner’s use.trace configuration. The distinction is documented in the Tracing API reference.
Choose the right capture method
| Need | Method | Trade-off |
|---|---|---|
| A screenshot automatically after test failure | use.screenshot: 'only-on-failure' |
Minimal setup; captures failed tests without extra test code. |
| Capture a particular state or attach a named image | page.screenshot() and testInfo.attach() |
More control, but the code must execute to the screenshot call. |
| Understand the steps and state around a CI failure | trace: 'on-first-retry' with Trace Viewer |
Richer context; tracing every test is performance-heavy. |
For many suites, a practical combination is automatic screenshots on failure plus first-retry traces in CI. Use manual attachment only for additional checkpoints or named evidence that the automatic artifact does not provide.
Or skip the browser setup
If you need a screenshot of a URL rather than an artifact tied to Playwright Test’s own execution, ScreenshotNeo offers a one-request screenshot API and an MCP server. Its clean-capture steps accept consent banners and remove more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, with response headers identifying the page verdict and billing outcome. AI agents can use its MCP tools, including take_screenshot, get_page_info and capture_pdf. See ScreenshotNeo and its API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://playwright.dev -o shot.webpThe endpoint returns a screenshot in the requested image format or a PDF; this example saves the response as shot.webp. It is a service call, not a substitute for Playwright’s test-runner artifacts when you need the browser state produced by a particular failing test. ScreenshotNeo’s Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month without a card.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Troubleshoot missing or unhelpful screenshots
No screenshot appears after a failure
- Confirm the project is using Playwright Test and the active config includes
use.screenshot. A standalone Playwright script does not use the test runner’s configuration behavior in the same way. - Check that the value is
'only-on-failure', not the default'off'. - Look in the configured test output directory, typically
test-results, and inspect the test report or reporter output for attachments. - Make sure the test actually failed. A passing test will not receive an artifact in this mode.
- Check for project-specific configuration overrides or multiple config files; the setting must apply to the project that ran the test.
The screenshot is captured, but the important state is missing
The automatic image is a viewport screenshot unless full-page capture is enabled. If the issue is below the visible viewport, set the full-page option. If the relevant state exists only briefly, use a manual screenshot and attach it immediately at that point, or inspect the trace timeline for the sequence.
A manual attachment is absent
Verify that execution reached page.screenshot(); an earlier failed assertion prevents later lines from running. Confirm that testInfo.attach() receives either a valid buffer in body or an accessible file path, and that the content type matches the image. Inspect the reporter’s attachment view and the test output directory rather than expecting a manually returned screenshot buffer to be automatically listed as an attachment.
The trace does not include assertions
If you enabled the lower-level context tracing API, switch to Playwright Test’s use.trace setting for the test-runner trace. The context API records browser-level activity and network data, not the test assertion stream.
Trace capture slows the suite
Do not trace every test by default if the overhead is a concern. For CI, configure trace: 'on-first-retry' so trace collection is focused on retried failures. Keep automatic failure screenshots if a single image is enough for routine triage, and reserve traces for cases where action and network context matters.
Frequently Asked Questions
Does Playwright take screenshots on errors by default?
No. Playwright Test’s screenshot mode defaults to 'off'; opt in with use.screenshot.
What is the difference between 'only-on-failure' and 'on-first-failure'?
The former captures after each failed test; the latter limits capture to a test’s first failure.
Can I use this setting with a plain Playwright script?
The configuration option described here is for Playwright Test. A standalone script should call the screenshot API directly.
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
