# @digital-commons-official/codeceptjs-visual-helper 中文文档

规范地址：https://npmcn.com/package/%40digital-commons-official/codeceptjs-visual-helper/

版本：3\.0\.2
npm 元数据更新时间：2026-11-03T12:19:51.319Z
中文译文更新时间：2026-11-12T08:27:49.087Z
软件包许可：EUPL-1\.2

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40digital-commons-official/codeceptjs-visual-helper
原文对照：https://npmcn.com/package/%40digital-commons-official/codeceptjs-visual-helper/?lang=original
项目主页：https://gitlab.com/digital-commons/software/libraries/npm/codeceptjs-visual-helper#readme
源码仓库：https://gitlab.com/digital-commons/software/libraries/npm/codeceptjs-visual-helper

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：73.5 kB，13 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：3 个
- peer 依赖：codeceptjs \>=3\.0\.0，@codeceptjs/helper \>=1\.0\.0
- 首次发布：2025-11-29T01:33:41.232Z
- 最新版本发布：2026-11-03T12:19:51.129Z
- 近 30 天下载量：14938（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

具有 Playwright, Puppeteer, WebDriver, Appium & TestCafe 支持的 CodeceptJS 视觉回归测试助手

## 安装

```sh
npm install @digital-commons-official/codeceptjs-visual-helper
```

也可以使用：`pnpm add @digital-commons-official/codeceptjs-visual-helper`、`yarn add @digital-commons-official/codeceptjs-visual-helper`、`bun add @digital-commons-official/codeceptjs-visual-helper`

## README

# 密码-视觉-帮助者

[![pipeline status](https://gitlab.com/digital-commons/software/libraries/npm/codeceptjs-visual-helper/badges/main/pipeline.svg)](https://gitlab.com/digital-commons/software/libraries/npm/codeceptjs-visual-helper/-/commits/main)

视觉回归测试助手 [密码JS](https://codecept.io/),提供了像素逐像素截图与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上不再支持.

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

## 配置 {}

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

```javascript
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
  }
}
```

### 配置选项

| 选项 | 类型 | 默认 | 说明 |  |
| --- | --- | --- | --- | --- |
| `baselineDir` | `string` | `./tests/screenshots/baseline/` | 包含基线图像的目录 |  |
| `diffDir` | `string` | `false` | `./tests/screenshots/diff/` | 生成的 diff 图像目录; 设置为 `false` 无法禁用 |
| `actualDir` | `string` | `global.output_dir` | 抓取的截图目录 |  |
| `tolerance` | `number` | `0` | 允许的不同像素百分比(0-100) |  |
| `threshold` | `number` | `0.1` | 像素匹配颜色比较阈值 (0–1) |  |
| `diffPrefix` | `string` | `Diff_` | Diff 图像的文件名前缀 |  |
| `imageFormat` | `string` | `'webp'` | `'webp'` (无损失)或 `'png'` 旧基线 |  |
| `saveIntermediateImages` | `boolean` | `false` | 保留用于调试的中间处理图像 |  |
| `captureActual` | `boolean` | `'missing'` | `'missing'` | 自动抓取实际截图 |
| `captureBaseline` | `boolean` | `'missing'` | `'missing'` | 自动捕获基线图像 |

## 使用量 +++

### 监视视觉匹配

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

```javascript
// 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` 方法进行对比并返回详细结果,不丢弃例外:

```javascript
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}`);
}
```

### 抓取屏幕截图

```javascript
// 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');
```

## 比较选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `tolerance` | `number` | 覆盖此比较的默认容忍度 |
| `compareWith` | `string` | 指定自定义基线图像名称 |
| `element` | `string` | CSS 特定元素比较选择器 |
| `bounds` | `object` | 边框 `{ x, y, width, height }` 限制比较 |
| `ignoreRegions` | `array` | 区域组合 `[{ x, y, width, height }]` 排除 |
| `pixelmatchArgs` | `object` | 覆盖像素匹配库选项 |

## 基线变化

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

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

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

## 比较结果对象

```typescript
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
}
```

## 联合国

### 项目结构

```bash
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
```

### 运行测试

```bash
# 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包来发布. 下列任务支持发布工作流程:

```bash
# 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

## 常见问题

### @digital-commons-official/codeceptjs-visual-helper 是什么？

具有 Playwright, Puppeteer, WebDriver, Appium & TestCafe 支持的 CodeceptJS 视觉回归测试助手

### 如何安装 @digital-commons-official/codeceptjs-visual-helper？

在项目目录运行 npm install @digital-commons-official/codeceptjs-visual-helper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：codeceptjs（\>=3\.0\.0）、@codeceptjs/helper（\>=1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @digital-commons-official/codeceptjs-visual-helper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @digital-commons-official/codeceptjs-visual-helper 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @digital-commons-official/codeceptjs-visual-helper 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @digital-commons-official/codeceptjs-visual-helper 可以商用吗？

@digital-commons-official/codeceptjs-visual-helper 使用 EUPL-1\.2 许可。声明的许可为 EUPL-1\.2，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @digital-commons-official/codeceptjs-visual-helper 的下载量有多少？

根据 npm 官方下载统计，@digital-commons-official/codeceptjs-visual-helper 在 2026/10/12 – 2026/11/10 这 30 天内被下载 14,938 次，日均约 498 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @digital-commons-official/codeceptjs-visual-helper 还在维护吗？

最新版本 3\.0\.2 发布于 2026/11/03（8 天前）；至今共发布 44 个版本，其中过去 12 个月发布了 44 个；首次发布于 2025/11/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。