In a Playwright Test, use the built-in page fixture and call await page.screenshot() to capture the current page. Save directly to a file with { path: 'screenshot.png' }, or attach the returned PNG bytes to the test result with testInfo.attach(). For failure diagnosis, use a trace when you need actions and DOM snapshots; opt into video when a replay-like recording is useful. Playwright Test gives each test an isolated browser context, while standalone Playwright scripts must create and close their own contexts.
How do I take a screenshot in a Playwright test?
Use the test runner’s page fixture. It provides a page in the isolated context for that test; navigate to the state you want to inspect, then call page.screenshot(). A screenshot call without a path returns image bytes; passing a path saves a file.
import { test, expect } from '@playwright/test';
test('capture the account page', async ({ page }) => {
await page.goto('https://example.com/account');
await expect(page.getByRole('heading', { name: 'Account' })).toBeVisible();
await page.screenshot({ path: 'artifacts/account.png' });
});Replace the example URL and assertion with your application. Ensure the destination directory exists when using a path. Waiting for a meaningful condition before capturing is more reliable than taking the image immediately after navigation: the page may still be rendering or loading content.
The Page API documents screenshots saved to a path and screenshots returned as bytes. See the Playwright Page API.
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 →#1 Best Overall
Choose the capture scope deliberately
The basic call captures the page as it appears at that moment. If you need a report attachment rather than a standalone file, capture the bytes and use testInfo.attach() as shown below. For debugging a sequence of interactions, a screenshot alone cannot show what happened before the captured state; consider a trace instead.
How do I attach a screenshot to a Playwright Test result?
Capture the returned bytes and pass them to testInfo.attach() with a name and the correct content type. The test runner copies the attachment to a location accessible to reporters.
import { test, expect } from '@playwright/test';
test('attach a screenshot to the result', async ({ page }, testInfo) => {
await page.goto('https://playwright.dev');
await expect(page).toHaveTitle(/Playwright/);
const screenshot = await page.screenshot();
await testInfo.attach('screenshot', {
body: screenshot,
contentType: 'image/png',
});
});This is a Playwright Test runner example, not a standalone Playwright library script. The runner provides both page and testInfo. Attachments are useful when the image should travel with the test result and be available to the configured reporter, rather than being written to a fixed application path. Consult the TestInfo API for attachment behavior.
Capture a useful state
- Navigate to the page and wait for an application-specific signal, such as a visible heading or completed assertion.
- Capture after the interactions that establish the state you want to document.
- Use
contentType: 'image/png'when the screenshot bytes are PNG, as in the example.
How are Playwright Test browser contexts isolated?
Playwright Test runs each test in its own browser context. The context isolates cookies and storage, so state created by one test does not normally leak into another. The built-in page fixture gives the test a page in that context; you generally do not need to create a browser or context yourself inside a regular test.
Recommended Free Tools
This runner-managed lifecycle is different from using Playwright as a library in a script. A standalone script must launch a browser, create a context and page, and close them when finished. Contexts are the browser-level boundary for session state and, for manually configured video recording, artifact finalization. See the official guides to browser contexts and test fixtures.
Should I use a screenshot or a trace to debug a failed test?
Use the artifact that answers the debugging question. A screenshot shows a single visual state. A trace provides a sequence of actions and additional debugging context, including DOM snapshots and network activity. A video records the run visually and is useful when a replay-like view of the page matters.
| Artifact | Best for | Important distinction |
|---|---|---|
| Screenshot | One visual state; a simple file or test attachment. | Static image, not a history of interactions. |
| Trace | Investigating actions and page state around a problem. | Direct context tracing does not record test assertions; use test-runner tracing when assertion-level failure context matters. |
| Video | A visual recording of a test run. | Opt-in, and the recording is finalized after the page or context closes. |
Tracing every test can be performance heavy, so select a retention mode that fits the debugging need rather than collecting traces indiscriminately. The Trace Viewer guide describes action details, locators, action duration, source location, DOM snapshots and a screenshot film strip when screenshots are enabled.
Configure traces in Playwright Test
For runner-managed tests, configure the trace option in the Playwright Test configuration. For example, retain-on-failure keeps traces for failures rather than retaining every successful run.
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'retain-on-failure',
},
});Use the option appropriate to your debugging workflow. The Trace Viewer documentation describes modes such as retaining traces on failure; retention choices affect how many artifacts accumulate. Runner configuration is the better route when assertions and test-failure context are part of what you need to investigate.
Use direct tracing in a standalone library script
If you are not using the test runner, start and stop tracing through the browser context. The tracing API captures browser operations and network activity, but it does not capture test assertions.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const context = await browser.newContext();
await context.tracing.start({ screenshots: true, snapshots: true });
try {
const page = await context.newPage();
await page.goto('https://example.com');
await page.getByRole('link', { name: 'About' }).click();
} finally {
await context.tracing.stop({ path: 'trace.zip' });
await context.close();
await browser.close();
}This is a library pattern: it creates its own browser and context. Open the resulting trace with Playwright’s Trace Viewer. If you need test assertion context, use the runner’s trace configuration instead. See the Tracing API.
How do I record a Playwright Test video?
Video recording is off by default. Enable it in Playwright Test’s video option, choosing a mode according to what you want to retain. For example, these settings record on the first retry or retain videos only for failed runs:
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
video: 'on-first-retry',
// Alternatively: video: 'retain-on-failure',
},
});Playwright documents modes for recording every test, recording on the first retry, retaining only failed runs, and recording on retries. Use the one that fits your workflow: retaining on failure limits routine artifacts, while recording on retries can help investigate intermittent failures. Video is available only after the page or browser context closes. Do not try to consume the recording before that lifecycle step has completed. The Videos guide covers the modes.
Record video with a manually created context
Outside the test runner, configure recording while creating the context and close that context before reading the video. The browser API documents the context lifecycle and video setup.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const context = await browser.newContext({
recordVideo: { dir: 'videos/' },
});
const page = await context.newPage();
await page.goto('https://example.com');
await page.getByRole('link', { name: 'About' }).click();
// Closing the context finalizes its video.
await context.close();
await browser.close();Use an existing directory for recordings. If you manually create a recording context and omit await context.close(), the video may not yet be finalized when your script tries to access it. The runner handles its test contexts, but standalone scripts own their cleanup. See the Browser API.
When should you use each capture method?
- Use a screenshot when a single state is enough, such as recording a visual result or attaching an image to a report.
- Use a trace when the sequence of actions, locator details, snapshots or network activity is needed to understand a failure. Prefer runner tracing if assertions matter.
- Use video when a visual recording of the run will help explain behavior, especially for retry-based or failed-run investigation.
These are different artifacts, not interchangeable formats. Choose by diagnostic purpose and retention needs. The documentation does not establish quantitative storage or performance comparisons among screenshots, traces and videos; it does note that tracing every test can be performance heavy.
Troubleshooting screenshot, trace, and video capture
The screenshot is blank or shows an incomplete page
The capture may have happened before the application reached the state you intended. Wait for a meaningful page condition—such as a visible locator or a successful assertion—before calling page.screenshot(). A screenshot records the page at capture time; it does not explain whether later loading or interaction would have changed it.
The screenshot attachment is missing from the test result
Confirm the test uses Playwright Test and passes its testInfo argument, then await testInfo.attach() with the screenshot bytes and contentType: 'image/png'. Check the reporter output for attachments; attach() makes the file accessible to reporters rather than saving it to an arbitrary path.
The trace does not show an assertion
That is expected when tracing directly with browserContext.tracing: the API records browser operations and network activity, not test assertions. Configure tracing through Playwright Test if assertion-level test debugging is needed.
The video file is unavailable or incomplete
For a manually created video context, await context.close() before accessing the recording. The recording is finalized only after the page or browser context closes. In Playwright Test, let the runner finish the test lifecycle before inspecting its video artifact.
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 glitchesArtifacts are accumulating or runs are slower
Review retention rather than enabling maximum capture on every run. Use failure- or retry-focused trace and video modes where they fit the problem. Tracing every test can be performance heavy; the documentation gives no universal storage estimate, so artifact volume depends on your test suite and retention choices.
Or skip the browser setup: ScreenshotNeo
If your goal is a screenshot of a live website rather than capturing the state inside your own Playwright test, ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP or PDF. Its capture flow accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers identify the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info and capture_pdf.
For a website screenshot, the API call is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It also supports full-page captures, selector-based element capture, dark mode, device and viewport settings, PDF options, custom CSS and JavaScript, waits, request blocking, custom headers and cookies, caching, signed links, asynchronous jobs, bulk capture, a usage API and an OpenAPI spec. These are for website captures and do not replace Playwright Test’s in-test page fixture, assertion context or trace workflow.
ScreenshotNeo’s 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. Sign up for free and get 1,000 screenshots a month with no card.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can I use page.screenshot() without saving a file?
Yes. Without a path, it returns screenshot bytes, which you can pass to testInfo.attach().
Does Playwright Test record video automatically?
No. Video is off by default; enable a documented video mode in configuration.
Does direct Playwright tracing include assertions?
No. Direct context tracing records browser operations and network activity, not test assertions.
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.
