<p align="center"> <a href="https://www.npmjs.com/package/@frsource/cypress-plugin-visual-regression-diff"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/8cc8637f-89f1-4a11-a4c9-f66aba9691ff.svg" alt="NPM 版本徽章"> </a> <a href="https://www.npmjs.com/package/@frsource/cypress-plugin-visual-regression-diff"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/e34e6f05-7df5-41b3-9972-a7491bba1206.svg" alt="NPM 总下载量徽章"> </a> <a href="https://codeclimate.com/github/FRSOURCE/cypress-plugin-visual-regression-diff/maintainability"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/89177c8e-380a-4985-b501-451e65ed88aa.svg" alt="CodeClimate 可维护性徽章"> </a> <a href="https://codeclimate.com/github/FRSOURCE/cypress-plugin-visual-regression-diff/test_coverage"> <img src="https://api.codeclimate.com/v1/badges/b4f9a6e7b071771dd82f/test_coverage" /> </a> <a href="https://github.com/semantic-release/semantic-release"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/83d37521-1d8e-44cb-9891-ea7b220b0602.svg" alt="semantic-relase 徽章"> </a> <a href="https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/blob/main/LICENSE"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/31bfaf46-1275-4c58-8b52-a6d91705deb0.svg" alt="MIT 许可证徽章"> </a> </p> <p align="center"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/60190fb4-5a63-4f0d-abc8-0f457e616ab8.svg" alt="Cypress Plugin Visual Regression Diff 标志" height="120px"/> </p> <h1 align="center">Cypress 插件 - 视觉回归对比</h1> <p align="center">借助友好的图形界面进行视觉回归测试。💅 <i>仅适用于&nbsp;Cypress！</i> 兼容端到端和组件测试 💪</p> <p align="center"> <a href="#getting-started">入门</a> · <a href="#usage">使用</a> · <a href="#faq">常见问题</a> · <a href="https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/issues">提交问题</a> · <a href="https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/discussions">有问题或想法？</a> <br> </p> <p align="center"> <br> <i>为视觉回归测试提供流畅体验的插件： <br>指定测试失败的阈值。 <br>直接在 Cypress UI 中快速预览新旧截图。 <br>使用图像对比查找视觉变化。 <br>发布为可摇树优化的包，通过 <a href="https://www.npmjs.com/package/microbundle">microbundle</a> 分别为 JS ES5 或现代打包工具提供。 <br>适用于所有打包工具（已在 webpack、vite、rollup 上测试）， <br>提供完整的类型定义，因为完全使用 <a href="https://www.typescriptlang.org">typescript</a> 编写。</i> <br> <br> </p>  ## 入门 ### 安装 你可以使用你喜欢的包管理器安装这个库： ```bash # npm npm install --save-dev @frsource/cypress-plugin-visual-regression-diff

yarn

yarn add -D @frsource/cypress-plugin-visual-regression-diff

pnpm

pnpm add -D @frsource/cypress-plugin-visual-regression-diff

接下来，你需要导入这个库：  
- 首先，在你的支持文件中（默认位于 `cypress/support/index.js`）：  
```ts
// typescript / ES6
import "@frsource/cypress-plugin-visual-regression-diff";

// javascript
require("@frsource/cypress-plugin-visual-regression-diff");

• 其次：
• （对于 Cypress 10.0+）在 cypress.config.js（或 cypress.config.ts）中：

// typescript / ES6
import { defineConfig } from "cypress";
import { initPlugin } from "@frsource/cypress-plugin-visual-regression-diff/plugins";

export default defineConfig({
// initPlugin 必须在使用的部分调用：e2e 或 component
e2e: {
setupNodeEvents(on, config) {
initPlugin(on, config);
},
},
component: {
setupNodeEvents(on, config) {
initPlugin(on, config);
},
},
});

• （对于 Cypress <10.0）在你的插件文件中（默认位于 cypress/plugins/index.js）：

// typescript / ES6
import { initPlugin } from "@frsource/cypress-plugin-visual-regression-diff/plugins";

export default function (
on: Cypress.PluginEvents,
config: Cypress.PluginConfigOptions
) {
initPlugin(on, config);

return config;
}

// javascript
const {
initPlugin,
} = require("@frsource/cypress-plugin-visual-regression-diff/plugins");

module.exports = function (on, config) {
initPlugin(on, config);

return config;
};

就是这样 - 现在让我们看看如何在使用部分中使用这个库。

使用

安装完成后，可以在你的测试中这样使用这个库：

cy.get(".an-element-of-your-choice").matchImage();

或者，如果你想对整个文档进行截图：

cy.matchImage();

matchImage 命令会进行截图，并将其与上一次运行的图像进行比较。如果发生回归，测试将失败，你会看到一个"查看对比"按钮，以查看问题的根源。

示例

仍然在安装上遇到困难？看看这个仓库的示例目录，了解如何在你的项目的 e2e 或组件测试 Cypress 环境中使用这个插件。

自动清理未使用的图像

删除视觉回归插件生成的、不再被任何测试使用的截图是很有用的。 通过环境变量启用此功能，享受释放的存储空间 🚀：

npx cypress run --env "pluginVisualRegressionCleanupUnusedImages=true"

配置

配置插件：

• 通过将配置作为参数传递给 matchImage 命令：

cy.matchImage({
// 截图配置，直接传递给 Cypress 截图方法：https://docs.cypress.io/api/cypress-api/screenshot-api#Arguments
// 默认：{ }
screenshotConfig: {
blackout: ['.element-to-be-blackouted']
},
// pixelmatch 选项，参见：https://www.npmjs.com/package/pixelmatch#pixelmatchimg1-img2-output-width-height-options
// 默认：{ includeAA: true }
diffConfig: {
threshold: 0.01,
},
// 是否自动创建缺失的基准图像
// 默认：true
createMissingImages: false,
// 是否自动更新图像，不进行对比 - 适用于 CI
// 默认：false
updateImages: true,
// 存储截图的目录路径
// 相对路径相对于项目根目录解析
// 支持绝对路径（Unix 和 Windows 操作系统）
// 路径分隔符将根据操作系统由插件自动规范化，你应始终使用 / 作为路径分隔符，例如：C:/my-directory/nested 用于 Windows 驱动器表示法
// 路径中可以使用一个特殊变量：
// - {spec_path} - 从项目根目录到当前规格文件目录的相对路径（例如 `/src/components/my-tested-component`）
// 默认：'{spec_path}/__image_snapshots__'
imagesPath: 'this-might-be-your-custom/maybe-nested-directory',
// 测试应该失败的最大阈值
// 默认：0.01
maxDiffThreshold: 0.1,
// 强制将缩放因子设置为 "1"
// 有助于在高密度屏幕（如 Mac Retina）上截图被放大 2 倍的问题
// 默认：true
forceDeviceScaleFactor: false,
// 用于命名图像文件的标题
// 默认：Cypress.currentTest.titlePath（你的测试标题）
title: `${Cypress.currentTest.titlePath.join(' ')} (${Cypress.browser.displayName})`,
// 传递自定义图像的路径，该图像应用于比较
// 而不是检查上一次运行的图像
// 默认：undefined
matchAgainstPath: '/path/to/reference-image.png'
})

• 通过全局环境配置。环境变量名称与上述配置对象的键相同，但添加了 pluginVisualRegression 前缀，例如：

npx cypress run --env "pluginVisualRegressionUpdateImages=true,pluginVisualRegressionDiffConfig={\"threshold\":0.01}"

// cypress.config.ts
import { defineConfig } from "cypress";

export default defineConfig({
env: {
pluginVisualRegressionUpdateImages: true,
pluginVisualRegressionDiffConfig: { threshold: 0.01 },
},
});

// cypress.env.json (https://docs.cypress.io/guides/guides/environment-variables#Option-2-cypress-env-json)
{
"pluginVisualRegressionUpdateImages": true,
"pluginVisualRegressionDiffConfig": { "threshold": 0.01 }
}

有关设置环境变量的更多方法，请查看这里。

常见问题

<details><summary>为什么截图不符合我的 Cypress 配置中设置的 `viewport`？</summary> Cypress 中的截图默认不会缩放到视口大小。你可以通过以下方式改变这一行为： - 全局更改默认截图配置：<code>Cypress.Screenshot.defaults({ capture: 'viewport' });</code> - 局部通过直接传递截图配置给 <code>.matchImage</code> 命令：<code>cy.matchImage({ screenshotConfig: { capture: 'viewport' } });</code> </details> <details><summary>我升级了这个插件的版本，所有的基准图像都被自动更新了。为什么？</summary> 有时我们需要对图像比较或图像生成算法进行重大更改。为了给你提供最简单的升级路径 - 插件会自动更新你的基准图像。只需在插件升级后将它们提交到你的仓库，就大功告成了！ </details> ## 问题 不要犹豫，直接在[讨论板](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/discussions)上提问！ ## 更新日志 每个版本的变更都记录在[发布说明](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/releases)和[每个包的 CHANGELOG 文件](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/tree/main/packages)中。 ## 许可证 [MIT](https://opensource.org/licenses/MIT) 版权所有 (c) 2021-至今，Jakub FRS Freisler，[FRSOURCE](https://www.frsource.org/) <p align="center"> <a href="https://www.frsource.org/" title="点击访问 FRSOURCE 页面！"> <img src="https://yellow-cdn.veclightyear.com/87312a0a/1b7ef54f-ed05-41d3-9342-22e3f9271af8.jpg" alt="FRSOURCE 标志" height="60px"/> </a> </p>