What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
In Playwright, “snapshot” can mean a visual screenshot baseline, a saved text or binary value, an accessible-structure template, or state captured in a trace. They are different representations with different comparison rules. Choose based on what you need to verify: pixels, a value, accessibility structure, or debugging context.
What are Playwright snapshots?
A Playwright snapshot is a saved representation of something observed during a test or browser session, used for comparison or debugging. The word does not identify one universal file format. A screenshot snapshot records rendered pixels; a generic snapshot records a value; an ARIA snapshot describes accessible structure; and trace snapshots preserve context from actions for later investigation.
That distinction matters when a test fails. A changed screenshot may reflect rendering differences even when the page’s meaning is unchanged. A changed ARIA snapshot may indicate a role, name, or hierarchy change without any pixel comparison. A trace capture helps explain what happened during a run, but is not itself an assertion baseline.
What format does Playwright use for snapshots?
| Kind | What it represents | Format or storage | Best suited to |
|---|---|---|---|
| Visual screenshot | Rendered page or element pixels | PNG by default; lossless WebP when selected by extension | Visual regression checks |
| Generic value | Text or arbitrary binary content | Named snapshot file; Playwright Test detects content type and uses an appropriate comparison algorithm | Comparing a value rather than a rendered page |
| ARIA | Accessible roles, names, attributes, text, and hierarchy | YAML-like tree; a separately stored file commonly ends in .aria.yml |
Checking accessible structure |
| Trace snapshot | DOM, ARIA, or screen state associated with actions | Included in trace data according to tracing options | Debugging a recorded run |
Visual screenshot snapshots: compare rendered pixels
Screenshot assertions are part of Playwright Test. A screenshot assertion waits until two consecutive page screenshots produce the same result, then compares the last image with its expected image. PNG is the default. Naming the screenshot with a .webp extension selects WebP, which Playwright documentation describes as lossless.
#1 Best Overall
Use this type when the result you care about is appearance: layout, typography, colors, spacing, or a particular visual state. A screenshot can cover a page or an element, depending on the assertion being used. The stored baseline is an image, not a semantic description of the page.
Why visual baselines can change between runs
Rendered images can vary with the host operating system, browser version, browser settings, hardware, power source, and headless mode. A baseline created on one machine may therefore differ from a run on another, even when the application code has not changed. Generate and compare visual baselines in a consistent environment, ideally the same environment used by the test run.
When a visual change is intentional, review the proposed image difference and update the expected baseline deliberately. Playwright Test documents --update-snapshots as the option for updating expected screenshots. Treat an update as a code change: inspect it before committing it, rather than accepting every changed image automatically.
Generic value snapshots: compare text or binary data
toMatchSnapshot(snapshotName) is not limited to images. It can compare text or arbitrary binary data. Playwright Test detects the content type and applies a suitable comparison method, so this approach is useful when the expected result is a serialized or otherwise saved value rather than the page as it looks.
For example, a test can compare a string against a named snapshot:
import { test, expect } from '@playwright/test';
test('matches a text value', async () => {
const message = 'Account settings saved';
expect(message).toMatchSnapshot('saved-message.txt');
});Playwright Test’s documented example places snapshots alongside the test in a separate directory named after the test file with -snapshots appended. Commit these expected files to version control and review their diffs. This makes changes to the expected value visible alongside the test that depends on it.
ARIA snapshots: compare accessible structure
An ARIA snapshot represents accessible content as a YAML-like tree. Nodes can express roles, accessible names, text, and attributes such as checked, disabled, expanded, invalid, level, pressed, or selected. It is a structural representation, not a screenshot and not a full dump of every DOM detail.
toMatchAriaSnapshot() compares the accessible structure with a template. Matching is case-sensitive and order-sensitive, while whitespace is collapsed. Consequently, a change in accessible name capitalization or the order of elements can matter. A template can omit names or attributes that are not relevant to the test, allowing a partial structural match when dynamic details should not be fixed into the expectation.
Recommended Free Tools
An ARIA snapshot can be embedded in an assertion or stored separately with a name ending in .aria.yml. By default, snapshots from a test file go in its corresponding -snapshots directory. Playwright documentation notes that ARIA snapshots should be the same across browsers, so one snapshot is saved for multiple browsers unless path configuration changes that behavior.
Trace snapshots: debugging context, not a baseline
Playwright tracing can include DOM snapshots and network activity, ARIA snapshots, or screenshots associated with actions. In the tracing options, snapshots: true is documented as a shortcut for DOM snapshots. These captures help reconstruct what was happening during a run and investigate failures.
Do not treat a trace capture as interchangeable with a screenshot or value assertion. A trace is a debugging record whose contents depend on the tracing options; a test baseline is an expected value against which the test compares. Use each for its own purpose.
Where are Playwright snapshots stored?
By default, snapshot files are associated with the test file in a corresponding -snapshots directory. The exact location can be configured. In code, testInfo.snapshotPath() resolves a path from a name and an optional kind: screenshot, aria, or snapshot.
Configuration supports snapshotPathTemplate and assertion-specific path templates. The documented template tokens include {arg}, {ext}, {platform}, {projectName}, {snapshotDir}, {testDir}, and test-file path or name tokens. Templates are useful when a project needs to organize snapshots by project, platform, test location, or type.
The older snapshotDir option is marked discouraged in the TestConfig API; the documented recommendation is to use snapshot path templates instead. Because Playwright API details can change between versions, check the documentation for the version installed in your project, especially when changing path configuration.
How do I update Playwright snapshots?
- Run the relevant Playwright Test test in the same browser and environment used to create its expected snapshots.
- Inspect the failure and determine which kind of snapshot changed: image, generic value, or ARIA structure. A trace can help investigate the run, but it is not the expected baseline.
- If the application change is intentional, rerun the test with
--update-snapshotsto update expected snapshots. - Review the updated files in the test’s snapshot directory. For images, inspect the actual visual difference; for text, binary, or ARIA files, review the changed content and ensure it is expected.
- Commit the test and its reviewed expected files together so the baseline change remains auditable.
Do not update baselines merely to make a failing test pass. First rule out rendering-environment differences, unintended accessibility changes, and accidental changes to the actual result.
Choose the snapshot type that matches the question
- “Did the page look right?” Use a screenshot baseline. Keep the rendering environment consistent.
- “Did this text or binary value match?” Use a generic
toMatchSnapshotassertion. - “Did the accessible roles, names, and hierarchy match?” Use an ARIA snapshot, keeping case and order sensitivity in mind.
- “What state did the browser have during these actions?” Capture a trace with the relevant snapshot options enabled.
Common problems and fixes
Screenshot baselines differ only on another machine
Check the host operating system, browser version and settings, hardware, power source, and headless mode. Those factors can change rendering. Create and check visual baselines in the same environment rather than normalizing away unexplained differences.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →An ARIA snapshot fails after a seemingly small text edit
ARIA matching is case-sensitive, and accessible names are part of the represented structure. Check the name’s exact text and whether whitespace or an element’s role changed. If a name or attribute is deliberately irrelevant to the test, use a partial template that omits it rather than pinning a volatile detail.
ARIA elements are present but in a different order
ARIA snapshot matching is order-sensitive. Determine whether the order change reflects a meaningful interaction or content change. If order is not part of the behavior being tested, shape the expected template to focus on the structure that matters.
A generic snapshot is being mistaken for a screenshot
toMatchSnapshot can store text or arbitrary binary data as well as image content. Check the assertion input and the named file’s content type before diagnosing a failure as a visual-regression problem.
Snapshot files are appearing in an unexpected directory
Check the configured snapshot path template and any assertion-specific template. Use testInfo.snapshotPath() with the appropriate kind to resolve the intended path. If a project still relies on snapshotDir, consult the version-specific TestConfig guidance and consider the documented path-template approach.
A trace is available, but it does not update the expected image
Trace snapshots are debugging captures, not the stored expectation for a screenshot assertion. Update the assertion baseline through the test’s snapshot update workflow after confirming that the visual change is intentional.
Or skip the browser setup
Playwright snapshots are useful when you need a test-controlled baseline or accessible-structure assertion. For a one-off website capture or an API-driven screenshot, ScreenshotNeo is a separate option—not a replacement for Playwright assertions. One GET request returns an image or PDF:
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. It removes cookie banners, popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free.
For a quick comparison of what this service does, visit ScreenshotNeo.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsQuick 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.
