# @bahmutov/cypress-toy-visual-testing 中文文档

规范地址：https://npmcn.com/package/%40bahmutov/cypress-toy-visual-testing/

版本：1\.8\.6
npm 元数据更新时间：2025-10-15T15:11:17.837Z
中文译文更新时间：2026-11-07T23:45:24.520Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bahmutov/cypress-toy-visual-testing
原文对照：https://npmcn.com/package/%40bahmutov/cypress-toy-visual-testing/?lang=original
项目主页：https://github.com/bahmutov/cypress-toy-visual-testing#readme
源码仓库：https://github.com/bahmutov/cypress-toy-visual-testing

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

- 包体积（解压后）：85.8 kB，9 个文件
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2024-05-01T15:33:24.068Z
- 最新版本发布：2025-10-15T15:11:17.637Z
- 近 30 天下载量：1986（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 0 个）

## 中文简介

Cypress 用户简单的本地视觉测试

## 安装

```sh
npm install @bahmutov/cypress-toy-visual-testing
```

也可以使用：`pnpm add @bahmutov/cypress-toy-visual-testing`、`yarn add @bahmutov/cypress-toy-visual-testing`、`bun add @bahmutov/cypress-toy-visual-testing`

## README

# @bahmutov/cypress-toy-visual-测试 [![main](https://github.com/bahmutov/cypress-toy-visual-testing/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/bahmutov/cypress-toy-visual-testing/actions/workflows/main.yml)

> Cypress 用户简单的本地视觉测试

## 学习

-   网上课程 [用 Cypress 进行视觉测试](https://cypress.tips/courses/visual-testing)

## 安装

将此插件添加为 dev 依赖

```shell
npm i -D @bahmutov/cypress-toy-visual-testing
```

从 Cypress 配置文件中的“ hook” 设置 :

```js
// cypress.config.js

const { defineConfig } = require('cypress')
// https://github.com/bahmutov/cypress-toy-visual-testing
const {
  setupVisualTesting,
} = require('@bahmutov/cypress-toy-visual-testing/dist/plugin/setup')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      setupVisualTesting(on, config)
      return config
    },
  },
})
```

在您的支持文件中添加自定义命令 :

```js
// cypress/support/e2e.js

// https://github.com/bahmutov/cypress-toy-visual-testing
import '@bahmutov/cypress-toy-visual-testing/dist/support/commands'
```

## 使用

获取完整页面截图

```js
cy.imageDiff('added-todos')
```

### 抓取选项

-   `fullPage` (默认)取出整个页面的截图并将其缝入一个图像
-   `viewport` 取当前可见部分的截图
-   `clipToViewport` 将整个测试跑道的截图取出,将图像剪接到取景口.
-   `diffPercentage` 允许您忽略图像差异, 最高为像素的 N% 。 如果diff低于这个百分比,金像就不会被覆盖
-   `failOnLayoutDiff` 如果尺寸不同, 图像比较失败, 默认为真实
-   `dimensionTolerance` 如果 `failOnLayoutDiff: true`

例如,让我们忽略所有图像差异,最多半个像素

```js
cy.imageDiff('app', { diffPercentage: 0.5 })
```

比较图像,允许每个维度在金像的5%以内

```js
cy.imageDiff('app', {
  failOnLayoutDiff: true,
  dimensionTolerance: 0.05,
})
```

## CI 选项

以下 Cypress env 变量可以改变图像 diff 是如何被批准或拒绝的 :

-   `updateGoldImages` 以新截图覆盖金色图像, 即使有差异 。 用于拉请求中的分支来覆盖可以添加到源分支的图像 。 然后用户可以看到已改变的金像和主分支金像的区别.
    
-   `failOnMissingGoldImage`默认值 `false` 可用于自动失败 `cy.imageDiff` 如果截图没有金色的图像来比较。 例如,在 `main` 树枝,我们可以要求所有金色图像都存在.
    

```yml
- name: Run Cypress tests 🧪
  # https://github.com/cypress-io/github-action
  uses: cypress-io/github-action@v6
  with:
    start: npm start
    # if there is no gold image to compare a screenshot to
    # it is a problem, and we should fail the tests
    env: failOnMissingGoldImage=true
```

## 发展

使用 `npm run watch` 将TS汇编成联合来文

使用下列图标来指代图像:

-   金色图像
-   qq 当前截图
-   图像匹配
-   图像不匹配

## 常见问题

### @bahmutov/cypress-toy-visual-testing 是什么？

Cypress 用户简单的本地视觉测试

### 如何安装 @bahmutov/cypress-toy-visual-testing？

在项目目录运行 npm install @bahmutov/cypress-toy-visual-testing，或使用 pnpm add / yarn add / bun add。

### @bahmutov/cypress-toy-visual-testing 支持 TypeScript 吗？

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

### @bahmutov/cypress-toy-visual-testing 可以商用吗？

@bahmutov/cypress-toy-visual-testing 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bahmutov/cypress-toy-visual-testing 的下载量有多少？

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

### @bahmutov/cypress-toy-visual-testing 还在维护吗？

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