# @emerson-eps/cypress-image-snapshot 中文文档

规范地址：https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/

版本：1\.5\.3
npm 元数据更新时间：2026-02-12T11:42:28.925Z
中文译文更新时间：2026-11-13T15:51:16.801Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40emerson-eps/cypress-image-snapshot
原文对照：https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/?lang=original

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

- 包体积（解压后）：31.2 kB，15 个文件
- TypeScript 类型：未声明
- 运行依赖：4 个
- peer 依赖：cypress \>10\.0\.0
- 首次发布：2023-06-15T14:16:58.703Z
- 最新版本发布：2024-10-30T09:21:50.991Z
- 近 30 天下载量：3882（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

Cypress 图像快照绑定 [图片相机](https://github.com/americanexpress/jest-image-snapshot)图像向导逻辑到 [Cypress.io (英语)](https://cypress.io/) 命令.

## 安装

```sh
npm install @emerson-eps/cypress-image-snapshot
```

也可以使用：`pnpm add @emerson-eps/cypress-image-snapshot`、`yarn add @emerson-eps/cypress-image-snapshot`、`bun add @emerson-eps/cypress-image-snapshot`

## README

# Cypress 图像快照

Cypress 图像快照绑定 [图片相机](https://github.com/americanexpress/jest-image-snapshot)图像向导逻辑到 [Cypress.io (英语)](https://cypress.io/) 命令.

[![build-and-test](https://github.com/emerson-eps/cypress-image-snapshot/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/emerson-eps/cypress-image-snapshot/actions/workflows/build-and-test.yml)

-   [安装](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-installation)
    -   [类型脚本](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-typescript)
-   [使用量](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-usage)
    -   [在你的测试中](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-in-your-tests)
        -   [选项](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-options)
    -   [更新快照](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-updating-snapshots)
    -   [防止失败](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-preventing-failures)
    -   [需要显示快照](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-requiring-snapshots-to-be-present)
-   [如何运作](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-how-it-works)
-   [所需资源](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-requirements)
-   [捐款](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-contributing)
    -   [设置](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-setup)
    -   [在插件上工作](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-working-on-the-plugin)
        -   [打开](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-open)
        -   [运行](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-run)
            -   [关于环境变量的说明](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-note-on-environment-variables)
-   [从 `jaredpalmer/cypress-image-snapshot`](https://npmcn.com/package/%40emerson-eps/cypress-image-snapshot/#readme-forked-from-jaredpalmercypress-image-snapshot)

## 安装

使用您选择的软件包管理器安装

```bash
# yarn
yarn add --dev @emerson-eps/cypress-image-snapshot

# npm
npm install --save-dev @emerson-eps/cypress-image-snapshot
```

插入插件功能并添加到 [`setupNodeEvents` 函数](https://docs.cypress.io/guides/references/configuration#setupNodeEvents)数字 :

```ts
// cypress.config.ts

import {defineConfig} from 'cypress'
import {addMatchImageSnapshotPlugin} from '@emerson-eps/cypress-image-snapshot/plugin'

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      addMatchImageSnapshotPlugin(on)
    },
  },
})
```

将命令添加到您的相关 [支持文件](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Support-file)数字 :

```ts
// cypress/support/e2e.ts

import {addMatchImageSnapshotCommand} from '@emerson-eps/cypress-image-snapshot'

addMatchImageSnapshotCommand()

// can also add any default options to be used
// by all instances of `matchImageSnapshot`
addMatchImageSnapshotCommand({
  failureThreshold: 0.2,
})
```

### 类型脚本

TypeScript 被支持所以任何引用都引用 `@types/cypress-image-snapshot` 可以从您的工程中删除

确保将这些类型列入 `tsconfig.json`

```
{
  "compilerOptions": {
    // ...
  },
  "include": ["@emerson-eps/cypress-image-snapshot"]
}
```

## 使用量

### 在你的测试中

```ts
describe('Login', () => {
  it('should be publicly accessible', () => {
    cy.visit('/login');

    // snapshot name will be the test title
    cy.matchImageSnapshot();

    // snapshot name will be the name passed in
    cy.matchImageSnapshot('login');

    // options object passed in
    cy.matchImageSnapshot({
      failureThreshold: 0.4
      blur: 10
      timeout: 3000
    });

    // match element snapshot
    cy.get('#login').matchImageSnapshot();
  });
});
```

#### 选项

选项对象结合了jest-image-snapshot和Cypress截图配置.

-   [图片相机](https://github.com/americanexpress/jest-image-snapshot#%EF%B8%8F-api)
-   [Cypress 截图](https://docs.cypress.io/api/commands/screenshot#Arguments)

```ts
cy.matchImageSnapshot({
  // options for jest-image-snapshot
  failureThreshold: 0.2,
  comparisonMethod: 'ssim',

  // options for Cypress.screenshot()
  capture: 'viewport',
  blackout: ['.some-element'],
})
```

已执行新的选项, 以使函数递归并重试快照 :

```ts
cy.matchImageSnapshot({
  // Time it takes for the snapshot command to time out if the snapshot is not correct
  timeout: 5000,

  //Sets a delay between recursive snapshots
  delayBetweenTries: 1000,
})
```

### 更新快照

运行 Cypress 与 `--env updateSnapshots=true` 以更新所有测试的基础图像文件.

### 需要显示快照

运行 Cypress 与 `--env requireSnapshots=true` 如果缺少快照,则失败。 这对于持续整合很有用,因为应事先提供快照.

## 如何运作

工作流程 `cy.matchImageSnapshot()` 当运行 Cypress 时 :

1.  使用截图 `cy.screenshot()` 根据当前测试而命名.
2.  检查保存的快照是否存在 `<rootDir>/cypress/snapshots` 如果是这样的话,diff 与快照.
3.  如果有结果,请保存到 `<rootDir>/cypress/snapshots/__diff_output__`。 。 。 .

## 所需资源

在Cypress 10.x、11.x和12.x试验

Cypress 必须安装为对等依赖

## 捐款

### 设置

-   清除存储器并安装线条依赖 `yarn install`
-   确保 Docker 设置 。 这是生成/更新快照所必需的
-   使用 [沃尔塔](https://volta.sh/) 建议管理节点和雅恩版本。 这些是 自动从 `package.json`
-   报告应基于 [常规变化日志](https://github.com/pvdlg/conventional-changelog-metahub#commit-types)

### 在插件上工作

为了更方便地测试,同时开发 有一些简单的 验证插件的 Cypress 测试 。 这些测试有两种方式:

#### 打开

`yarn test:open`

在开放模式下,测试在Electron运行,并忽略任何快照故障. 这是 由于开发机对CI的渲染差异. 这里还有 动词输出被发送到测试跑道控制台来协助调试.

**说明** 在此显示上面的线条脚本将每次重建插件 。 这是 有必要,因为测试是对照 `dist` 目录 确保国家防范机制的既定一揽子措施之间的平等.

确保每次更改都要在 Cypress 中测试命令运行

#### 运行

-   `yarn docker:build`
-   `yarn docker:run`

这里的命令可以确保测试在 Docker 容器内进行 匹配 CI 机器。 这样可以生成图像并正确匹配 在 Github 动作中进行测试时.

##### 关于环境变量的说明

必须在默认情况下定义两个环境变量 运行 Docker 中的测试 :

-   `CYPRESS_updateSnapshots=false`
-   `CYPRESS_debugSnapshots=false`

推荐这些装入外壳 [缩写](https://direnv.net/)

然后,他们可以根据需要被推翻:

```
CYPRESS_updateSnapshots=true yarn docker:run
```

## 从 `@simonsmith/cypress-image-snapshot`

这是重写插件从 [西蒙·史密斯](https://github.com/simonsmith/cypress-image-snapshot)。 。 。 .

## 常见问题

### @emerson-eps/cypress-image-snapshot 是什么？

Cypress 图像快照绑定 图片相机图像向导逻辑到 Cypress\.io \(英语\) 命令\.

### 如何安装 @emerson-eps/cypress-image-snapshot？

在项目目录运行 npm install @emerson-eps/cypress-image-snapshot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cypress（\>10\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @emerson-eps/cypress-image-snapshot 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/emerson-eps\_\_cypress-image-snapshot 是否存在。

### @emerson-eps/cypress-image-snapshot 可以商用吗？

@emerson-eps/cypress-image-snapshot 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @emerson-eps/cypress-image-snapshot 的下载量有多少？

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

### @emerson-eps/cypress-image-snapshot 还在维护吗？

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