Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
In Playwright with TypeScript, capture a page with await page.screenshot({ path: 'screenshot.png' }), or capture the full scrollable page with fullPage: true. Use locator.screenshot() for one element, the test runner’s screenshot option for automatic failure artifacts, and toHaveScreenshot() when you want a visual regression assertion. The right method depends on whether you need an image to inspect, attach to a report, or compare against a baseline.
How to take a screenshot in Playwright with TypeScript
In a Playwright Test project, page.screenshot() captures the current page. Supplying a path writes an image file; omitting the path gives you image data you can attach to the test or pass to another process. The following test captures the full page and attaches the resulting PNG to the test report:
import { test, expect } from '@playwright/test';
test('capture a page', async ({ page }, testInfo) => {
await page.goto('https://example.com');
const image = await page.screenshot({ fullPage: true });
await testInfo.attach('page screenshot', {
body: image,
contentType: 'image/png',
});
});This example uses the Playwright Test runner, imported from @playwright/test. The screenshot API itself is documented in Playwright’s Screenshots guide. The example attaches a full-page image; remove fullPage: true to capture the current viewport instead.
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 →Save the image to a file
When you want an ordinary image file rather than a test attachment, provide a path:
#1 Best Overall
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });The path and file type should agree: use a .png path for PNG or a .jpg or .jpeg path for JPEG. Playwright’s screenshot options also support selecting an image type and other capture settings; consult the official guide for the current option list. Without fullPage: true, the capture is the visible viewport, not the entire scrollable document.
Choose viewport, full page, or one element
| What you need | Use | What it captures |
|---|---|---|
| The visible screen | page.screenshot() |
The current viewport by default. |
| The whole scrollable page | page.screenshot({ fullPage: true }) |
A full-page image rather than only the current viewport. |
| A particular component | page.locator('.header').screenshot() |
The selected locator element. |
| A test artifact | testInfo.attach() with screenshot bytes or a path |
An attachment available to the test reporter. |
| A rendering comparison | expect(page).toHaveScreenshot() or expect(locator).toHaveScreenshot() |
A screenshot assertion against a stored expectation. |
Capture a single element
Use a locator when the page is large but the part you need is small:
await page.goto('https://example.com');
await page.locator('.header').screenshot({ path: 'header.png' });Locator screenshots scroll the element into view and perform actionability checks. They do not make an obscured element visible: if another element covers it, the capture does not automatically uncover it. A locator that identifies a scrollable container captures the content currently shown inside that container; it does not turn the container into a full-page capture. These details are documented in the Locator API.
Free tools Windows power users keep installed
One-click scans. No signup required.
Prefer locator screenshots over the older ElementHandle screenshot API. Playwright marks the ElementHandle method as discouraged and directs users toward locator-based capture in its ElementHandle API.
Attach screenshots to a Playwright test
For debugging and CI reports, an attachment is often more useful than a file saved somewhere in the working directory. testInfo.attach() accepts image bytes and a content type, as in the first example, or a file path:
await testInfo.attach('page screenshot', {
path: 'screenshot.png',
contentType: 'image/png',
});Playwright copies an attachment to a reporter-accessible location. If you create a temporary screenshot file, await the attachment before deleting that file so Playwright has time to copy it. See the TestInfo API for attachment details.
Take a screenshot automatically when a test fails
If the goal is to diagnose failed tests, configure screenshots once in the Playwright Test configuration instead of adding capture code to every test. For example, set screenshot: 'only-on-failure' in the use options:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
screenshot: 'only-on-failure',
},
});The documented modes are off, on, only-on-failure, and on-first-failure. Choose based on when you want the runner to produce screenshots:
off: do not capture automatic screenshots.on: capture screenshots for every test.only-on-failure: capture for tests that fail.on-first-failure: capture on the first failure in a test’s retry sequence.
For failure diagnosis, only-on-failure is a practical starting choice: it preserves evidence for failures without asking the runner to capture an image for every passing test. That is a workflow recommendation, not a change to the supported modes. The option can also be an object with a mode and screenshot options such as fullPage. Its documented default is false for fullPage, so a configured automatic screenshot otherwise captures the viewport. Refer to the TestOptions API for the configuration shape and available options.
Use screenshots for visual regression tests
A diagnostic screenshot gives you an image to inspect. A visual regression test goes further: it checks whether the rendering matches an expected screenshot. In Playwright Test, use toHaveScreenshot() on a page or locator:
import { test, expect } from '@playwright/test';
test('page rendering matches its baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot();
});For a component-level comparison, assert against a locator instead:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsawait expect(page.locator('.header')).toHaveScreenshot();These screenshot assertions are supported by the Playwright Test runner. Before making the comparison, Playwright waits until two consecutive screenshots produce the same result, then compares the last image with the expectation. That stabilization step is useful, but it does not remove the need to make the test page and its contents suitably consistent for your own test. The documented assertion behavior is in the PageAssertions API.
Keep snapshot locations organized
When a test suite has multiple projects or needs baselines arranged by test path, configure snapshotPathTemplate in the Playwright Test configuration. Its available path tokens include the test directory, test file path, project name, and snapshot argument. Use those tokens to make the intended separation explicit rather than relying on an ambiguous shared location. See the TestConfig API for the configuration and token details.
Or skip the browser setup
If you need a website screenshot from an API rather than a Playwright browser test, ScreenshotNeo takes a URL in one GET request and returns an image or PDF. Here is a complete cURL example, with the API documentation alongside it: ScreenshotNeo API docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpIt can also be called from Python or Node.js:
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)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 accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status. It also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; yearly billing gives two months free. Every feature is available on every plan.
| Plan | Price | Monthly screenshots |
|---|---|---|
| Free | $0 | 1,000 |
| Starter | $5 | 3,000 |
| Growth | $15 | 15,000 |
| Pro | $39 | 60,000 |
| Scale | $99 | 250,000 |
| Business | $249 | 1,000,000 |
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Troubleshooting Playwright screenshots
- The image shows only the top part of the page. A regular page screenshot captures the viewport. Set
fullPage: truewhen you need the full scrollable page. - The element screenshot is incomplete. If the locator points to a scrollable container, the capture shows its current scroll state. A locator screenshot is not a request to capture all content hidden inside that container.
- The target is covered or not visible. Locator screenshot capture performs actionability checks and scrolls the target into view, but a covered element is not made visible for you. Adjust the page state or target before capturing.
- A test fails without an automatic screenshot. Check that the test runner configuration uses the intended mode, such as
only-on-failure, and that automatic screenshot capture has not been set tooff. If you need a full-page failure image, configure the screenshot option object withfullPage: true. - An attachment is missing from the report. Await
testInfo.attach(). If it attaches a temporary path, do not remove the file until the awaited attachment call has completed. - A visual assertion does not behave like a saved diagnostic image.
toHaveScreenshot()is an assertion against a stored expectation, not just a command to save an arbitrary screenshot. Usepage.screenshot()or a locator screenshot when you only need image output.
Which Playwright screenshot method should you use?
- For a one-off page image, use
page.screenshot(). - For all scrollable page content, set
fullPage: true. - For one component, use
locator.screenshot(). - For report evidence from test code, attach screenshot bytes or a file with
testInfo.attach(). - For automatic failure evidence, configure the runner’s screenshot mode.
- For rendering checks against a baseline, use
toHaveScreenshot().
Those approaches solve different problems: producing an image, collecting a test artifact, and asserting that a rendering has not changed are not interchangeable. Select the method that matches the artifact’s purpose.
Frequently Asked Questions
Can I use Playwright screenshots without the Playwright Test runner?
The test configuration options and screenshot assertions described here belong to Playwright Test. The page and locator screenshot methods are browser APIs; use the official Playwright documentation for the package and runtime you have installed.
Does full-page mode capture every item in a scrollable widget?
No. A full-page page screenshot covers the scrollable page; a locator targeting a scrollable container reflects the container’s current scroll state.
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.
