UI 视觉设计 / 系统课时
用 Playwright 验证交互状态
用 Playwright 验证交互状态
Figma 中的按钮与输入框看起来正确,仍可能存在 Tab 顺序错误、禁用按钮被误触发或主题切换无效的问题。本课用一个可独立运行的页面编写 Playwright 测试,同时区分交互断言和截图对比,让回归失败能指向具体原因。
学习目标
- 用键盘事件与自动重试断言验证焦点顺序、禁用状态及提交结果。
- 验证 Light/Dark 主题切换后 DOM 状态与实际样式一致。
- 建立视觉快照基准,区分行为回归和视觉回归。
准备 Playwright 测试环境
在已安装 Node.js 与 npm 的项目根目录运行以下命令;初始化向导选择 TypeScript、tests 目录,并确认安装浏览器。已配置 Playwright 的项目可跳过初始化,直接安装 Chromium。
npm init playwright@latest
npx playwright install chromium预期结果:项目内存在 playwright.config.ts 和 tests/ 目录,Chromium 浏览器可用于运行测试。本文使用 Playwright Test 的 test、expect、getByRole 与截图断言,不依赖真实后端。
编写键盘、禁用和主题测试
在 tests/interaction.spec.ts 写入以下完整代码。示例页面包含邮箱输入框、初始禁用的提交按钮、主题切换按钮和状态提示;使用 page.setContent() 是为了先验证测试写法,而不是声称已测过真实 React 组件。
import { test, expect } from '@playwright/test';
// 自包含测试页面:无服务器、无网络请求。
const fixture = `<!doctype html>
<html lang='zh-CN' data-theme='light'>
<head><style>
body { margin: 24px; font: 16px Arial, sans-serif;
background: #fff; color: #0f172a; }
html[data-theme='dark'] body { background: #0f172a; color: #fff; }
button:focus-visible, input:focus-visible {
outline: 2px solid #2563eb; outline-offset: 2px;
}
</style></head>
<body>
<label for='email'>邮箱</label>
<input id='email' type='email'>
<button id='submit' disabled>提交</button>
<button id='theme'>切换主题</button>
<p role='status'>未提交</p>
<script>
const email = document.querySelector('#email');
const submit = document.querySelector('#submit');
email.addEventListener('input', () => {
// 只有非空且通过浏览器邮箱校验后才能提交。
submit.disabled = !email.value || !email.validity.valid;
});
submit.addEventListener('click', () => {
document.querySelector('[role=status]').textContent = '已提交';
});
document.querySelector('#theme').addEventListener('click', () => {
const root = document.documentElement;
root.dataset.theme = root.dataset.theme === 'light' ? 'dark' : 'light';
});
</script>
</body></html>`;
test.beforeEach(async ({ page }) => {
// 固定视口,避免同一快照混入尺寸差异。
await page.setViewportSize({ width: 375, height: 800 });
await page.setContent(fixture);
});
test('禁用按钮被 Tab 跳过', async ({ page }) => {
const email = page.getByRole('textbox', { name: '邮箱' });
const submit = page.getByRole('button', { name: '提交' });
await page.keyboard.press('Tab');
await expect(email).toBeFocused();
await expect(submit).toBeDisabled();
await page.keyboard.press('Tab');
await expect(page.getByRole('button', { name: '切换主题' }))
.toBeFocused();
});
test('有效输入后可通过 Enter 提交', async ({ page }) => {
const email = page.getByRole('textbox', { name: '邮箱' });
const submit = page.getByRole('button', { name: '提交' });
await email.fill('invalid');
await expect(submit).toBeDisabled();
await email.fill('reader@example.com');
await expect(submit).toBeEnabled();
await email.press('Tab');
await expect(submit).toBeFocused();
await page.keyboard.press('Enter');
await expect(page.getByRole('status')).toHaveText('已提交');
});
test('Enter 切换主题并改变实际样式', async ({ page }) => {
await page.getByRole('button', { name: '切换主题' }).press('Enter');
await expect(page.locator('html'))
.toHaveAttribute('data-theme', 'dark');
await expect(page.locator('body'))
.toHaveCSS('background-color', 'rgb(15, 23, 42)');
});
test('暗色主题截图没有意外变化', async ({ page }) => {
await page.getByRole('button', { name: '切换主题' }).click();
await expect(page).toHaveScreenshot('dark-375.png', {
animations: 'disabled',
});
});预期结果:四个测试分别验证 Tab 跳过禁用控件、有效邮箱经 Enter 提交、暗色主题实际生效,以及暗色页面与已批准快照一致。首次运行截图测试前,须先按后文命令建立基准。
getByRole 根据可访问角色与名称定位,比依赖 CSS 类名更贴近真实交互;toBeFocused()、toBeDisabled() 和 toHaveCSS() 会在超时前自动重试。这里对主题同时检查 data-theme 和计算后的背景色,避免“属性已变、样式未生效”的假通过。
识别焦点路线和回归类型
禁用状态会改变键盘遍历路线:邮箱为空时,Tab 从输入框越过“提交”直达“切换主题”;邮箱有效时,“提交”重新进入焦点顺序。只验证按钮颜色,无法发现焦点卡住或 Enter 无法激活的问题。

| 检验类别 | 代表断言 | 主要发现的问题 |
|---|---|---|
| 行为回归 | toBeFocused()、toBeDisabled()、toHaveAttribute() |
Tab 顺序、控件可用性、状态切换错误 |
| 视觉回归 | toHaveScreenshot() |
颜色、间距、轮廓、布局偏离基准 |
截图相同不意味着按钮可由键盘操作;DOM 属性正确也不意味着视觉效果正确。因此行为测试和截图测试应分开命名,失败后先看哪一种断言触发。
运行用例并审查失败
第一次运行时需要生成并人工审查截图基准;确认暗色页面正确后,将生成的快照纳入版本控制。以后回归运行不要携带更新参数,否则可能把缺陷覆盖进基准。
npx playwright test tests/interaction.spec.ts --project=chromium --update-snapshots
npx playwright test tests/interaction.spec.ts --project=chromium预期输出(两次运行均通过时的摘要,耗时因环境不同而变化):
4 passed (<TIME>)如果没有 chromium 项目名称,先检查 playwright.config.ts 中的 projects。若行为断言失败,查看实际焦点、原生 disabled 属性及事件处理;若仅截图失败,检查字体、操作系统、浏览器版本和视口是否与基准一致。确认产品设计有意变更后,才重新更新快照。
在 React 组件上复用这些断言
实际项目中,应把 beforeEach 内的 page.setContent(fixture) 换成 page.goto('/settings'),并在 playwright.config.ts 配置指向本地开发服务器的 use.baseURL;/settings 只是示例路由,需要替换成真实路径。随后将“邮箱”“提交”“切换主题”替换为页面真实的可访问名称,避免测试演示页却误以为覆盖了产品。
建议每个关键交互组件至少覆盖一种无鼠标操作路径、一种禁用或错误边界,以及必要的主题状态。截图基准按固定浏览器、系统、字体与视口生成;行为用例保持独立,才能在设计变量或 React 实现更新后迅速判断是交互退化还是纯视觉变化。