Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Configure Playwright’s ARIA snapshot paths and matching behavior in playwright.config.ts; the YAML is the generated accessibility-tree baseline, not the configuration file itself. Use the ARIA-specific expect.toMatchAriaSnapshot.pathTemplate to choose where those files go, set a default children matching mode, and run Playwright with --update-snapshots to create or refresh baselines deliberately.
What Playwright snapshot YAML is
An ARIA snapshot is a YAML representation of the accessibility tree for a page or locator. Playwright’s toMatchAriaSnapshot assertion compares the current tree with that expected representation. The Playwright guide describes each accessible element in the tree as a YAML node. The test configuration itself remains JavaScript or TypeScript, commonly in playwright.config.ts; YAML is the snapshot data the tests read and compare.
Use ARIA snapshots when you want an assertion about accessible roles, names, and relationships, rather than a pixel-by-pixel image comparison. The guide also documents page.ariaSnapshot() and locator.ariaSnapshot() for obtaining an ARIA representation while a test runs. The assertion is usually the right choice for a maintained expected baseline; the methods are useful when you need to inspect or use the current representation in test code.
Configure the ARIA snapshot directory
Set the default location in your Playwright project configuration. This example keeps ARIA files under a dedicated __aria__ directory while retaining the test file path and the argument supplied to the assertion:
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests',
snapshotPathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
expect: {
toMatchAriaSnapshot: {
pathTemplate: '{testDir}/__aria__/{testFilePath}/{arg}{ext}',
children: 'contain',
},
},
});In this configuration, the top-level snapshotPathTemplate is the shared template for snapshot assertions. The nested expect.toMatchAriaSnapshot.pathTemplate is specific to ARIA snapshot assertions, so you can keep those baselines apart from screenshot and other snapshot files. If you do not need separate ARIA organization, the shared template is available instead.
The API reference documents snapshotPathTemplate as controlling locations for toHaveScreenshot(), toMatchAriaSnapshot(), and toMatchSnapshot(). It was added in Playwright v1.28. Confirm that the installed version supports the options you use; snapshot configuration is version-sensitive.
Choose path tokens to avoid collisions
Templates can use {testDir}, {snapshotDir}, {testFilePath}, {testFileDir}, {testFileName}, {testFileBaseName}, {testName}, {arg}, {ext}, {projectName}, and {platform}. A separator immediately before an optional token is included only when that token has a value, which helps avoid stray separators in paths.
For a straightforward single-project setup, {testFilePath} plus {arg} makes the path reflect the source test and the snapshot name passed to the assertion. Add {projectName} when the same test runs in multiple configured projects, and {platform} when platform-specific baselines need distinct locations. Choose a template that stays deterministic and gives each intended baseline a unique path.
Name a snapshot and find its file
Pass a filename to the assertion to identify the baseline:
await expect(page.getByRole('main')).toMatchAriaSnapshot('main.aria.yml');The .aria.yml suffix makes the file’s purpose visible in the repository. The configured template determines its directory and how the filename argument and extension map into the final path. For code that needs to determine the location rather than construct it manually, use testInfo.snapshotPath('main.aria.yml', { kind: 'aria' }).
Keep the snapshot name stable and specific to the asserted region. If two assertions resolve to the same path, they cannot maintain independent expected values. When adding a new assertion, check the resolved path and the generated file in version control so the baseline is stored where the team expects.
Choose how child elements are matched
Set a default at expect.toMatchAriaSnapshot.children. The available modes express different strictness:
| Mode | Effect | Typical use |
|---|---|---|
contain |
Required children may appear within a larger tree. | Use when the assertion should tolerate additional children while still requiring the listed ones. |
equal |
Applies the documented equal-children behavior. | Use when matching should be stricter than containment; confirm the expected tree shape for your installed Playwright version. |
deep-equal |
Requires recursive equality. | Use when descendants at each level must match the expected structure. |
These modes are not interchangeable: a permissive containment check can allow extra content, while recursive equality makes structural changes more likely to fail the test. Select the least permissive mode that genuinely protects the behavior the test is intended to verify. An individual snapshot can override the configured default by specifying a top-level /children property in that ARIA snapshot.
Keep baselines separate across browser projects
When a test runs in more than one browser project, a shared snapshot path can cause one project’s update to replace another project’s expected file. Playwright’s snapshot guide notes that screenshots can vary across browsers and platforms because rendering and fonts differ. Separating paths by project and platform makes ownership explicit and avoids accidental baseline collisions.
For example, change the ARIA-specific path template to:
pathTemplate: '{testDir}/__aria__/{projectName}/{platform}/{testFilePath}/{arg}{ext}'This stores each project/platform combination in its own branch of the directory tree. Use the tokens only where they solve a real collision or make review clearer; a single-project suite does not need unnecessary directory depth.
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 matchRank #4
Create or update ARIA YAML baselines
Run the test command with snapshot updates enabled:
npx playwright test --update-snapshots
# shorthand:
npx playwright test -uThe ARIA snapshot guide states that matching snapshots are not updated by this command unless the selected update mode requires it. The configured updateSnapshots mode determines how broadly Playwright writes baselines:
| Mode | Behavior | Use when |
|---|---|---|
missing |
Default. Creates missing snapshots; does not replace existing mismatches broadly. | For cautious baseline creation during normal development. |
changed |
Updates mismatches and creates missing files. | When intentionally accepting the changes exercised by the selected test run. |
all |
Updates all executed snapshots. | For a deliberate broad refresh after reviewing the impact. |
none |
Disables updates. | When the run must report mismatches without writing baselines. |
Prefer the narrowest update behavior that fits the task. Run the intended tests, inspect the YAML diff, and commit changed baselines alongside the application or test change that explains them. A passing update command means files were written according to the chosen mode; it does not establish that every new expected tree is correct.
Inline snapshots and older path settings
Inline snapshot write strategy
If a snapshot is embedded in source rather than stored in a separate YAML file, updateSourceMethod controls how Playwright writes updates. The documented options are patch, 3way, and overwrite. patch is the default and creates a unified diff; 3way writes merge-conflict markers; overwrite replaces the source snapshot value. The API reference records this option as added in Playwright v1.50, so older installations may not support it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
Why not start with snapshotDir?
snapshotDir is the older base-directory setting and is marked discouraged in the current API reference, which recommends snapshotPathTemplate for configuring snapshot paths. Use the newer template for a new layout. Keep snapshotDir only when maintaining a compatibility-sensitive existing convention, and verify behavior against the API documentation for the Playwright version actually installed.
Troubleshoot common configuration problems
- The YAML appears in an unexpected directory. Check whether the assertion-specific
pathTemplateis set; it controls ARIA snapshots separately from the sharedsnapshotPathTemplate. Then check the substituted tokens and the filename argument. - Two browser projects overwrite or disagree on one file. Include
{projectName}in the path, and add{platform}if platform-specific baselines also need separation. Ensure the project names resolve to distinct paths. - The test fails after an expected UI change. Review the actual accessible tree and decide whether the change is intended before running an update command. Choose an update mode that matches the scope you mean to refresh, then inspect the YAML diff.
- An update run does not rewrite a mismatch. Check the configured
updateSnapshotsmode. The default ismissing; usechangedwhen the intention is to update mismatches, ornoneif updates are disabled. - The assertion is too permissive or too strict. Revisit the default
childrenmode and any snapshot-level/childrenoverride. Use containment for allowed additions, and a stricter equality mode only where exact structure is part of the test contract. - A configuration option is rejected or ignored. Check the installed Playwright version and the API reference’s version notes. In particular,
snapshotPathTemplaterequires v1.28 or later andupdateSourceMethodv1.50 or later.
Operational practices for reliable snapshot tests
- Keep ARIA baselines under a distinct directory when that makes review and ownership clearer.
- Use project and platform tokens only when the test matrix needs independent baselines; avoid shared paths that let different projects write the same expected file.
- Make updates intentional. Broad refreshes can obscure the change that caused a baseline difference, so review updates in the same diff as the test or interface change.
- Treat a snapshot mismatch as a prompt to inspect the accessibility tree, not as an instruction to accept every generated change.
- Keep the Playwright package version consistent across contributors and CI, so path handling and supported configuration options do not vary unexpectedly.
ARIA snapshots are text baselines, so they avoid image-file review for these assertions; they still have a maintenance cost when accessible names or structure intentionally change. Project-specific output can create more files, but reduces overwrites and keeps browser-specific changes reviewable.
Or skip the browser setup
ScreenshotNeo is a separate website screenshot API, not a Playwright ARIA snapshot generator: it returns rendered screenshots or PDFs, not YAML accessibility-tree baselines. If your task is to capture a visual page image rather than configure an ARIA assertion, one GET request can do that:
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. Cookie and consent banners are accepted like a visitor and removed, as are more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does an ARIA snapshot replace an accessibility audit?
No. It gives a test a repeatable representation of an accessibility tree; it does not by itself establish that an interface is usable or conforms to every accessibility requirement.
Can I use an ARIA snapshot with a page section instead of the whole page?
Yes. The assertion can target a locator, such as a landmark or component, so the baseline can focus on the part of the tree relevant to that test.
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.
Recommended Free Tools
