Playwright ARIA Snapshot：AI 写的页面，怎么测语义没变？

关键词：Playwright ARIA Snapshot、AI Coding、UI 自动化测试、可访问性树、语义回归

AI 把结算页改完后，截图对比通过了，原来的 CSS 定位器也没报错。

页面看上去没问题：标题还在、金额还在、“提交订单”四个字也还在。

但实际发生了两件事：

• 原来的 <button> 被重构成了带 onClick 的 <div>，键盘无法稳定触发；
• 订单金额区域失去了语义名称，读屏用户听到的只是一串数字。

这类问题，像素级截图不一定看得见，普通 locator 断言也不一定能覆盖。

AI Coding 时代，UI 自动化不能只测“页面有没有元素”，还要测“用户能不能理解并操作这个页面”。

Playwright 的 ARIA Snapshot 提供了一种中间层：它把页面的可访问性树序列化为 YAML，记录角色、可访问名称、层级和状态。它不替代功能测试，也不替代视觉回归；它负责验证 UI 的语义契约。

一、页面长得一样，不代表交互还是同一个页面

先看一个结算页重构前后的差别。

重构前：

<button type="submit" disabled={isSubmitting}>
  提交订单
</button>

AI 重构后，可能变成：

<div className="submit-button" onClick={submitOrder}>
  提交订单
</div>

视觉上差别不大，但业务意义已经变了。

真正的 button 默认具有可聚焦、键盘触发、禁用状态等语义；一个普通 div 需要开发者额外补齐 role、键盘事件、焦点管理和禁用逻辑。很多 AI 生成的前端代码，恰好会在“看起来等价”的重构中漏掉这些细节。

所以，正确组合不是“用 ARIA Snapshot 取代所有自动化”，而是：

像素看外观，Locator 看节点，ARIA Snapshot 看语义，业务断言看结果。

二、先给关键页面定义“用户能理解的结构”

以订单确认页为例，真正值得长期守住的不是某个 div 的 class，而是以下结构：

• 页面有一个一级标题“确认订单”；
• 订单金额是一个可被识别的区域；
• “提交订单”是一个可操作的按钮；
• 用户协议是可跳转的链接；
• 支付完成后跳转到正确结果页。

先让页面自身具备稳定语义：

export function CheckoutPage() {
  return (
    <main aria-label="订单确认">
      <h1>确认订单</h1>

      <section aria-labelledby="amount-title">
        <h2 id="amount-title">订单金额</h2>
        <p>商品金额 ¥699.00</p>
        <p>优惠金额 -¥100.00</p>
        <strong data-testid="payment-amount">应付金额 ¥599.00</strong>
      </section>

      <a href="/terms">用户协议</a>

      <button type="submit">
        提交订单
      </button>
    </main>
  );
}

再用 Playwright 固定住“不能被随便改掉”的部分：

import {
    test, expect } from '@playwright/test';

test('订单确认页保留核心语义契约', async ({
    page }) => {
   
  await page.goto('/checkout?fixture=member-coupon');

  await expect(
    page.getByRole('main', {
    name: '订单确认' }),
  ).toMatchAriaSnapshot(`
    - heading "确认订单" [level=1]
    - region "订单金额":
      - heading "订单金额" [level=2]
      - text: /应付金额 ¥\\d+\\.\\d{2}/
    - link "用户协议":
      - /url: /terms
    - button "提交订单"
  `);

  const submit = page.getByRole('button', {
    name: '提交订单' });

  // Snapshot 证明语义存在；业务断言继续验证它真的可用
  await expect(submit).toBeEnabled();
  await submit.click();

  await expect(page).toHaveURL(/\\/payment\\/confirm/);
  await expect(page.getByTestId('payment-amount'))
    .toHaveText('应付金额 ¥599.00');
});

这段代码有一个很重要的边界：

• ARIA Snapshot 负责“提交订单仍是按钮、金额仍是命名区域”；
• toBeEnabled() 和点击跳转负责“按钮真的能完成业务动作”；
• 金额断言负责“语义正确的页面没有展示错误结果”。

这才是可维护的组合。

Playwright 官方文档明确区分了 Snapshot 与普通断言：前者适合检查较完整的复杂结构，后者适合精准验证某个状态或值，两者应该配合使用。Snapshot 与断言的适用边界

三、别把整页快照塞进仓库，关键区域才值得建契约

很多团队第一次用 Snapshot，最容易犯的错是：

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

生成一大页 YAML，然后每次 UI 改动就点“更新快照”。

结果是：快照文件越来越长，失败信息越来越没人看，最后变成“反正 CI 红了，更新一下 Snapshot”。

对测试价值最高的做法，是按风险切分。

对关键区域，可以使用 /children: equal，明确要求子节点顺序和内容不能多也不能少：

await expect(
  page.getByRole('region', {
    name: '订单金额' }),
).toMatchAriaSnapshot(`
  - /children: equal
  - heading "订单金额" [level=2]
  - text: 商品金额 ¥699.00
  - text: 优惠金额 -¥100.00
  - strong: 应付金额 ¥599.00
`);

Playwright 默认的子节点匹配更偏“包含关系”；对金额区、支付确认区等高风险模块，才需要有选择地使用 equal 或 deep-equal。否则一次正常加文案，也会让整套测试频繁误报。子节点匹配规则

四、快照更新应该进入代码评审，而不是自动放行

ARIA Snapshot 最大的风险，不是技术本身，而是团队把“更新快照”误当成“修复测试”。

建议把快照更新做成单独的审查动作：

{
   
  "scripts": {
   
    "test:ui-contract": "playwright test tests/ui-contract",
    "update:ui-contract": "playwright test tests/ui-contract --update-snapshots --update-source-method=patch"
  }
}

这里特意使用 patch，而不是直接覆盖源码。这样 UI 契约变化会以 Diff 的形式出现在 PR 中，评审者能回答三个问题：

1. 这次结构变化是否有产品需求支撑？
2. 关键按钮、金额区、协议链接是否仍然存在并可操作？
3. 修改 Snapshot 的同时，是否补充或保留了业务断言？

Playwright 支持把 Snapshot 更新为可审查的 patch 文件，也支持把 ARIA Snapshot 单独存成 .aria.yml 文件。这意味着它不是“黑盒录制结果”，而可以成为版本库中被审查的 UI 契约。更新与管理 Snapshot 的官方方式

一个简单但很有效的团队规则是：

任何涉及“提交、支付、登录、退款”的 ARIA Snapshot 更新，都必须和对应业务断言同时出现在 PR 里。

五、AI 写 UI 越快，测试越要守住语义边界

AI Coding 会明显增加前端重构频率：

• 元素标签被替换；
• 文案、布局和组件树被重组；
• 原有测试定位器被删除或重新生成；
• 视觉不变，但键盘、读屏和跳转行为悄悄退化。

这时，测试不应该陷入“重新找一个 XPath”的循环。

更好的做法是把关键页面当成一份用户可理解的结构协议：

用户要找到什么？
用户要理解什么？
用户要操作什么？
操作之后，业务必须去哪里？

ARIA Snapshot 不是让测试多一份 YAML，而是让 AI 生成的页面多一层可审查、可回归、可解释的交付证据。

如果你们团队已经把 AI Coding 用在前端页面改造上，可以先从一个页面开始：结算页、登录页和退款页里，哪个最值得先定义语义契约？