快照测试

概述

使用 Playwright 的快照测试，你可以针对预定义的快照模板断言页面的无障碍树。

同步

page.goto('https://playwright.net.cn/')
expect(page.query_selector('banner')).to_match_aria_snapshot("""
  - banner:
    - heading /Playwright enables reliable end-to-end/ [level=1]
    - link "Get started"
    - link "Star microsoft/playwright on GitHub"
    - link /[\\d]+k\\+ stargazers on GitHub/
""")

异步

await page.goto('https://playwright.net.cn/')
await expect(page.query_selector('banner')).to_match_aria_snapshot("""
  - banner:
    - heading /Playwright enables reliable end-to-end/ [level=1]
    - link "Get started"
    - link "Star microsoft/playwright on GitHub"
    - link /[\\d]+k\\+ stargazers on GitHub/
""")

断言测试对比快照测试

快照测试和断言测试在测试自动化中服务于不同的目的。

断言测试

断言测试是一种目标明确的方法，你可以在其中断言关于元素或组件的特定值或条件。例如，在 Playwright 中，expect(locator).to_have_text() 验证元素是否包含预期的文本，而 expect(locator).to_have_value() 确认输入字段是否具有预期的值。断言测试是具体的，通常检查元素或属性的当前状态是否符合预期的、预定义的状态。它们对于可预测的、单值检查效果很好，但在测试更广泛的结构或变体时范围有限。

优点

• 清晰性：测试意图明确且易于理解。
• 特异性：测试关注功能的特定方面，使其对不相关的更改更具鲁棒性。
• 调试：失败提供有针对性的反馈，直接指出问题所在。

缺点

• 对于复杂输出冗长：为复杂数据结构或大型输出编写断言可能很繁琐且容易出错。
• 维护开销：随着代码的演进，手动更新断言可能非常耗时。

快照测试

快照测试捕获元素、组件或数据在给定时刻的整个状态的“快照”或表示，然后将其保存以供将来比较。重新运行测试时，会将当前状态与快照进行比较，如果存在差异，则测试失败。这种方法对于复杂或动态结构特别有用，手动断言每个细节会非常耗时。快照测试比断言测试更广泛、更全面，允许你随时间跟踪更复杂的更改。

优点

• 简化复杂输出：例如，使用传统断言测试 UI 组件的渲染输出可能很乏味。快照捕获整个输出，便于比较。
• 快速反馈循环：开发人员可以轻松发现输出中意外的更改。
• 鼓励一致性：有助于在代码演进时保持输出的一致性。

缺点

• 过度依赖：可能很想在没有完全理解的情况下接受对快照的更改，这可能会隐藏错误。
• 粒度：当出现差异时，大型快照可能难以解释，特别是当微小更改影响输出的很大一部分时。
• 适用性：不适用于输出频繁或不可预测地变化的高度动态内容。

何时使用

• 快照测试是以下情况的理想选择：
  • 对整个页面和组件进行 UI 测试。
  • 对复杂 UI 组件进行广泛的结构检查。
  • 对结构很少改变的输出进行回归测试。
• 断言测试是以下情况的理想选择：
  • 核心逻辑验证。
  • 计算值测试。
  • 需要精确条件的细粒度测试。

通过结合快照测试进行广泛的结构检查和断言测试进行特定功能检查，可以实现全面的测试策略。

Aria 快照

在 Playwright 中，aria 快照提供了页面的无障碍树的 YAML 表示。这些快照可以存储起来，以后进行比较，以验证页面结构是否保持一致或满足定义的要求。

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

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

- role "name" [attribute=value]

• role：指定元素的 ARIA 或 HTML 角色（例如，heading、list、listitem、button）。
• "name"：元素的无障碍名称。带引号的字符串表示精确值，/patterns/ 用于正则表达式。
• [attribute=value]：方括号中的属性和值表示特定的 ARIA 属性，例如 checked、disabled、expanded、level、pressed 或 selected。

这些值来自 ARIA 属性或根据 HTML 语义计算。要检查页面的无障碍树结构，请使用 Chrome DevTools 无障碍选项卡。

快照匹配

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

对于以下 DOM 结构：

<h1>title</h1>

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

同步

expect(page.locator("body")).to_match_aria_snapshot("""
  - heading "title"
""")

异步

await expect(page.locator("body")).to_match_aria_snapshot("""
  - heading "title"
""")

匹配时，快照模板会与页面当前的无障碍树进行比较：

• 如果树结构与模板匹配，则测试通过；否则，测试失败，表示预期和实际的无障碍状态不匹配。
• 比较区分大小写并折叠空白字符，因此忽略缩进和换行符。
• 比较对顺序敏感，这意味着快照模板中元素的顺序必须与页面无障碍树中的顺序匹配。

部分匹配

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

<button>Submit</button>

aria 快照

- button

在此示例中，匹配了按钮角色，但未指定无障碍名称（"Submit"），从而允许测试通过，无论按钮的标签是什么。

---

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

<input type="checkbox" checked>

用于部分匹配的 aria 快照

- checkbox

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

---

同样，你可以在列表或组中通过省略特定的列表项或嵌套元素来部分匹配子元素。

<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

用于部分匹配的 aria 快照

- list
  - listitem: Feature B

部分匹配使你能够创建灵活的快照测试，验证必要的页面结构，而无需强制执行特定内容或属性。

严格匹配

默认情况下，将匹配包含子集内容的模板

<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

用于部分匹配的 aria 快照

- list
  - listitem: Feature B

/children 属性可用于控制子元素的匹配方式：

• contain (默认)：如果所有指定的子元素都按顺序存在，则匹配
• equal：如果子元素与指定列表完全按顺序匹配，则匹配
• deep-equal：如果子元素与指定列表完全按顺序匹配（包括嵌套子元素），则匹配

<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

由于模板中不存在 Feature C，aria 快照将失败

- list
  - /children: equal
  - listitem: Feature A
  - listitem: Feature B

使用正则表达式匹配

正则表达式允许对具有动态或可变文本的元素进行灵活匹配。无障碍名称和文本可以支持正则表达式模式。

<h1>Issues 12</h1>

使用正则表达式的 aria 快照

- heading /Issues \d+/

生成快照

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

使用 Playwright 代码生成器生成快照

如果你正在使用 Playwright 的 代码生成器，则通过其交互式界面可以简化 aria 快照的生成过程。

• “断言快照”操作：在代码生成器中，可以使用“断言快照”操作自动为选定的元素创建快照断言。这是将 aria 快照捕获为你录制的测试流程的一部分的快速方法。
• “Aria 快照”选项卡：代码生成器界面中的“Aria 快照”选项卡直观地表示选定定位符的 aria 快照，让你探索、检查和验证元素的角色、属性和无障碍名称，以帮助创建和查看快照。

使用 Locator.aria_snapshot 方法

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

示例:

同步

snapshot = page.locator("body").aria_snapshot()
print(snapshot)

异步

snapshot = await page.locator("body").aria_snapshot()
print(snapshot)

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

无障碍树示例

带有 level 属性的标题

标题可以包含一个 level 属性，指示其标题级别。

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

aria 快照

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

文本节点

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

<div>Sample accessible name</div>

aria 快照

- text: Sample accessible name

内联多行文本

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

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

aria 快照

- paragraph: Line 1 Line 2

链接

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

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

aria 快照

- link "Read more about Accessibility"

文本框

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

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

aria 快照

- textbox: Enter your name

带项目的列表

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

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

aria 快照

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

分组元素

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

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

aria 快照

- group: Summary

属性和状态

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

带有 checked 属性的复选框

<input type="checkbox" checked>

aria 快照

- checkbox [checked]

带有 pressed 属性的按钮

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

aria 快照

- button "Toggle" [pressed=true]