Cypress 插件 - 视觉回归对比

借助友好的图形界面进行视觉回归测试。💅 仅适用于 Cypress！ 兼容端到端和组件测试 💪

入门 · 使用 · 常见问题 · 提交问题 · 有问题或想法？

为视觉回归测试提供流畅体验的插件：
指定测试失败的阈值。
直接在 Cypress UI 中快速预览新旧截图。
使用图像对比查找视觉变化。
发布为可摇树优化的包，通过 microbundle 分别为 JS ES5 或现代打包工具提供。
适用于所有打包工具（已在 webpack、vite、rollup 上测试），
提供完整的类型定义，因为完全使用 typescript 编写。

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

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

常见问题