HarmonyOS开发：截图测试——视觉回归测试

📌 核心要点：截图测试通过像素级对比捕获UI的视觉变化，是防止"改了A页面B页面样式悄悄变了"的最后一道防线，容差设置和基线管理是核心难点。

背景与动机

你改了个按钮的圆角，结果列表的间距也跟着变了——你注意到了吗？

功能测试能告诉你按钮能不能点、页面能不能跳，但它管不了样式问题。按钮颜色深了10%、间距多了2px、字体大了一号——这些变化功能测试全发现不了，但用户一眼就能看出来。

更可怕的是，这种样式问题经常是"牵一发而动全身"。你改了全局主题色，十个页面的配色都跟着变了；你调了列表项的高度，详情页的布局就乱了。手动检查？几十个页面你查得过来吗？

这就是截图测试的价值。它不是验证"组件存不存在"，而是验证"页面看起来对不对"。每次跑测试，自动截一张图，和上次的基准图对比——像素级差异，一帧不差。

核心原理

截图测试的工作流程

flowchart TD
    A[执行测试用例] --> B[截取当前页面]
    B --> C{存在基准图?}
    C -->|否| D[保存为基准图]
    D --> E[首次运行-测试通过]
    C -->|是| F[加载基准图]
    F --> G[像素级对比]
    G --> H{差异率 < 容差?}
    H -->|是| I[测试通过]
    H -->|否| J[生成差异图]
    J --> K[测试失败]
    K --> L{是真实bug?}
    L -->|是| M[修复bug]
    L -->|否-预期变更| N[更新基准图]
    M --> A
    N --> O[下次以新基准对比]
    
    classDef start fill:#4A90D9,stroke:#2C5F8A,color:#fff
    classDef process fill:#67C23A,stroke:#3E9B2B,color:#fff
    classDef decision fill:#E6A23C,stroke:#B07D2B,color:#fff
    classDef success fill:#67C23A,stroke:#3E9B2B,color:#fff
    classDef fail fill:#F56C6C,stroke:#C94A4A,color:#fff
    classDef update fill:#9B59B6,stroke:#7D3C98,color:#fff
    
    class A start
    class B,D,F,G process
    class C,H,L decision
    class E,I success
    class J,K fail
    class N,O update

像素对比算法

截图对比的核心是像素差异计算。最基础的算法是逐像素对比RGB值：

graph LR
    A[基准图像素 R1,G1,B1] --> C[计算差异]
    B[当前图像素 R2,G2,B2] --> C
    C --> D["diff = |R1-R2| + |G1-G2| + |B1-B2|"]
    D --> E{diff > 阈值?}
    E -->|是| F[标记为差异像素]
    E -->|否| G[标记为相同像素]
    
    classDef input fill:#4A90D9,stroke:#2C5F8A,color:#fff
    classDef process fill:#67C23A,stroke:#3E9B2B,color:#fff
    classDef decision fill:#E6A23C,stroke:#B07D2B,color:#fff
    classDef diff fill:#F56C6C,stroke:#C94A4A,color:#fff
    classDef same fill:#909399,stroke:#606266,color:#fff
    
    class A,B input
    class C,D process
    class E decision
    class F diff
    class G same

差异率 = 差异像素数 / 总像素数 × 100%。如果差异率超过容差阈值，测试失败。

容差的重要性

为什么需要容差？因为完全一致的截图几乎不可能。同样的代码，在不同设备上渲染可能有亚像素差异；同样的页面，不同时间截图可能因为动画帧不同而有微小差别；甚至系统字体的渲染差异都会导致像素级不一致。

容差设多少合适？这取决于你的场景：

代码实战

基础用法：截图与保存

// 465_screenshot_test_basic.ets
import { Driver, ON } from '@ohos.UiTest';

export default function basicScreenshotTest() {
  const driver = Driver.create();
  
  // ===== 1. 基础截图 =====
  // 截取当前屏幕，保存到指定路径
  driver.captureScreen('/data/local/tmp/home_page.png');
  console.info('已截取首页截图');
  
  // ===== 2. 组件截图 =====
  // 只截取某个组件的区域
  const header = driver.findComponent(ON.id('page_header'));
  if (header !== null) {
    header.captureScreen('/data/local/tmp/header.png');
    console.info('已截取头部区域截图');
  }
  
  // ===== 3. 操作后截图 =====
  // 点击按钮后截取状态变化
  const expandBtn = driver.findComponent(ON.id('expand_btn'));
  expandBtn?.click();
  
  // 等待动画完成
  await sleep(500);
  
  driver.captureScreen('/data/local/tmp/expanded_state.png');
  console.info('已截取展开状态截图');
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

进阶用法：截图对比与差异检测

// 465_screenshot_test_advanced.ets
import { Driver, ON } from '@ohos.UiTest';
import { fileIo } from '@kit.CoreFileKit';

// 截图对比工具类
class ScreenshotComparator {
  private baselineDir: string;
  private currentDir: string;
  private diffDir: string;
  private tolerance: number; // 容差百分比
  
  constructor(baselineDir: string, tolerance: number = 0.5) {
    this.baselineDir = baselineDir;
    this.currentDir = '/data/local/tmp/uitest_current/';
    this.diffDir = '/data/local/tmp/uitest_diff/';
    this.tolerance = tolerance;
  }
  
  // 截取并对比
  async compareScreenshot(driver: Driver, name: string): Promise<{
    passed: boolean;
    diffRate: number;
    diffImagePath?: string;
  }> {
    const currentPath = `${this.currentDir}${name}.png`;
    const baselinePath = `${this.baselineDir}${name}.png`;
    const diffPath = `${this.diffDir}${name}_diff.png`;
    
    // 第1步：截取当前页面
    driver.captureScreen(currentPath);
    
    // 第2步：检查基准图是否存在
    const baselineExists = await this.fileExists(baselinePath);
    if (!baselineExists) {
      // 首次运行，保存为基准图
      await this.copyFile(currentPath, baselinePath);
      console.info(`📸 首次截图，已保存基准图: ${name}`);
      return { passed: true, diffRate: 0 };
    }
    
    // 第3步：加载两张图进行对比
    const diffResult = await this.pixelCompare(baselinePath, currentPath, diffPath);
    
    // 第4步：判断是否通过
    const passed = diffResult.diffRate <= this.tolerance;
    if (!passed) {
      console.error(`❌ 截图对比失败: ${name}, 差异率: ${diffResult.diffRate.toFixed(2)}%`);
    } else {
      console.info(`✅ 截图对比通过: ${name}, 差异率: ${diffResult.diffRate.toFixed(2)}%`);
    }
    
    return {
      passed,
      diffRate: diffResult.diffRate,
      diffImagePath: passed ? undefined : diffPath,
    };
  }
  
  // 像素级对比（简化实现）
  private async pixelCompare(
    baselinePath: string, 
    currentPath: string, 
    diffPath: string
  ): Promise<{ diffRate: number; diffPixels: number }> {
    // 读取两张图片的像素数据
    // 注意：实际项目中需要使用图片解码库获取像素数据
    // 这里展示核心逻辑
    
    const baselineData = await this.readImageData(baselinePath);
    const currentData = await this.readImageData(currentPath);
    
    if (baselineData.width !== currentData.width || baselineData.height !== currentData.height) {
      console.error('截图尺寸不一致，无法对比');
      return { diffRate: 100, diffPixels: baselineData.width * baselineData.height };
    }
    
    const totalPixels = baselineData.width * baselineData.height;
    let diffPixels = 0;
    const pixelThreshold = 30; // 单像素RGB差异阈值
    
    // 逐像素对比
    for (let i = 0; i < totalPixels; i++) {
      const baseR = baselineData.pixels[i * 4];
      const baseG = baselineData.pixels[i * 4 + 1];
      const baseB = baselineData.pixels[i * 4 + 2];
      
      const currR = currentData.pixels[i * 4];
      const currG = currentData.pixels[i * 4 + 1];
      const currB = currentData.pixels[i * 4 + 2];
      
      const diff = Math.abs(baseR - currR) + Math.abs(baseG - currG) + Math.abs(baseB - currB);
      if (diff > pixelThreshold) {
        diffPixels++;
      }
    }
    
    const diffRate = (diffPixels / totalPixels) * 100;
    return { diffRate, diffPixels };
  }
  
  // 更新基准图
  async updateBaseline(name: string): Promise<void> {
    const currentPath = `${this.currentDir}${name}.png`;
    const baselinePath = `${this.baselineDir}${name}.png`;
    await this.copyFile(currentPath, baselinePath);
    console.info(`📸 已更新基准图: ${name}`);
  }
  
  // 辅助方法
  private async fileExists(path: string): Promise<boolean> {
    try {
      const stat = fileIo.statSync(path);
      return stat.size > 0;
    } catch {
      return false;
    }
  }
  
  private async copyFile(src: string, dst: string): Promise<void> {
    fileIo.copyFileSync(src, dst);
  }
  
  private async readImageData(path: string): Promise<{
    width: number;
    height: number;
    pixels: Uint8Array;
  }> {
    // 实际实现需要使用image模块解码PNG
    // 这里返回占位数据
    return { width: 1080, height: 1920, pixels: new Uint8Array(0) };
  }
}

完整示例：多页面视觉回归测试

// 465_screenshot_test_full.ets
import { Driver, ON } from '@ohos.UiTest';

// 视觉回归测试套件
class VisualRegressionSuite {
  private driver: Driver;
  private comparator: ScreenshotComparator;
  private results: Array<{
    page: string;
    passed: boolean;
    diffRate: number;
  }>;
  
  constructor() {
    this.driver = Driver.create();
    this.comparator = new ScreenshotComparator(
      '/data/local/tmp/uitest_baselines/',
      0.5 // 默认0.5%容差
    );
    this.results = [];
  }
  
  // 测试首页
  async testHomePage(): Promise<void> {
    // 确保在首页
    const homeTab = this.driver.findComponent(ON.id('tab_home'));
    homeTab?.click();
    await this.sleep(800);
    
    const result = await this.comparator.compareScreenshot(this.driver, 'home_page');
    this.results.push({ page: '首页', passed: result.passed, diffRate: result.diffRate });
  }
  
  // 测试商品详情页
  async testProductPage(): Promise<void> {
    // 导航到商品详情页
    const firstProduct = this.driver.findComponent(ON.id('product_item_0'));
    firstProduct?.click();
    await this.sleep(1000);
    
    const result = await this.comparator.compareScreenshot(this.driver, 'product_page');
    this.results.push({ page: '商品详情', passed: result.passed, diffRate: result.diffRate });
    
    // 返回
    this.driver.pressKey(KeyCode.BACK);
    await this.sleep(500);
  }
  
  // 测试购物车页面
  async testCartPage(): Promise<void> {
    const cartTab = this.driver.findComponent(ON.id('tab_cart'));
    cartTab?.click();
    await this.sleep(800);
    
    const result = await this.comparator.compareScreenshot(this.driver, 'cart_page');
    this.results.push({ page: '购物车', passed: result.passed, diffRate: result.diffRate });
  }
  
  // 测试个人中心页面
  async testProfilePage(): Promise<void> {
    const profileTab = this.driver.findComponent(ON.id('tab_profile'));
    profileTab?.click();
    await this.sleep(800);
    
    const result = await this.comparator.compareScreenshot(this.driver, 'profile_page');
    this.results.push({ page: '个人中心', passed: result.passed, diffRate: result.diffRate });
  }
  
  // 测试暗色模式
  async testDarkMode(): Promise<void> {
    // 切换到暗色模式
    const settingsBtn = this.driver.findComponent(ON.id('settings_btn'));
    settingsBtn?.click();
    await this.sleep(500);
    
    const darkModeToggle = this.driver.findComponent(ON.id('dark_mode_toggle'));
    darkModeToggle?.click();
    await this.sleep(1000); // 等待主题切换完成
    
    // 截取暗色模式下的各页面
    const homeTab = this.driver.findComponent(ON.id('tab_home'));
    homeTab?.click();
    await this.sleep(500);
    
    const result = await this.comparator.compareScreenshot(this.driver, 'home_page_dark');
    this.results.push({ page: '首页(暗色)', passed: result.passed, diffRate: result.diffRate });
    
    // 切回亮色模式
    const settingsBtn2 = this.driver.findComponent(ON.id('settings_btn'));
    settingsBtn2?.click();
    await this.sleep(500);
    const darkModeToggle2 = this.driver.findComponent(ON.id('dark_mode_toggle'));
    darkModeToggle2?.click();
    await this.sleep(1000);
  }
  
  // 运行所有测试
  async runAll(): Promise<void> {
    console.info('📸 ===== 开始视觉回归测试 =====');
    
    await this.testHomePage();
    await this.testProductPage();
    await this.testCartPage();
    await this.testProfilePage();
    await this.testDarkMode();
    
    this.printReport();
  }
  
  // 打印报告
  printReport(): void {
    console.info('\n📸 ===== 视觉回归测试报告 =====');
    
    const passed = this.results.filter(r => r.passed).length;
    const total = this.results.length;
    
    for (const r of this.results) {
      const status = r.passed ? '✅' : '❌';
      console.info(`${status} ${r.page}: 差异率 ${r.diffRate.toFixed(2)}%`);
    }
    
    console.info(`\n通过率: ${passed}/${total} (${(passed / total * 100).toFixed(0)}%)`);
  }
  
  private sleep(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// 执行测试
export default async function runVisualRegressionTest() {
  const suite = new VisualRegressionSuite();
  await suite.runAll();
}

踩坑与注意事项

坑1：动画和动态内容

截图测试最大的敌人就是动态内容。轮播图在自动播放、时间在实时更新、广告位在随机展示——每次截图都不一样，对比永远失败。

解决方案：

1. 固定时间点截图：在动画的特定帧截图，而不是随机时刻
2. 屏蔽动态区域：对比时忽略特定区域（比如广告位、时间显示区）
3. Mock动态数据：测试时使用固定的测试数据，而不是真实接口数据

// 截图前等待动画到稳定帧
await sleep(2000); // 等轮播图停在某一帧

// 或者禁用动画
// 在测试环境下设置动画时长为0

坑2：不同设备的渲染差异

同一个页面，在1080p和2K屏幕上渲染出来的像素不一样。字体抗锯齿、图片缩放、甚至GPU渲染管线都可能导致亚像素差异。

解决方案：

1. 基准图和对比图必须在同一设备上生成
2. 如果要支持多设备，每个设备维护独立的基准图集
3. 容差设置要考虑设备差异，别设太低

坑3：容差设太低或太高

容差0%意味着完全不允许差异——这在实际项目中几乎不可能通过。容差5%意味着20×20像素的图片允许有20个像素不同——这可能漏掉真正的bug。

建议：从0.5%开始，根据实际运行结果调整。如果频繁误报，适当提高；如果漏报了样式bug，适当降低。

坑4：基准图管理混乱

基准图是截图测试的"标准答案"。如果基准图本身就是错的，后续所有对比都失去意义。

管理原则：

1. 基准图必须经过人工审核才能入库
2. 基准图纳入版本控制，和代码一起管理
3. 更新基准图必须有明确的变更原因记录
4. 不同版本/环境的基准图分开存储

坑5：截图文件体积

一张1080×2340的PNG截图大约2-5MB。50个页面的基准图就是100-250MB。如果再加上每次运行的对比图和差异图，存储空间消耗很快。

建议：

1. 定期清理历史截图，只保留最近N次的结果
2. 差异图用高压缩率格式保存
3. 基准图用无损格式，对比图可以用有损格式

HarmonyOS 6适配说明

HarmonyOS 6对截图测试做了以下增强：

1. 内置截图对比API：driver.compareScreenshot(baselinePath, options)直接在框架层面做像素对比，不需要自己实现对比算法
2. 区域屏蔽：options.maskAreas可以指定忽略对比的区域，解决动态内容问题
3. 多分辨率基准图：支持同一页面在不同分辨率下的独立基准图管理
4. 差异图高亮：差异图自动高亮差异区域，用红色标记，方便快速定位
5. 感知哈希对比：除了像素对比，新增pHash算法，对缩放、偏移更鲁棒

迁移注意：captureScreen的返回值从void改为boolean，表示截图是否成功。旧代码如果没处理返回值不受影响，但建议加上错误检查。

总结

截图测试是UI测试体系的"最后一公里"。功能测试验证逻辑正确，截图测试验证视觉正确。两者结合，才能真正做到"用户看到的和我们预期的一致"。

核心建议：截图测试不是替代功能测试，而是补充。别指望截图测试能发现所有bug，但它在防止样式回归方面无可替代。从容差0.5%开始，逐步调优，别一上来就追求完美——先跑起来，再优化。