Playwright screenshot snapshot path: how to configure it

To configure where Playwright stores screenshot snapshots, set snapshotPathTemplate in your Playwright Test config for a shared template across snapshot types. To customize only screenshot assertions, set expect.toHaveScreenshot.pathTemplate. To name one screenshot assertion, pass a filename or path segments to toHaveScreenshot(). Relative templates resolve from the configuration directory.

Choose the narrowest scope that matches your goal: global layout, screenshot-only layout, or a one-off name. Keep assertion-provided paths inside the snapshot directory for that test file.

1. Set a global snapshot path template

snapshotPathTemplate controls paths for toHaveScreenshot(), toMatchAriaSnapshot(), and toMatchSnapshot(). For example, this config places snapshots in a __screenshots__ tree organized by test file:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',
});

Save this in your Playwright config file, such as playwright.config.ts. A relative template path is resolved from the config directory, not from the shell’s current working directory. Forward slashes work as path separators across platforms.

2. Configure screenshot assertions only

If you want a different layout for screenshot baselines while leaving other snapshots on their existing path convention, configure the screenshot assertion under expect:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
    },
  },
});

The optional {/projectName} component adds the project directory when a project has a name and omits it when the project is unnamed. That keeps paths tidy while allowing named projects to have separate baselines.

snapshotPathTemplate was added in Playwright v1.28. Check the API documentation for the version installed in your project, especially if a config option is rejected or a token does not behave as expected.

3. Understand template tokens and path organization

A template is assembled from literal path segments and supported tokens. Commonly useful tokens include:

Token	What it contributes
{arg}	The relative snapshot path without its extension, derived from the assertion argument. If no argument is supplied, Playwright generates a snapshot name.
{ext}	The snapshot extension, including the leading dot.
{platform}	The Node.js process.platform value.
{projectName}	The filesystem-sanitized project name, or empty for an unnamed project.
{snapshotDir}	The project’s snapshot directory.
{testDir}	The configured test directory.
{testFileDir}	The test file’s directory relative to testDir.
{testFileBaseName}	The test file basename without its extension.
{testFileName}	The test file name.
{testFilePath}	The test file path relative to testDir.
{testName}	The sanitized test title, including parent describe titles but excluding the file name.

Use {arg} and {ext} when assertion arguments should determine the baseline name and extension. Include {projectName} or {platform} if you need separate baselines for projects or operating systems. Browser and platform rendering can differ, so sharing one baseline across environments should be an intentional choice.

A single character immediately before a token is treated as optional along with that token when its value is empty. For example, {/projectName} avoids an empty path component and dangling separator for an unnamed project.

4. Name an individual screenshot assertion

Give toHaveScreenshot() a filename when only one assertion needs a clear name:

import { test, expect } from '@playwright/test';

test('landing page', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveScreenshot('landing.png');
});

You can provide path segments as an array:

await expect(page).toHaveScreenshot(['relative', 'path', 'to', 'snapshot.png']);

The supplied path must remain within the snapshot directory for that test file. An attempt to escape that directory throws an error. Prefer stable, descriptive names so test intent and baseline changes are easy to review.

5. Check the resolved path and update baselines

When a baseline appears in an unexpected directory, ask Playwright Test for the resolved path with test.info().snapshotPath(). Pass { kind: 'screenshot' } to resolve using the screenshot path template; this option was added in v1.53.

import { test, expect } from '@playwright/test';

test('landing page', async ({ page }, testInfo) => {
  await page.goto('https://example.com');
  console.log(testInfo.snapshotPath('landing.png', { kind: 'screenshot' }));
  await expect(page).toHaveScreenshot('landing.png');
});

When the expected screenshot should change, regenerate the baselines with:

npx playwright test --update-snapshots

Review the resulting image changes and commit expected snapshot files with the tests. Treat baseline updates as reviewable test artifacts rather than automatically accepting every generated difference.

6. Choose an image format and scope

Screenshot assertions use PNG by default. A .webp filename selects WebP, which Playwright documents as lossless. Screenshot assertions are part of the Playwright Test runner; this configuration does not apply to arbitrary browser automation outside that runner.

Need	Use	Scope
Reorganize all snapshot types	snapshotPathTemplate	Global
Reorganize screenshot baselines only	expect.toHaveScreenshot.pathTemplate	Screenshot assertions
Give one assertion a readable name	Filename or path segments in toHaveScreenshot()	One assertion

Include the project token when projects need independent baselines. If you deliberately want projects to share image baselines, omit it only after considering whether their browser and platform rendering should match.

7. Troubleshoot path problems

Symptom	Likely cause	Fix
Config rejects snapshotPathTemplate	The installed Playwright version predates support, or the config is not being read by Playwright Test.	Check the installed version and config file; the option was added in v1.28.
Snapshots appear under an unexpected directory	A relative template is resolved from the config directory, or a token expands to a path different from what you assumed.	Resolve the full path with test.info().snapshotPath(); use { kind: 'screenshot' } for screenshot assertions (v1.53+).
An unnamed project creates an awkward empty directory	The template has a separator around an empty {projectName}.	Use the optional token prefix form {/projectName}.
A named screenshot path throws	The supplied path attempts to leave the test file’s snapshot directory.	Keep the filename or array path segments relative and inside that directory.
Different projects overwrite or disagree on baselines	The path template does not separate projects, or the environments render differently.	Add {projectName} and, if relevant, {platform}; compare the visual-comparison needs before sharing baselines.
A baseline has the wrong extension	The assertion name or template extension does not match the intended format.	Use {ext} in the template and choose .png or .webp in the assertion name as needed.
Baseline update creates many changes	The update command regenerates expected snapshots for the run.	Inspect the changed images and limit the test run to the relevant tests before updating when appropriate.

8. Performance, reliability, and cost

Path configuration changes where Playwright Test writes and looks for baselines; it does not make page rendering or screenshot capture faster. Organizing paths by test file, project, or platform can make parallel test results easier to distinguish and prevent accidental baseline sharing.

For reliable comparisons, keep the execution environment consistent where practical and separate baselines for projects that render differently. Commit the intended baseline files and review updates. No separate screenshot service is needed to configure Playwright’s own snapshot paths.

Or skip the browser setup

If your goal is to capture a website image rather than maintain a Playwright visual baseline, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. The API accepts screenshot options including full-page capture, element selection, viewport and device settings, and wait conditions. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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}`);

• Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status.
• An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
• The Free plan includes 1,000 screenshots 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.

FAQ

Does this change Playwright’s actual test output directory?

No. These settings control expected snapshot paths used by snapshot assertions, not the test runner’s general output directory.

Can multiple projects share screenshot baselines?

Yes, if the path template omits the project token. Decide whether sharing is appropriate for the browsers and platforms in those projects.

Can I use this config outside Playwright Test?

The assertion methods and their path configuration belong to Playwright Test. For other browser automation workflows, use that workflow’s own screenshot and file-writing APIs.

Official references

• Playwright TestConfig: snapshotPathTemplate
• Playwright visual comparisons and snapshots guide
• Playwright TestInfo: snapshotPath