Pass a filename to Playwright Test’s toHaveScreenshot() assertion to give a screenshot snapshot a custom name: await expect(page).toHaveScreenshot('checkout-summary.png'); If you want the file path to include the test title automatically, configure snapshotPathTemplate with its {testName} token. The assertion name and the test-title-based path are separate controls.
Give an individual screenshot assertion a custom name
Pass the desired filename to toHaveScreenshot(). This TypeScript example names the baseline for a checkout page:
As an Amazon Associate I earn from qualifying purchases.
import { test, expect } from '@playwright/test';
test('checkout totals update', async ({ page }) => {
await page.goto('/checkout');
await expect(page).toHaveScreenshot('checkout-totals.png');
});Playwright uses PNG by default; a .webp extension selects WebP. You can give separate assertions distinct names—for example, before.png and after.png—to distinguish visual states within the same test.
Include the test title in the snapshot path
Use snapshotPathTemplate when you want a reusable directory and naming policy across tests, rather than only a descriptive name for one assertion. For example, this configuration places snapshots in a folder based on the sanitized test title:
#1 Best Overall
import { defineConfig } from '@playwright/test';
export default defineConfig({
snapshotPathTemplate: '{testDir}/__screenshots__/{testName}/{arg}{ext}',
});With an assertion name of checkout-totals.png, {arg} is checkout-totals and {ext} is .png. The {testName} token represents the sanitized test title, including parent describe titles and excluding the test file name. Relative template paths resolve from the configuration directory.
Other available tokens include {testFilePath}, {testFileDir}, {testFileName}, {testFileBaseName}, {testDir}, {snapshotDir}, {projectName} and {platform}. A single character immediately before a token can be made conditional on the token being present, which is useful when optional values might otherwise leave stray separators in a path.
- Use an explicit assertion filename for a one-off semantic name.
- Use
snapshotPathTemplatewhen the test title or another template value should shape paths consistently across tests.
Resolve the configured path in code
If a test or helper needs to know where Playwright expects a screenshot baseline, use testInfo.snapshotPath() with the screenshot kind:
Free tools Windows power users keep installed
One-click scans. No signup required.
const expectedScreenshot = test.info().snapshotPath(
'checkout-totals.png',
{ kind: 'screenshot' },
);The screenshot kind uses the configured screenshot path template. The kind option was added in Playwright v1.53; check the version installed in your project if this option is unavailable.
Use the screenshot assertion for visual comparisons
For page visual comparisons in the Playwright Test runner, use await expect(page).toHaveScreenshot(). It waits until two consecutive screenshots match, then compares the last screenshot with the expected baseline. toMatchSnapshot() is a separate assertion for strings or buffers. Although a screenshot buffer can be passed to it with a name, Playwright’s API guidance points to toHaveScreenshot() for screenshot comparisons.
Generate and maintain stable baselines
- Run the test the first time to create its reference screenshot.
- Review the generated baseline and keep the approved reference in version control.
- When a visual change is intentional, review the new output and update approved baselines with
npx playwright test --update-snapshots.
Screenshot rendering can differ with the host operating system, browser version, settings, hardware, power source and headless mode. Generate and compare baselines in a consistent environment. If content changes unpredictably between runs, Playwright’s documentation describes using stylePath to hide or filter volatile elements while capturing the screenshot.
Troubleshoot naming and comparison problems
- The snapshot does not include the test title. An explicit argument such as
checkout-totals.pngnames the assertion, but does not automatically add the title. ConfiguresnapshotPathTemplateand include{testName}in the template. - The path contains the assertion name but not its extension in
{arg}. That is expected:{arg}omits the extension, while{ext}supplies it. Include both tokens if the template should preserve the full filename. - A configured path is not where you expected. Check the template tokens and remember that relative template paths resolve from the configuration directory. Use
test.info().snapshotPath(name, { kind: 'screenshot' })to inspect the resolved screenshot path. - The screenshot assertion or path option is unavailable. The official rolling documentation lists
toHaveScreenshot(name)as added in v1.23,snapshotPathTemplatein v1.28 and theTestInfo.snapshotPathkindoption in v1.53. Check the installed Playwright version before relying on an option. - A baseline differs across machines or runs. Keep browser and rendering environments consistent, and use
stylePathto filter volatile content when appropriate. Review changes before updating committed baselines. - You are using
toMatchSnapshot()for a page screenshot. UsetoHaveScreenshot()for page visual assertions in Playwright Test;toMatchSnapshot()is intended for strings or buffers.
Or skip the browser setup
If you need an image capture of a live webpage outside a Playwright visual-baseline test, ScreenshotNeo offers a screenshot API. It is not a replacement for Playwright’s named baseline assertions or visual regression workflow. A single GET request can return an image or PDF; see the ScreenshotNeo API documentation.
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 matchQuick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups and chat widgets before the capture; bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.
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.
