Skip to main content

Aria 快照

概述​

¥Overview

在 Playwright 中，aria 快照提供页面可访问性树的 YAML 表示。这些快照可以存储并在以后进行比较，以验证页面结构是否保持一致或是否符合定义的期望。

¥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.

YAML 格式描述了页面上可访问元素的层次结构，详细说明了角色、属性、值和文本内容。结构遵循树状语法，其中每个节点代表一个可访问元素，缩进表示嵌套元素。

¥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.

以下是 playwright.dev 主页的 aria 快照的一个简单示例：

¥Following is a simple example of an aria snapshot for the playwright.dev homepage:

- banner:
  - heading /Playwright enables reliable/ [level=1]
  - link "Get started"
  - link "Star microsoft/playwright on GitHub"
- main:
  - img "Browsers (Chromium, Firefox, WebKit)"
  - heading "Any browser • Any platform • One API"

树中的每个可访问元素都表示为一个 YAML 节点：

¥Each accessible element in the tree is represented as a YAML node:

- role "name" [attribute=value]

  • 角色：指定元素的 ARIA 或 HTML 角色（例如，heading、list、listitem、button）。

    ¥role: Specifies the ARIA or HTML role of the element (e.g., heading, list, listitem, button).

  • "name"：元素的可访问名称。带引号的字符串表示精确值，/patterns/ 用于正则表达式。

    ¥"name": Accessible name of the element. Quoted strings indicate exact values, /patterns/ are used for regular expression.

  • [attribute=value]：方括号中的属性和值表示特定的 ARIA 属性，例如 checked、disabled、expanded、level、pressed 或 selected。

    ¥[attribute=value]: Attributes and values, in square brackets, represent specific ARIA attributes, such as checked, disabled, expanded, level, pressed, or selected.

这些值来自 ARIA 属性或基于 HTML 语义计算。要检查页面的可访问性树结构，请使用 Chrome DevTools 可访问性窗格。

¥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 Pane.

快照匹配​

¥Snapshot matching

Playwright 中的 expect(locator).toMatchAriaSnapshot() 断言方法将定位器范围的可访问结构与预定义的 aria 快照模板进行比较，帮助根据测试要求验证页面的状态。

¥The expect(locator).toMatchAriaSnapshot() assertion method in Playwright compares the accessible structure of the locator scope with a predefined aria snapshot template, helping validate the page's state against testing requirements.

对于以下 DOM：

¥For the following DOM:

<h1>title</h1>

你可以使用以下快照模板进行匹配：

¥You can match it using the following snapshot template:

await expect(page.locator('body')).toMatchAriaSnapshot(`
  - heading "title"
`);

匹配时，会将快照模板与页面的当前可访问性树进行比较：

¥When matching, the snapshot template is compared to the current accessibility tree of the page:

  • 如果树结构与模板匹配，则测试通过；否则，它会失败，表明预期和实​​际可访问性状态不匹配。

    ¥If the tree structure matches the template, the test passes; otherwise, it fails, indicating a mismatch between expected and actual accessibility states.

  • 比较区分大小写并折叠空格，因此会忽略缩进和换行符。

    ¥The comparison is case-sensitive and collapses whitespace, so indentation and line breaks are ignored.

  • 比较区分顺序，这意味着快照模板中元素的顺序必须与页面可访问性树中的顺序匹配。

    ¥The comparison is order-sensitive, meaning the order of elements in the snapshot template must match the order in the page's accessibility tree.

部分匹配​

¥Partial matching

你可以通过省略属性或可访问名称对节点执行部分匹配，从而可以验证可访问性树的特定部分而无需精确匹配。这种灵活性对于动态或不相关的属性很有帮助。

¥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>

aria 快照

¥aria snapshot

- button

在此示例中，按钮角色已匹配，但未指定可访问名称 ("提交")，因此无论按钮的标签如何，测试都可以通过。

¥In 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.

对于具有 ARIA 属性（如 checked 或 disabled）的元素，省略这些属性允许部分匹配，仅关注角色和层次结构。

¥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>

用于部分匹配的 aria 快照

¥aria snapshot for partial match

- checkbox

在此部分匹配中，checked 属性被忽略，因此无论复选框状态如何，测试都将通过。

¥In 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>

用于部分匹配的 aria 快照

¥aria snapshot for partial match

- list
  - listitem: Feature B

部分匹配让你可以创建灵活的快照测试，以验证基本页面结构，而无需强制执行特定内容或属性。

¥Partial matches let you create flexible snapshot tests that verify essential page structure without enforcing specific content or attributes.

使用正则表达式匹配​

¥Matching with regular expressions

正则表达式允许灵活匹配具有动态或可变文本的元素。可访问的名称和文本可以支持正则表达式模式。

¥Regular expressions allow flexible matching for elements with dynamic or variable text. Accessible names and text can support regex patterns.

<h1>Issues 12</h1>

带有正则表达式的 aria 快照

¥aria snapshot with regular expression

- heading /Issues \d+/

生成快照​

¥Generating snapshots

在 Playwright 中创建 aria 快照有助于确保和维护应用的结构。你可以根据你的测试设置和工作流程以各种方式生成快照。

¥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.

1. 使用 Playwright 代码生成器生成快照​

¥ Generating snapshots with the Playwright code generator

如果你使用 Playwright 的 代码生成器，则其交互式界面简化了 aria 快照的生成：

¥If you’re using Playwright’s Code Generator, generating aria snapshots is streamlined with its interactive interface:

  • "断言快照" 操作：在代码生成器中，你可以使用 "断言快照" 操作自动为所选元素创建快照断言。这是捕获 aria 快照作为记录测试流程的一部分的快速方法。

    ¥"Assert snapshot" Action: In the code generator, you can use the "Assert snapshot" action to automatically create a snapshot assertion for the selected elements. This is a quick way to capture the aria snapshot as part of your recorded test flow.

  • "Aria 快照" 选项卡：代码生成器界面中的 "Aria 快照" 选项卡以可视化方式表示所选定位器的 aria 快照，让你可以探索、检查和验证元素角色、属性和可访问名称，以帮助创建和审查快照。

    ¥"Aria snapshot" Tab: The "Aria snapshot" tab within the code generator interface visually represents the aria snapshot for a selected locator, letting you explore, inspect, and verify element roles, attributes, and accessible names to aid snapshot creation and review.

2. 使用 @playwright/test 和 --update-snapshots 标志更新快照​

¥ Updating snapshots with @playwright/test and the --update-snapshots flag

使用 Playwright 测试运行器 (@playwright/test) 时，你可以通过使用 --update-snapshots 标志运行测试来自动更新快照：

¥When using the Playwright test runner (@playwright/test), you can automatically update snapshots by running tests with the --update-snapshots flag:

npx playwright test --update-snapshots

此命令重新生成断言的快照，包括 aria 快照，替换过时的快照。当应用结构更改需要新的快照作为基线时，它很有用。请注意，Playwright 将等待测试运行器配置中指定的最大预期超时，以确保在拍摄快照之前页面已稳定。如果测试在生成快照时超时，可能需要调整 --timeout。

¥This command regenerates snapshots for assertions, including aria snapshots, replacing outdated ones. It’s useful when application structure changes require new snapshots as a baseline. Note that Playwright will wait for the maximum expect timeout specified in the test runner configuration to ensure the page is settled before taking the snapshot. It might be necessary to adjust the --timeout if the test hits the timeout while generating snapshots.

用于快照生成的空模板​

¥Empty template for snapshot generation

在断言中传递一个空字符串作为模板会即时生成快照：

¥Passing an empty string as the template in an assertion generates a snapshot on-the-fly:

await expect(locator).toMatchAriaSnapshot('');

请注意，Playwright 将等待测试运行器配置中指定的最大预期超时，以确保在拍摄快照之前页面已稳定。如果测试在生成快照时超时，可能需要调整 --timeout。

¥Note that Playwright will wait for the maximum expect timeout specified in the test runner configuration to ensure the page is settled before taking the snapshot. It might be necessary to adjust the --timeout if the test hits the timeout while generating snapshots.

快照补丁文件​

¥Snapshot patch files

更新快照时，Playwright 会创建用于捕获差异的补丁文件。这些补丁文件可以进行审查、应用和提交到源代码控制，允许团队跟踪随时间的结构变化并确保更新与应用要求一致。

¥When updating snapshots, Playwright creates patch files that capture differences. These patch files can be reviewed, applied, and committed to source control, allowing teams to track structural changes over time and ensure updates are consistent with application requirements.

3. 使用 Locator.ariaSnapshot 方法​

¥ Using the Locator.ariaSnapshot method

locator.ariaSnapshot() 方法允许你以编程方式创建定位器范围内可访问元素的 YAML 表示，这对于在测试执行期间动态生成快照特别有用。

¥The locator.ariaSnapshot() method allows 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:

const snapshot = await page.locator('body').ariaSnapshot();
console.log(snapshot);

此命令以 YAML 格式输出指定定位器范围内的 aria 快照，你可以根据需要验证或存储它。

¥This command outputs the aria snapshot within the specified locator’s scope in YAML format, which you can validate or store as needed.

可访问性树示例​

¥Accessibility tree examples

具有级别属性的标题​

¥Headings with level attributes

标题可以包含指示其标题级别的 level 属性。

¥Headings can include a level attribute indicating their heading level.

<h1>Title</h1>
<h2>Subtitle</h2>

aria 快照

¥aria snapshot

- heading "Title" [level=1]
- heading "Subtitle" [level=2]

文本节点​

¥Text nodes

独立或描述性文本元素显示为文本节点。

¥Standalone or descriptive text elements appear as text nodes.

<div>Sample accessible name</div>

aria 快照

¥aria snapshot

- text: Sample accessible name

内联多行文本​

¥Inline multiline text

多行文本（例如段落）在 aria 快照中被规范化。

¥Multiline text, such as paragraphs, is normalized in the aria snapshot.

<p>Line 1<br>Line 2</p>

aria 快照

¥aria snapshot

- paragraph: Line 1 Line 2

¥Links

链接显示其文本或由伪元素组成的内容。

¥Links display their text or composed content from pseudo-elements.

<a href="#more-info">Read more about Accessibility</a>

aria 快照

¥aria snapshot

- link "Read more about Accessibility"

文本框​

¥Text boxes

类型为 text 的输入元素显示其 value 属性内容。

¥Input elements of type text show their value attribute content.

<input type="text" value="Enter your name">

aria 快照

¥aria snapshot

- textbox: Enter your name

带有项目的列表​

¥Lists with items

有序和无序列表包含其列表项。

¥Ordered and unordered lists include their list items.

<ul aria-label="Main Features">
  <li>Feature 1</li>
  <li>Feature 2</li>
</ul>

aria 快照

¥aria snapshot

- list "Main Features":
  - listitem: Feature 1
  - listitem: Feature 2

分组元素​

¥Grouped elements

组捕获嵌套元素，例如带有摘要内容的 <details> 元素。

¥Groups capture nested elements, such as <details> elements with summary content.

<details>
  <summary>Summary</summary>
  <p>Detail content here</p>
</details>

aria 快照

¥aria snapshot

- group: Summary

属性和状态​

¥Attributes and states

常用的 ARIA 属性，如 checked、disabled、expanded、level、pressed 和 selected，表示控制状态。

¥Commonly used ARIA attributes, like checked, disabled, expanded, level, pressed, and selected, represent control states.

具有 checked 属性的复选框​

¥Checkbox with checked attribute

<input type="checkbox" checked>

aria 快照

¥aria snapshot

- checkbox [checked]

具有 pressed 属性的按钮​

¥Button with pressed attribute

<button aria-pressed="true">Toggle</button>

aria 快照

¥aria snapshot

- button "Toggle" [pressed=true]