UI 视觉设计 / 系统课时

用 Playwright 验证交互状态

用 Playwright 验证交互状态

Figma 中的按钮与输入框看起来正确,仍可能存在 Tab 顺序错误、禁用按钮被误触发或主题切换无效的问题。本课用一个可独立运行的页面编写 Playwright 测试,同时区分交互断言和截图对比,让回归失败能指向具体原因。

学习目标

  • 用键盘事件与自动重试断言验证焦点顺序、禁用状态及提交结果。
  • 验证 Light/Dark 主题切换后 DOM 状态与实际样式一致。
  • 建立视觉快照基准,区分行为回归和视觉回归。

准备 Playwright 测试环境

在已安装 Node.js 与 npm 的项目根目录运行以下命令;初始化向导选择 TypeScript、tests 目录,并确认安装浏览器。已配置 Playwright 的项目可跳过初始化,直接安装 Chromium。

bash
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 组件。

ts
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 无法激活的问题。

禁用状态下的 Tab 焦点路线与行为、视觉双轨验证

检验类别 代表断言 主要发现的问题
行为回归 toBeFocused()、toBeDisabled()、toHaveAttribute() Tab 顺序、控件可用性、状态切换错误
视觉回归 toHaveScreenshot() 颜色、间距、轮廓、布局偏离基准

截图相同不意味着按钮可由键盘操作;DOM 属性正确也不意味着视觉效果正确。因此行为测试和截图测试应分开命名,失败后先看哪一种断言触发。

运行用例并审查失败

第一次运行时需要生成并人工审查截图基准;确认暗色页面正确后,将生成的快照纳入版本控制。以后回归运行不要携带更新参数,否则可能把缺陷覆盖进基准。

bash
npx playwright test tests/interaction.spec.ts --project=chromium --update-snapshots
npx playwright test tests/interaction.spec.ts --project=chromium

预期输出(两次运行均通过时的摘要,耗时因环境不同而变化):

text
4 passed (<TIME>)

如果没有 chromium 项目名称,先检查 playwright.config.ts 中的 projects。若行为断言失败,查看实际焦点、原生 disabled 属性及事件处理;若仅截图失败,检查字体、操作系统、浏览器版本和视口是否与基准一致。确认产品设计有意变更后,才重新更新快照。

在 React 组件上复用这些断言

实际项目中,应把 beforeEach 内的 page.setContent(fixture) 换成 page.goto('/settings'),并在 playwright.config.ts 配置指向本地开发服务器的 use.baseURL;/settings 只是示例路由,需要替换成真实路径。随后将“邮箱”“提交”“切换主题”替换为页面真实的可访问名称,避免测试演示页却误以为覆盖了产品。

建议每个关键交互组件至少覆盖一种无鼠标操作路径、一种禁用或错误边界,以及必要的主题状态。截图基准按固定浏览器、系统、字体与视口生成;行为用例保持独立,才能在设计变量或 React 实现更新后迅速判断是交互退化还是纯视觉变化。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Playwright 验证交互状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通