English · Java
Appearance
English · Java
Appearance
import LiteYouTube from '@site/src/components/LiteYouTube';
With Playwright's Snapshot testing you can assert the accessibility tree of a page against a predefined snapshot template.
page.navigate("https://playwright.dev/");
assertThat(page).matchesAriaSnapshot("""
- banner:
- heading /Playwright enables reliable end-to-end/ [level=1]
- link "Get started":
- /url: /docs/intro
- link "Star microsoft/playwright on GitHub":
- /url: https://github.com/microsoft/playwright
- link /[\\d]+k\\+ stargazers on GitHub/
""");Snapshot testing and assertion testing serve different purposes in test automation:
Assertion testing is a targeted approach where you assert specific values or conditions about elements or components. For instance, with Playwright, locatorAssertions.hasText() verifies that an element contains the expected text, and locatorAssertions.hasValue() confirms that an input field has the expected value. Assertion tests are specific and generally check the current state of an element or property against an expected, predefined state. They work well for predictable, single-value checks but are limited in scope when testing the broader structure or variations.
Advantages
Disadvantages
Snapshot testing captures a “snapshot” or representation of the entire state of an element, component, or data at a given moment, which is then saved for future comparisons. When re-running tests, the current state is compared to the snapshot, and if there are differences, the test fails. This approach is especially useful for complex or dynamic structures, where manually asserting each detail would be too time-consuming. Snapshot testing is broader and more holistic than assertion testing, allowing you to track more complex changes over time.
Advantages
Disadvantages
By combining snapshot testing for broad, structural checks and assertion testing for specific functionality, you can achieve a well-rounded testing strategy.
In Playwright, aria snapshots provide a YAML representation of the accessibility tree of a page. These snapshots can be stored and compared later to verify if the page structure remains consistent or meets defined expectations. A template is a constraint, not necessarily a complete serialization of the accessibility tree.
The YAML format describes the hierarchical structure of accessible elements on the page, detailing roles, attributes, values, and text content. The structure follows a tree-like syntax, where each node represents an accessible element, and indentation indicates nested elements.
Each accessible element in the tree is represented as a YAML node:
- role "name" [attribute=value]heading, list, listitem, button)./patterns/ are used for regular expression.checked, disabled, expanded, invalid, level, pressed, required, or selected. Attributes can constrain a specific value, such as [pressed=mixed].These values are derived from ARIA attributes or calculated based on HTML semantics. To inspect the accessibility tree structure of a page, use the Chrome DevTools Accessibility Tab.
The pageAssertions.matchesAriaSnapshot() assertion method in Playwright compares the accessible structure of the page with a predefined aria snapshot template, helping validate the page's state against testing requirements. You can also use locatorAssertions.matchesAriaSnapshot() to match a specific part of the page.
For the following DOM:
<h1>title</h1>You can match it using the following snapshot template:
assertThat(page).matchesAriaSnapshot("""
- heading "title"
""");When matching, the snapshot template is compared to the current accessibility tree of the page:
You can perform partial matches on nodes by omitting attributes or accessible names, enabling verification of specific parts of the accessibility tree without requiring exact matches. This flexibility is helpful for dynamic or irrelevant attributes.
<button>Submit</button>- buttonIn this example, the button role is matched, but the accessible name ("Submit") is not specified, allowing the test to pass regardless of the button's label.
For elements with ARIA attributes like checked or disabled, omitting these attributes allows partial matching, focusing solely on role and hierarchy.
<input type="checkbox" checked>- checkboxIn this partial match, the checked attribute is ignored, so the test will pass regardless of the checkbox state.
Similarly, you can partially match children in lists or groups by omitting specific list items or nested elements.
<ul>
<li>Feature A</li>
<li>Feature B</li>
<li>Feature C</li>
</ul>- list:
- listitem: Feature BPartial matches let you create flexible snapshot tests that verify essential page structure without enforcing specific content or attributes.
By default, a template containing the subset of children will be matched:
<ul>
<li>Feature A</li>
<li>Feature B</li>
<li>Feature C</li>
</ul>- list:
- listitem: Feature BThe /children property controls children for the node where it appears:
contain (default): Matches if all specified children are present in order.equal: Matches if direct children exactly match the specified list in order.deep-equal: Matches if children and nested children exactly match the specified list in order.With no expected child entries, contain allows any children, while equal and deep-equal require none. Add /children: contain to a nested node to override inherited deep-equal matching and allow extra children there.
<ul>
<li>Feature A</li>
<li>Feature B</li>
<li>Feature C</li>
</ul>Following snapshot will fail due to Feature C not being in the template:
- list:
- /children: equal
- listitem: Feature A
- listitem: Feature Bchildren mode globally Instead of adding a /children property to every snapshot, you can set the default children matching mode for all toMatchAriaSnapshot calls in the configuration file:
Individual snapshots can still override the global setting by including an explicit /children property in the template.
Regular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text can support regex patterns.
<h1>Issues 12</h1>- heading /Issues \d+/Creating aria snapshots in Playwright helps ensure and maintain your application's structure. You can generate snapshots in various ways depending on your testing setup and workflow.
If you're using Playwright's Code Generator, generating aria snapshots is streamlined with its interactive interface:
page.ariaSnapshot() and locator.ariaSnapshot() Methods page.ariaSnapshot() and locator.ariaSnapshot() allow you to programmatically create a YAML representation of accessible elements within a locator's scope, especially helpful for generating snapshots dynamically during test execution.
Example:
String snapshot = page.ariaSnapshot();
System.out.println(snapshot);This command outputs the aria snapshot within the specified locator's scope in YAML format, which you can validate or store as needed.
Headings can include a level attribute indicating their heading level.
<h1>Title</h1>
<h2>Subtitle</h2>- heading "Title" [level=1]
- heading "Subtitle" [level=2]Standalone or descriptive text elements appear as text nodes.
<div>Sample accessible name</div>- text: Sample accessible nameMultiline text, such as paragraphs, is normalized in the aria snapshot.
<p>Line 1<br>Line 2</p>- paragraph: Line 1 Line 2Links display their text or composed content from pseudo-elements. The link’s destination may be matched using the /url property.
<a href="#more-info">Read more about Accessibility</a>- link "Read more about Accessibility":
- /url: "#more-info"The value of /url may also be a regular expression:
<a href="https://www.youtube.com/channel/UC46Zj8pDH5tDosqm1gd7WTg">YouTube channel</a>- link:
- /url: /https://www.youtube.com/channel/.*/Input elements of type text show their value attribute content.
<input type="text" value="Enter your name">- textbox: Enter your nameOrdered and unordered lists include their list items.
<ul aria-label="Main Features">
<li>Feature 1</li>
<li>Feature 2</li>
</ul>- list "Main Features":
- listitem: Feature 1
- listitem: Feature 2Groups capture nested elements, such as <details> elements with summary content.
<details>
<summary>Summary</summary>
<p>Detail content here</p>
</details>- group: SummaryCommonly used ARIA attributes, like checked, disabled, expanded, invalid, level, pressed, required, and selected, represent control states.
checked attribute <input type="checkbox" checked>- checkbox [checked]pressed attribute <button aria-pressed="true">Toggle</button>- button "Toggle" [pressed=true]aria-invalid attribute The aria-invalid value is surfaced directly. A value of true renders as [invalid], while grammar and spelling render as [invalid=grammar] and [invalid=spelling]. A false value is omitted.
<input type="text" aria-label="Email" aria-invalid="true" value="not-an-email">- textbox "Email" [invalid]: not-an-email<input type="text" aria-label="Bio" aria-invalid="spelling">- textbox "Bio" [invalid=spelling]required attribute On roles that support aria-required, native required attributes on inputs, textareas and selects, or aria-required="true", render as [required]. A native required attribute takes precedence over aria-required="false". A false value is omitted from snapshots, but can be asserted with [required=false].
<input type="email" aria-label="Email" required>- textbox "Email" [required]