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 →To include failure evidence in a Playwright HTML report, set screenshot: 'only-on-failure' in playwright.config.ts, choose the HTML reporter, and run npx playwright test --reporter=html. Playwright writes the report to playwright-report by default; use npx playwright show-report to open it. For deeper debugging, capture traces on retry, and use TestInfo.attach when you need a deliberately named screenshot attached to a particular test.
What the HTML report contains—and where screenshots fit
Playwright’s HTML reporter creates a self-contained folder for a test run that can be served as a web page. It presents results across the tests and browsers that ran, along with their durations. Screenshots, videos, and traces are supporting artifacts: they help explain a result but are not the report itself.
Playwright normally places screenshot, video, and trace files in the test output directory, typically test-results. The HTML report presents test-run information and links to relevant evidence. Keep the report folder and its related output artifacts together when you publish or archive a run, so readers can inspect the evidence associated with failures.
There are three useful levels of visual evidence:
- Failure screenshots: a quick visual record of the page when a test fails.
- Explicit attachments: screenshots you choose to capture at a particular point and attach to a test.
- Traces: richer debugging records that can help reconstruct the sequence leading to a failure.
Generate and open a Playwright HTML report
Run the reporter from the project directory where Playwright is configured:
npx playwright test --reporter=htmlThe HTML report is written to playwright-report by default. To open a report from a completed run, run:
npx playwright show-reportThe report is useful locally and can also be published as a CI artifact or served as a web page. The HTML reporter supports options for a report title, output folder, whether to open the report automatically, host, port, and an attachments base URL. Those settings let a team adapt where and how the report is presented without changing how tests capture screenshots.
Capture screenshots only when a test fails
For most CI runs, 'only-on-failure' is a practical balance: passing tests do not generate screenshots, while failures retain a visual clue for investigation. Configure it alongside the reporter and a trace policy in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: [['html', { open: 'never' }]],
use: {
screenshot: 'only-on-failure',
trace: 'on-first-retry',
},
});This keeps CI from automatically opening the report and asks Playwright to save a screenshot when a test fails. The trace policy retains a trace on the first retry, which can provide more context than a still image. When the run is complete, inspect the HTML report and the linked trace for the failing test.
Choose a screenshot scope
The supported screenshot settings are 'off', 'on', and 'only-on-failure'. Use them according to the evidence you need:
'off'disables automatic screenshots.'on'captures screenshots for every test, useful when broad visual evidence is needed but likely to produce more artifacts.'only-on-failure'limits automatic screenshots to failures, reducing unnecessary output while preserving failure evidence.
Automatic screenshots are a test-run policy. They are not a substitute for a deliberate checkpoint in a test when the screenshot must be captured at a precise moment or with a meaningful attachment name.
Attach a custom screenshot to a test
Use page.screenshot to save an image at a path managed by the test, then call testInfo.attach with the file path and its MIME type. This example captures a screenshot after the test’s own actions and associates it with that test:
import { test, expect } from '@playwright/test';
test('account page shows the profile', async ({ page }, testInfo) => {
await page.goto('https://example.com/account');
await expect(page.getByRole('heading', { name: 'Profile' })).toBeVisible();
const screenshotPath = testInfo.outputPath('account-profile.png');
await page.screenshot({ path: screenshotPath, fullPage: true });
await testInfo.attach('account-profile', {
path: screenshotPath,
contentType: 'image/png',
});
});Replace the example URL and assertion with the page and condition your test actually verifies. The example uses a full-page image; remove fullPage: true if you only need the visible viewport. Supplying contentType: 'image/png' identifies the attachment as a PNG, allowing reporters to display it appropriately.
Use an explicit attachment when you need evidence from a specific state, such as immediately after a navigation or before a cleanup step. Do not attach the same image redundantly if the automatically captured failure screenshot already answers the diagnostic question. A stable, descriptive attachment name also makes the report easier for a teammate to scan.
Use traces when a screenshot is not enough
A screenshot shows a state, but often not how the test reached it. A trace can offer action snapshots, logs, source locations, network information, metadata, and attachment inspection in Trace Viewer. This additional sequence-level context is especially useful for failures that depend on timing, navigation, or an unexpected intermediate state.
With trace: 'on-first-retry', a trace is retained on the first retry rather than for every passing execution. The HTML report links to trace evidence for inspection. Open the failed test in the report, follow its trace link, and use Trace Viewer to examine the action sequence and surrounding information. Screenshots remain valuable as a quick visual summary; traces are the better next step when the summary does not explain the failure.
Trace attachments can also help with visual-regression review: expected images, actual images, and image differences can be inspected as part of the trace evidence. Treat that as a review aid, not as a replacement for the assertions and comparison logic in the test.
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 minuteRank #4
Choose artifact scope and publication deliberately
Artifacts have practical trade-offs. Capturing for every test creates the broadest evidence set, but also adds files to manage and retain. Capturing on failure focuses the output on the tests that need attention. Traces add more debugging depth than a screenshot but may require more storage and a deliberate retention policy. Choose the minimum useful evidence for routine runs, then expand capture where a failure is hard to diagnose.
| Choice | What it provides | Trade-off |
|---|---|---|
screenshot: 'on' |
Screenshots for every test. | More artifacts to store and review. |
screenshot: 'only-on-failure' |
Visual evidence focused on failed tests. | Does not capture passing-test states. |
trace: 'on-first-retry' |
Trace evidence on the first retry to investigate sequence and context. | More involved than inspecting a still image. |
| Local report folder | A report that can be opened or served locally. | Sharing depends on distributing or serving the report and associated artifacts. |
| Hosted CI artifacts | A report and evidence retained with a CI run for team access. | Availability and retention depend on the CI system and its artifact settings. |
For a local run, keep playwright-report available and open it with npx playwright show-report. In CI, publish the generated report and the relevant test output artifacts using your CI system’s artifact mechanism. The exact retention duration and access controls are set by that system, not by the Playwright HTML reporter. If your team needs longer-term storage, access controls, or run-to-run analysis, evaluate a CI reporting or test-observability platform against those requirements.
Troubleshoot missing screenshots and report evidence
The report opens, but a screenshot is missing
Check that screenshot capture is not set to 'off', and confirm the test actually failed if the setting is 'only-on-failure'. Look in the test output directory, typically test-results, as well as the report view. If you publish artifacts from CI, make sure the published files include the report and its associated test output rather than only a top-level HTML file.
A passing test has no screenshot
That is expected with 'only-on-failure'. If you need a screenshot from a passing test, take and attach it explicitly at the point of interest, or choose 'on' when screenshots from every test are required.
Recommended Free Tools
Best Value
A custom attachment does not display as an image
Check that the file was saved successfully and that the attachment declares the correct content type. For a PNG, use contentType: 'image/png'. Also ensure the file remains available with the report artifacts when the report is shared.
The report is available but the trace is not
Confirm that a trace policy is configured and that the test run included the retry condition needed by 'on-first-retry'. A first attempt that passes may not produce a retry trace. Inspect the failed test’s output artifacts and keep them with the report when publishing the run.
The report does not open automatically
The example configuration sets open: 'never', so this is intentional. Open the finished report with npx playwright show-report. If you want a different opening behavior, adjust the HTML reporter’s open option.
Or skip the browser setup
Playwright’s report workflow is the right choice for browser-test results, failure screenshots, and traces. If the task is instead to capture a website from an external service, ScreenshotNeo offers a single-request screenshot API; it is not a replacement for Playwright’s test runner or HTML report. The [ScreenshotNeo docs](https://screenshotneo.com/docs/) describe its request options.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThis request returns a screenshot using the service’s API. Before capture, ScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. An 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 screenshots; every feature is available on every plan, and yearly billing gives two months free. See ScreenshotNeo for the service, then sign up for the free plan.
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.
