NextEdu/docs/testing/visual-regression.md

视觉回归测试 (Visual Regression Testing)

本项目使用 Playwright 的 toHaveScreenshot() API 实现视觉回归测试,对关键页面在多种视口与主题下进行像素级快照对比,以捕获 UI 的意外变化。

目录结构

tests/visual/
├── visual.config.ts              # 视觉测试配置(页面、视口、主题、快照路径)
├── homepage.spec.ts              # 登录页视觉测试
├── admin-dashboard.spec.ts       # 管理员仪表盘视觉测试
├── teacher-dashboard.spec.ts     # 教师仪表盘视觉测试
├── student-dashboard.spec.ts     # 学生仪表盘视觉测试
├── helpers/
│   ├── auth.ts                   # 认证辅助(登录、setupAuthState)
│   └── visual-helpers.ts         # 视觉通用辅助(视口、主题、遮罩)
└── __screenshots__/              # 快照基线存储目录(自动生成)

覆盖范围

页面	路径	视口	主题	是否需要登录
登录页	/login	desktop / tablet / mobile	light / dark	否
管理员仪表盘	/admin/dashboard	desktop / tablet / mobile	light / dark	是 (admin)
教师仪表盘	/teacher/dashboard	desktop / tablet / mobile	light / dark	是 (teacher)
学生仪表盘	/student/dashboard	desktop / tablet / mobile	light / dark	是 (student)

视口尺寸:

• desktop: 1920 × 1080
• tablet: 768 × 1024
• mobile: 375 × 812

运行测试

前置条件

• 需要启动开发服务器(Playwright 会通过 webServer 配置自动启动)
• 需要登录的视觉测试需要 DATABASE_URL 环境变量,否则会自动跳过
• 测试账号默认为 admin@xiaoxue.edu.cn / 123456,可通过环境变量覆盖

运行命令

# 运行所有视觉回归测试
npm run test:visual

# 运行单个测试文件
npx playwright test --project=visual-chromium tests/visual/homepage.spec.ts

# 以 UI 模式运行(便于调试)
npx playwright test --project=visual-chromium --ui

环境变量

变量	默认值	说明
DATABASE_URL	-	数据库连接串,未设置时需要登录的测试会跳过
VISUAL_ADMIN_EMAIL	admin@xiaoxue.edu.cn	管理员测试账号
VISUAL_ADMIN_PASSWORD	123456	管理员测试密码
VISUAL_TEACHER_EMAIL	admin@xiaoxue.edu.cn	教师测试账号
VISUAL_TEACHER_PASSWORD	123456	教师测试密码
VISUAL_STUDENT_EMAIL	admin@xiaoxue.edu.cn	学生测试账号
VISUAL_STUDENT_PASSWORD	123456	学生测试密码

更新基线

当 UI 发生预期内的变化时,需要更新快照基线:

# 更新所有视觉快照基线
npm run test:visual:update

# 更新单个测试文件的基线
npx playwright test --project=visual-chromium tests/visual/homepage.spec.ts --update-snapshots

更新后的快照应作为 PR 的一部分提交到版本库,以便团队评审 UI 变更。

处理误报

视觉测试可能因为动态内容(时间戳、用户名、实时数据等)产生误报。本项目通过以下方式消除误报:

1. 动态元素遮罩

maskDynamicElements() 辅助函数会自动遮罩以下选择器:

• [data-testid='timestamp']
• [data-testid='current-time']
• [data-testid='user-avatar']
• [data-testid='user-name']
• time
• [data-visual-dynamic]

可在测试中追加额外需要遮罩的选择器:

const masks = await maskDynamicElements(page, ["[data-testid='stat-card-value']"])

2. 标记动态元素

在组件代码中为动态元素添加 data-visual-dynamic 属性,即可自动被遮罩:

<div data-visual-dynamic>{new Date().toLocaleString()}</div>

3. 调整容差

playwright.config.ts 中配置了默认容差 maxDiffPixelRatio: 0.01(允许 1% 像素差异)。若特定页面需要更宽松的容差,可在断言时覆盖:

await expect(page).toHaveScreenshot("name.png", {
  maxDiffPixelRatio: 0.05,
})

4. 禁用动画

默认配置 animations: "disabled",避免动画过渡态导致快照不稳定。

CI 集成

GitHub Actions 示例

name: Visual Regression
on:
  pull_request:
    paths:
      - "src/**"
      - "tests/visual/**"
      - "playwright.config.ts"

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium

      # 启动数据库(按需)
      - run: npm run db:setup
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

      - name: Run visual tests
        run: npm run test:visual
        env:
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
          CI: "true"

      - name: Upload snapshot diff
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: snapshot-diff
          path: test-results/
          retention-days: 7

CI 注意事项

1. 快照基线需提交到版本库: tests/visual/__screenshots__/ 目录应纳入 Git 跟踪
2. 跨平台一致性: 不同操作系统的字体渲染存在差异,建议 CI 与本地使用相同的 Linux 容器环境。若本地为 Windows/macOS,可能出现少量误报,以 CI 结果为准
3. storageState 缓存: tests/visual/.auth/ 目录应加入 .gitignore,不要提交登录态文件

与 E2E 测试的关系

维度	E2E 测试	视觉测试
目录	tests/e2e/	tests/visual/
Playwright 项目	chromium	visual-chromium
运行命令	npm run test:e2e	npm run test:visual
关注点	功能正确性	UI 视觉一致性
断言方式	DOM/行为断言	像素快照对比

两个测试套件相互独立,可分别运行,互不影响。