AI 写完页面后怎么验收：用 Playwright 留下可复查的操作证据

页面截图能说明一部分外观，却无法单独证明按钮可以点击、弹窗会出现，或窄屏下的流程仍然可用。让 AI 完成前端后，可以把几个关键行为写成明确的检查，再保存实际执行的证据。

Playwright Test 提供测试运行器、断言和浏览器测试工具。[1] 本文依据官方文档整理，资料核对日期为 2026 年 10 月 19 日；示例未在读者应用执行。

先把“看起来正常”改写成行为

以帮助面板为例，本文为演示假定应用已经满足以下约定：

• 测试站点运行在 http://127.0.0.1:3000/；
• 页面有一个可访问名称为“显示帮助”的按钮；
• 点击后出现可访问名称为“帮助”、角色为 dialog 的面板。

这些名称是示例应用的约定。读者需要替换为真实界面已经明确的用户行为，不能为了让用例通过而随意更改产品含义。

一份小型验收表可以这样写：

本文下面只实现第一项；其余项目仍需独立验证。

安装时沿用项目现有约定

如果项目已经配置 Playwright，应直接复用现有测试结构。首次接入可以按照官方安装向导选择包管理器；以下以 npm 为例：[1]

1npm init playwright@latest
复制

向导会询问语言、测试目录、CI 配置和浏览器安装等选项。依赖与浏览器下载应纳入项目授权范围；有现成 CI 时先检查配置，避免重复建立流程。

用用户可见的语义定位元素

在已确认的测试目录中保存 help.spec.ts。这里示例目录为 tests/：

1import { test, expect } from '@playwright/test';
2
3test('帮助按钮能够打开面板', async ({ page }) => {
4  await page.goto('http://127.0.0.1:3000/');
5
6  await page.getByRole('button', {
7    name: '显示帮助',
8    exact: true,
9  }).click();
10
11  await expect(
12    page.getByRole('dialog', {
13      name: '帮助',
14      exact: true,
15    })
16  ).toBeVisible();
17});
复制

Playwright 官方建议优先使用面向用户的定位方式，例如角色与可访问名称，并使用能够重试的网页断言。[2] 这样的用例表达了界面契约，也有助于避免把测试绑在易变的 CSS 层级上。

toBeVisible() 会等待目标达到条件；通常不需要先加一段固定休眠来猜测渲染耗时。[2] 如果失败，应检查元素的实际状态、命名或业务行为，而不是不断延长等待。

在明确的测试环境里运行

先按项目文档启动测试应用，再运行：

1npx playwright test tests/help.spec.ts --trace on
复制

测试路径应与实际配置一致。这个命令不会代替你启动示例应用，除非项目已经另行配置了相应服务管理。

Trace 可以保留操作过程，并让人检查动作前后的页面快照与网络活动。[3] 运行后，在实际产物中找到相应 trace.zip，再打开：

1npx playwright show-trace path/to/trace.zip
复制

这里的路径是占位示例，必须换成真实生成的位置。用于首次排查时可以主动记录 Trace；长期 CI 的记录策略应按运行成本和项目需求配置。

失败时先找证据，再改实现

本文建议按顺序判断：

1. 应用是否成功启动，地址是否正确；
2. 按钮是否确实具有目标角色和名称；
3. 点击后是否发生预期状态变化；
4. 面板是否存在但不可见，或名称与约定不一致。

如果界面没有正确的可访问语义，应结合产品需求修复实现。如果产品名称已经调整，则更新验收约定与测试。直接换成模糊选择器，可能掩盖真正的问题。

自动测试与视觉检查各留一份结论

通过上面的用例，只证明在当前环境中，“帮助按钮能打开目标面板”这项检查成立。它并没有验证字号、对比度、布局和完整键盘体验。

交付时，本文建议列出实际执行的用例、浏览器、结果和证据位置，再补充截图或人工检查记录。Trace 可能包含页面内容及请求信息；共享前检查并脱敏，测试使用合成数据。

给 Agent 的提示词可以是：

先读取现有 Playwright 配置，围绕已确认的帮助面板行为补一个最小用例，在测试环境执行并保留 Trace。报告实际结果和未覆盖范围，不访问生产账号或生产写入接口。

参考来源

本文为原创整理；界面约定、代码与排查顺序为作者设计。

• [1] Playwright：Installation
• [2] Playwright：Best Practices
• [3] Playwright：Trace viewer