For Node.js projects already using Playwright Test, start with Playwright’s built-in expect(page).toHaveScreenshot() for visual regression checks. For capture alone, use page.screenshot(); it saves an image or returns a buffer without deciding whether the result differs from a baseline. If you want screenshots without managing a browser setup, ScreenshotNeo is an alternative to try first: it removes common page overlays before capture and bills only clean shots.
Which Playwright screenshot library should you use?
| Need | Start with | Why |
|---|---|---|
| Visual regression tests in Playwright Test | expect(page).toHaveScreenshot() |
It creates screenshot baselines and compares future test runs against them. |
| Capture an image for another workflow | page.screenshot() |
It can write an image file or return image bytes for your own processing or comparison. |
| Hosted capture rather than browser setup | ScreenshotNeo | It removes common consent banners, popups and chat widgets before capture; bot checks, blank pages and failed loads are not billed. |
| Vendor-run visual testing workflow | Evaluate Percy or Applitools | Both have documented Playwright connections, but current pricing, limits and workflow fit need direct vendor verification. |
These are not interchangeable categories. Playwright’s screenshot API captures; its snapshot assertion adds baseline comparison within Playwright Test. For a custom image pipeline or another test runner, capture with Playwright and choose a separate comparison and storage workflow.
Use Playwright Test’s built-in screenshot assertion
The assertion is documented as a Playwright Test runner feature. On first run, it generates a reference screenshot; later runs compare against that saved baseline. Playwright says the assertion waits for two consecutive screenshots to match before saving, which can help avoid capturing a changing frame. See Playwright visual comparisons and the SnapshotAssertions API reference.
Runnable Node.js example
In a project with Playwright Test installed, add a test such as tests/homepage.spec.js:
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 match#1 Best Overall
const { test, expect } = require('@playwright/test');
test('homepage visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('homepage.png');
});Run it with:
npx playwright test tests/homepage.spec.jsThe first run creates the baseline associated with the test; subsequent runs check for visual differences. Review baseline changes before accepting them into version control. To deliberately update snapshots after an approved design change, use:
npx playwright test --update-snapshotsControl expected variation
Small rendering differences can be handled with the assertion’s tolerance options, including pixel-difference thresholds documented in the API. For dynamic regions or animations, Playwright’s visual-comparisons guide documents a stylesheet option to hide or stabilize changing content. Apply those controls narrowly: overly broad tolerance or hiding large regions can conceal genuine regressions.
Baseline matching is only meaningful when the capture conditions are comparable. Playwright warns that browser rendering may vary with host OS, browser version, settings, hardware, power source, headless mode and other factors. Keep baseline creation and CI execution environments aligned, including browser versions and rendering settings.
Rank #2
Capture screenshots with page.screenshot()
When you need an image but not Playwright’s built-in baseline assertion, use the page screenshot API. The official Playwright screenshots documentation covers saving to a file, returning an image buffer, full-page capture and element screenshots.
Runnable Node.js capture example
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'page.png', fullPage: true });
await browser.close();
})();To obtain bytes for an image-processing or comparison step rather than writing directly to disk:
const imageBuffer = await page.screenshot({ type: 'png' });For a specific element, locate it and capture that element instead of the whole page:
Rank #3
const element = page.locator('main');
await element.screenshot({ path: 'main.png' });A capture API does not create baselines, review changes, calculate a diff or integrate results into a test report by itself. Those remain choices for your application or separate visual-testing tool.
How to choose and keep visual tests reliable
Match the tool to the workflow
- Already on Playwright Test: use
toHaveScreenshot()unless you have a clear need for a separate review, comparison or storage system. - Using a different runner or custom pipeline: use
page.screenshot(), then select a comparison engine and baseline process compatible with that workflow. - Considering a hosted service: Percy’s
@percy/playwrightpackage page documents a Playwright integration. Applitools’ November 2024 vendor comparison lists Playwright among supported frameworks; that is a vendor claim, not an independent product evaluation. Verify current browser support, review process, integrations, plan limits, pricing and data handling with each vendor.
Keep baselines intentional
- Generate baselines in the same browser and environment used for repeatable test runs.
- Use tolerance or page styling only for known, bounded sources of variation.
- When a visual change is expected, regenerate snapshots with
npx playwright test --update-snapshots. - Review changed image baselines alongside the code change before accepting them.
Understand the comparison component
Playwright’s visual-comparisons guide identifies pixelmatch as the image-comparison library used by its visual comparisons. Pixel comparison alone is not a complete testing workflow: capture, baseline storage, update review and test-runner integration also have to be addressed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Or skip the browser setup
ScreenshotNeo takes a URL in one GET request and returns a PNG, JPEG, WebP or PDF. Its screenshot API and MCP server are aimed at developers who want capture without running a browser locally. The API supports options including full-page capture, CSS-selector element capture, viewport and device presets, dark mode, custom CSS or JavaScript, waits, request blocking, cookies and headers; see the ScreenshotNeo documentation.
Rank #4
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie banners and consent overlays, newsletter popups and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; response headers identify the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_infoandcapture_pdffor AI agents and MCP clients. - The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common problems and fixes
A screenshot test fails after a harmless render change
Check whether the difference is an expected design update or environment drift. Align the browser and execution environment first; for genuinely volatile page content, use a narrowly targeted stylesheet or tolerance setting. If the change is intentional, update and review the baseline rather than suppressing the difference globally.
The first run reports a missing snapshot or creates one
That is the baseline-generation step. Inspect the generated image, then keep it with the test. On later runs the assertion compares against it.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCI differs from a developer’s machine
Rendering can change across OS, browser version, hardware, settings and headless mode. Use a consistent test environment for creating and checking baselines, and avoid regenerating reference images casually on a different setup.
You have an image but no regression result
page.screenshot() only captures. Add a comparison step or use expect(page).toHaveScreenshot() under Playwright Test if you need baseline assertions.
FAQ
Does Playwright use pixelmatch?
Playwright’s visual-comparisons documentation names pixelmatch as the comparison library used by its visual comparisons. That does not make pixelmatch, by itself, a complete screenshot test runner or baseline workflow.
Can I use toHaveScreenshot() without Playwright Test?
The snapshot assertion is documented for the Playwright Test runner. For a different runner, use screenshot capture and supply a separate comparison workflow.
Recommended Free Tools
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.
