novalon-website/docs/visual-testing-standards.md

视觉测试标准与验收准则

1. 概述

本文档定义了 Novalon 官网项目的视觉测试标准、验收准则和测试流程，确保用户界面在不同设备、浏览器和屏幕尺寸下的视觉一致性和正确性。

2. 测试范围

2.1 视觉元素覆盖

类别	测试内容	测试方式
页面布局	网格系统、间距、对齐方式、响应式断点	全页截图对比
色彩显示	品牌色、功能色、文本色、背景色	CSS 变量验证 + 截图对比
字体样式	字体族、字号、字重、行高、字间距	计算样式检查 + 截图对比
图片渲染	图片加载、尺寸比例、清晰度、懒加载	截图对比 + 元素可见性检查
交互状态	hover、focus、active、disabled 状态	组件截图对比
动画效果	过渡动画、加载动画、微交互	动画禁用后截图对比
主题切换	浅色/深色主题切换	主题切换后截图对比
响应式适配	桌面、平板、移动端布局	多视口截图对比

2.2 测试页面（12 个核心页面）

1. 首页 (/)
2. 关于我们 (/about)
3. 联系我们 (/contact)
4. 产品中心 (/products)
5. 产品详情 (/products/erp)
6. 解决方案列表 (/solutions)
7. 解决方案详情 (/solutions/manufacturing)
8. 服务列表 (/services)
9. 服务详情 (/services/software)
10. 新闻列表 (/news)
11. 新闻详情 (/news/company-founded)
12. 团队介绍 (/team)

2.3 测试矩阵

维度	配置
浏览器	Chromium (Chrome)、Firefox、WebKit (Safari)
视口尺寸	桌面 1280×800、平板 834×1194、移动端 390×844
主题	浅色主题、深色主题
设备类型	桌面端、平板端、移动端（含触摸支持）

3. 测试层级

L1: 全页面视觉回归测试

目标: 检测整页布局的意外变化

测试方法:

• 使用 Playwright toHaveScreenshot 进行全页截图对比
• 每个核心页面生成基线截图
• 每次代码变更后与基线对比

验收标准:

• 像素差异率 ≤ 0.5%
• 最大差异像素数 ≤ 200px
• 允许的差异区域：动态内容（时间、随机数等）、第三方组件

L2: 组件级视觉状态测试

目标: 验证 UI 组件在不同状态下的视觉表现

测试组件:

• 按钮：默认、悬停、聚焦、禁用
• 导航菜单：桌面端、移动端展开
• 卡片组件：默认、悬停
• 表单输入：默认、聚焦、错误状态
• 页头页脚：品牌一致性

验收标准:

• 状态变化有明确的视觉反馈
• 色彩过渡自然，无突兀跳变
• 聚焦环可见且符合 WCAG 标准

L3: 排版与色彩验证

目标: 确保品牌视觉规范的一致性

验证内容:

• H1-H6 标题字体样式
• 正文文本可读性
• 品牌主色调准确性
• 色彩对比度符合 WCAG AA 标准

验收标准:

• 品牌色值误差 ≤ 5%
• 标题字号层级清晰
• 文本对比度 ≥ 4.5:1（普通文本）
• 大文本对比度 ≥ 3:1（18pt 或 14pt 加粗）

4. 验收准则

4.1 通过标准

视觉测试通过需同时满足以下条件：

1. L1 全页回归: 100% 页面通过像素对比（差异在允许范围内）
2. L2 组件状态: 100% 组件状态测试通过
3. L3 排版色彩: 品牌色和字体样式符合规范
4. 跨浏览器: Chromium、Firefox、WebKit 三大浏览器无布局断裂
5. 响应式: 桌面、平板、移动三端布局正常，无内容溢出或重叠

4.2 严重等级定义

等级	定义	示例	修复时限
P0 - 阻塞	页面无法正常渲染、内容缺失或严重错位	首页白屏、导航栏消失	立即修复
P1 - 严重	核心功能区域视觉异常，影响用户理解或操作	表单无法识别、按钮不可见	24 小时内
P2 - 中等	非核心区域视觉问题，不影响主要功能	间距不一致、颜色轻微偏差	本周内
P3 - 轻微	细节优化，不影响功能和可读性	边框圆角差异、字重细微不同	下个迭代

4.3 可接受的差异

以下情况的视觉差异属于可接受范围：

1. 字体渲染差异: 不同操作系统/浏览器的字体抗锯齿差异
2. 亚像素差异: 1px 级别的渲染差异（非布局性）
3. 动态内容: 日期、随机数等动态数据（需在测试中 mask）
4. 图片压缩: 不同浏览器的图片解码细微差异
5. 滚动条样式: 操作系统级别的滚动条样式差异

5. 测试流程

5.1 基线建立流程

1. 确保代码处于稳定状态（主分支最新代码）
2. 运行 npm run test:visual:update 生成基线截图
3. 人工审核所有基线截图的视觉正确性
4. 将基线截图提交到版本库

5.2 日常测试流程

1. 代码提交前运行 npm run test:visual 进行桌面端 Chromium 测试
2. CI/CD 中运行完整的视觉测试套件（所有浏览器和视口）
3. 测试失败时生成差异报告
4. 开发人员确认是 bug 还是预期变更
5. 预期变更则更新基线，bug 则修复代码

5.3 人工验证流程

1. 自动化测试通过后，进行关键页面的人工抽查
2. 重点检查：品牌一致性、信息层次、可读性、交互反馈
3. 记录发现的视觉问题并跟踪修复

6. 工具与命令

6.1 可用命令

# 桌面端 Chromium 视觉测试（快速验证）
npm run test:visual

# 完整视觉测试（所有浏览器和视口）
npm run test:visual:all

# 更新基线截图
npm run test:visual:update

# 移动端视觉测试
npm run test:visual:mobile

# 平板端视觉测试
npm run test:visual:tablet

# 跨浏览器桌面端测试
npm run test:visual:browsers

6.2 测试配置

• 测试框架: Playwright
• 截图目录: e2e/visual-snapshots/
• 测试报告: e2e/playwright-report/
• 像素差异阈值: 0.5% 或 200px（取较宽松者）
• 动画处理: 测试时禁用 CSS 动画

7. 维护与更新

7.1 基线更新时机

• 发布新功能或 UI 重构后
• 品牌视觉规范更新后
• 修复视觉 bug 并验证后
• 依赖库升级导致合理视觉变化后

7.2 测试用例维护

• 新增页面时同步添加 L1 全页测试
• 新增组件时添加 L2 组件状态测试
• 品牌色更新时调整 L3 验证标准
• 定期 review 测试覆盖率

8. 参考资料

• Playwright Visual Testing
• WCAG 2.1 对比度指南
• 项目品牌设计规范