密码-视觉-帮助者

视觉回归测试助手 密码JS,提供了像素逐像素截图与Playwright,Puppeteer,WebDriver,Appium,WebDriverIO和TestCafe的综合支持比较.

概览

这个帮助器通过比较测试执行过程中所捕获的截图与既定基线图像,实现了自动的视觉回归测试. 当发现差异时,帮助者生成diff图像来突出差异,方便快速识别出意想不到的视觉变化.

关键特性

• 多司机支持 ——与Playwright,Puppeteer,WebDriver,Appium,WebDriverIO和TestCafe无缝集成
• 可配置的容忍 确定像素差异的可接受阈值
• 忽略区域 ——将动态内容领域排除在比较之外
• 基线变化 ——支持多个基线版本的响应或专题版面
• 详细报告 • 每次比较的综合图像和统计

安装

需要节点.js 22.19.0 或以后时间。用 CodeceptJS 4 测试包件 在22.23.4、24.22.1和26.12.1.节点18和20上不再支持.

npm install @digital-commons-official/codeceptjs-visual-helper --save-dev

配置 {}

将帮助添加到您的 codecept.conf.js 配置文件 :

helpers: {
  Playwright: {
    // Your browser helper configuration
  },
  VisualHelper: {
    require: '@digital-commons-official/codeceptjs-visual-helper',
    baselineDir: './tests/screenshots/baseline/',
    diffDir: './tests/screenshots/diff/',
    actualDir: './tests/output/',
    tolerance: 1.5,
    threshold: 0.1
  }
}

配置选项

使用量 +++

监视视觉匹配

这个 assertVisualMatch 方法将当前视图与基线图像进行比较,如果差异超过所配置的容忍度,则测试失败:

// Basic full-page comparison
await I.assertVisualMatch('homepage');

// With custom tolerance
await I.assertVisualMatch('dashboard', { tolerance: 2.5 });

// Element-specific comparison
await I.assertVisualMatch('navigation', { element: '#main-nav' });

// Excluding dynamic regions
await I.assertVisualMatch('profile-page', {
  ignoreRegions: [
    { x: 10, y: 10, width: 200, height: 50 }  // Timestamp area
  ]
});

比较而不作断言

这个 compareVisual 方法进行对比并返回详细结果,不丢弃例外:

const result = await I.compareVisual('checkout-form');

if (!result.isMatch) {
  console.log(`Visual difference detected: ${result.differencePercent}%`);
  console.log(`Diff image saved to: ${result.diffImagePath}`);
}

抓取屏幕截图

// Capture current viewport as actual image
await I.captureScreenshot('landing-page');

// Capture and save as new baseline
await I.captureScreenshot('landing-page', 'baseline');

// Capture specific element
await I.captureScreenshot('footer', 'baseline', 'footer.main');

比较选项

基线变化

帮助者使用平面支持多个基线变化(~后缀公约:

homepage.png           # Primary baseline
homepage~dark.png      # Dark theme variant
homepage~tablet.png    # Tablet viewport variant

在比较期间,帮助者评价所有相匹配的变异并报告最佳相匹配,从而可以在不同的视觉状态下进行全面测试.

比较结果对象

interface VisualComparisonResult {
  isMatch: boolean;           // Whether difference is within tolerance
  differencePercent: number;  // Percentage of differing pixels
  differentPixels: number;    // Count of differing pixels
  totalPixels: number;        // Total pixels in the image
  comparedPixels: number;     // Pixels compared (excluding masked regions)
  variationName: string;      // Name of the matched variation
  diffImagePath: string;      // Path to the generated diff image
  variations: Array<...>;     // Results for all evaluated variations
}

联合国

项目结构

project/helper/
├── src/
│   ├── index.js              # Main VisualHelper class
│   ├── index.d.ts            # TypeScript declarations
│   ├── config/
│   │   └── defaults.js       # Default configuration values
│   ├── drivers/
│   │   └── adapter.js        # Browser driver abstraction layer
│   ├── services/
│   │   ├── comparator.js     # Image comparison logic
│   │   └── path-builder.js   # File path construction
│   └── utils/
│       ├── conversion.js     # Type conversion utilities
│       ├── filesystem.js     # File system operations
│       └── image.js          # PNG and WebP manipulation functions
└── tests/
    ├── config/               # Configuration tests
    ├── services/             # Service tests
    ├── utils/                # Utility tests
    └── integration/          # Visual comparison integration tests

运行测试

# Execute all tests (unit, integration, e2e)
task test

# Execute helper unit tests only
task project:test:helper

# Execute integration tests with visual diff output
task project:test:helper:integration

# Execute CodeceptJS end-to-end tests
task project:test:helper:e2e

整合测试

整合测试产生实际的diff图像,可视同检查。 执行后,检查 project/helper/test-output/ 要审查的目录 :

• 同地比较 - 基线和实际图像,无差异
• 不同的比较 ——有有意差异并突出显示diff输出的图像
• 容忍比较 · 展示严格的宽容环境
• UI 模拟 ——与被忽略区域复杂的页面比较

发行( P)

帮助器被设计成npm包来发布. 下列任务支持发布工作流程:

# Inspect package contents locally without publishing
task project:release:helper

# Check the publishing authorization rules in an isolated runner
task project:test:npm

GitLab CI 使用 npm 信任的出版方式从受保护的默认分支发布 (OIDC) (英语). 发布工作使用默认的跑者标记, 由组合服务 并请求 npm 身份。 npm拒绝来自自营跑道的出处,所以版本在3.0.0之后 带无出处证明。 没有长寿的 npm 标志或本地 .npmrc 这是需要的.

许可证 QQ

欧盟PL-1.2