cypress-plugin-visual-regression-diff

Cypress视觉回归测试插件助力UI测试自动化

cypress-plugin-visual-regression-diff是一款专为Cypress设计的视觉回归测试插件。它支持设置失败阈值、快速预览新旧截图、识别图像差异，为开发者提供流畅的测试体验。该插件兼容E2E和组件测试，适用于多种打包工具，并具备完整的TypeScript类型定义。通过简化视觉回归测试流程，cypress-plugin-visual-regression-diff有助于提升UI开发和测试效率。

Cypress插件视觉回归测试自动化测试UI测试Github开源项目

访问官网

GitHub

<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> <img src="https://yellow-cdn.veclightyear.com/87312a0a/60190fb4-5a63-4f0d-abc8-0f457e616ab8.svg" alt="Cypress Plugin Visual Regression Diff 标志" height="120px"/> <h1 align="center">Cypress 插件 - 视觉回归对比</h1> 借助友好的图形界面进行视觉回归测试。💅 仅适用于 Cypress！ 兼容端到端和组件测试 💪 <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> 为视觉回归测试提供流畅体验的插件： 指定测试失败的阈值。 直接在 Cypress UI 中快速预览新旧截图。 使用图像对比查找视觉变化。 发布为可摇树优化的包，通过 <a href="https://www.npmjs.com/package/microbundle">microbundle</a> 分别为 JS ES5 或现代打包工具提供。 适用于所有打包工具（已在 webpack、vite、rollup 上测试）， 提供完整的类型定义，因为完全使用 <a href="https://www.typescriptlang.org">typescript</a> 编写。 ![frsource-visual-testing-example](https://yellow-cdn.veclightyear.com/87312a0a/cb1bda1a-6c93-41ea-9875-ee24246fbe9c.gif) ## 入门 ### 安装你可以使用你喜欢的包管理器安装这个库： ```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/) <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>

编辑推荐精选

酷表ChatExcel

大模型驱动的Excel数据处理工具

基于大模型交互的表格处理系统，允许用户通过对话方式完成数据整理和可视化分析。系统采用机器学习算法解析用户指令，自动执行排序、公式计算和数据透视等操作，支持多种文件格式导入导出。数据处理响应速度保持在0.8秒以内，支持超过100万行数据的即时分析。

AI工具酷表ChatExcelAI智能客服AI营销产品使用教程

DeepEP

DeepSeek开源的专家并行通信优化框架

DeepEP是一个专为大规模分布式计算设计的通信库，重点解决专家并行模式中的通信瓶颈问题。其核心架构采用分层拓扑感知技术，能够自动识别节点间物理连接关系，优化数据传输路径。通过实现动态路由选择与负载均衡机制，系统在千卡级计算集群中维持稳定的低延迟特性，同时兼容主流深度学习框架的通信接口。

DeepSeek

全球领先开源大模型，高效智能助手

DeepSeek是一家幻方量化创办的专注于通用人工智能的中国科技公司，主攻大模型研发与应用。DeepSeek-R1是开源的推理模型，擅长处理复杂任务且可免费商用。

问小白

DeepSeek R1 满血模型上线

问小白是一个基于 DeepSeek R1 模型的智能对话平台，专为用户提供高效、贴心的对话体验。实时在线，支持深度思考和联网搜索。免费不限次数，帮用户写作、创作、分析和规划，各种任务随时完成！

AI主流办公工具有哪些办公热门AI 助手

KnowS

AI医学搜索引擎整合4000万+实时更新的全球医学文献

医学领域专用搜索引擎整合4000万+实时更新的全球医学文献，通过自主研发AI模型实现精准知识检索。系统每日更新指南、中英文文献及会议资料，搜索准确率较传统工具提升80%，同时将大模型幻觉率控制在8%以下。支持临床建议生成、文献深度解析、学术报告制作等全流程科研辅助，典型用户反馈显示每周可节省医疗工作者70%时间。

Windsurf Wave 3

Windsurf Editor推出第三次重大更新Wave 3

新增模型上下文协议支持与智能编辑功能。本次更新包含五项核心改进：支持接入MCP协议扩展工具生态，Tab键智能跳转提升编码效率，Turbo模式实现自动化终端操作，图片拖拽功能优化多模态交互，以及面向付费用户的个性化图标定制。系统同步集成DeepSeek、Gemini等新模型，并通过信用点数机制实现差异化的资源调配。

AI IDE

腾讯元宝

腾讯自研的混元大模型AI助手

腾讯元宝是腾讯基于自研的混元大模型推出的一款多功能AI应用，旨在通过人工智能技术提升用户在写作、绘画、翻译、编程、搜索、阅读总结等多个领域的工作与生活效率。

AI助手AI对话AI工具腾讯元宝智能体热门 AI 办公助手

Grok3

埃隆·马斯克旗下的人工智能公司 xAI 推出的第三代大规模语言模型

Grok3 是由埃隆·马斯克旗下的人工智能公司 xAI 推出的第三代大规模语言模型，常被马斯克称为“地球上最聪明的 AI”。它不仅是在前代产品 Grok 1 和 Grok 2 基础上的一次飞跃，还在多个关键技术上实现了创新突破。

OmniParser

帮助AI理解电脑屏幕纯视觉GUI元素的自动化解析方案

开源工具通过计算机视觉技术实现图形界面元素的智能识别与结构化处理，支持自动化测试脚本生成和辅助功能开发。项目采用模块化设计，提供API接口与多种输出格式，适用于跨平台应用场景。核心算法优化了元素定位精度，在动态界面和复杂布局场景下保持稳定解析能力。

OmniParser界面解析交互区域检测Github开源项目

流畅阅读

AI网页翻译插件双语阅读工具，还原母语级体验

流畅阅读是一款浏览器翻译插件，通过上下文智能分析提升翻译准确性，支持中英双语对照显示。集成多翻译引擎接口，允许用户自定义翻译规则和快捷键配置，操作数据全部存储在本地设备保障隐私安全。兼容Chrome、Edge、Firefox等主流浏览器，基于GPL-3.0开源协议开发，提供持续的功能迭代和社区支持。

AI翻译AI翻译引擎AI翻译工具

下拉加载更多