@ blazediff/ marcher (英语)

视觉回归测试的核心匹配者逻辑. 提供与多算法,框架不可知API,快取状态跟踪的快取比较.

特征

• 多种比较方法数字 : core, (中文(简体) ), core-native, (中文(简体) ), ssim, (中文(简体) ), msssim, (中文(简体) ), hitchhikers-ssim, (中文(简体) ), gmsd
• 灵活输入类型: 文件路径或图像缓冲
• 快照状态跟踪: 报告增加/匹配/更新/失效
• 可配置阈值: 按像素计数或百分比
• 框架不可知性: Jest, Vitest, Bun 集成的核心逻辑
• 丰富的比较结果: Diff 计数、百分比和相似性分数

安装

npm install @blazediff/matcher

快速启动

import { getOrCreateSnapshot } from '@blazediff/matcher';

const result = await getOrCreateSnapshot(
  imageBuffer, // or file path
  {
    method: 'core',
    failureThreshold: 0.01,
    failureThresholdType: 'percent',
  },
  {
    testPath: '/path/to/test.spec.ts',
    testName: 'should render correctly',
  }
);

console.log(result.pass); // true/false
console.log(result.snapshotStatus); // 'added' | 'matched' | 'updated' | 'failed'
console.log(result.diffPercentage); // e.g., 0.05

API 参考

获取 OrCreateSnapshot( 已收到, 选项, 测试Context)

用于快照比较的主要功能.

回返情况: Promise<ComparisonResult>

匹配选项

比较结果

图像输入

type ImageInput =
  | string // File path
  | Uint8Array // Encoded PNG bytes (a Buffer works)
  | {
      data: Uint8Array | Uint8ClampedArray | Buffer;
      width: number;
      height: number;
    };

比较方法

core-native

通过 N-API 绑定来进行粗口比对. 最快速的方法 与本地的表演.

• 投入: 文件路径、 PNG 缓冲器或原始 RGBA 图像
• 算法: YIQ 色彩空间, 基于块优化
• 最好还是: 生产测试,大图像

core-wasm

这个 core-native 算法编译为 WebAssembly 。 同样的结果,没有本地的二进制.

• 投入: 文件路径或缓冲

core

在JavaScript中比对像素. 纯粹的JS执行,没有本土依赖.

• 投入: 文件路径或缓冲
• 算法: YIQ 有反变异检测的色彩空间
• 最好还是: 跨平台相容性

ssim

结构相似性指数. 衡量概念上的相似性.

• 投入: 文件路径或缓冲
• 算法: 具有可配置窗口大小的标准SSIM
• 最好还是: 概念质量评估
• 分数: 1 = 相同,下同

msssim

多比例结构相似性指数.

• 投入: 文件路径或缓冲
• 算法: 跨多个尺度的SSIM
• 最好还是: 分辨率或比例不同的图像

hitchhikers-ssim

快速SSIM取自"希契克指南".

• 投入: 文件路径或缓冲
• 算法: 优化SSIM计算
• 最好还是: 以可接受的精确度取舍加快SSIM

gmsd

渐入相相相相相.

• 投入: 文件路径或缓冲
• 算法: 基于渐变的感官相似性
• 最好还是: 检测结构变化
• 分数: 0 = 相同,高 = 不同

用法实例

带有文件路径

const result = await getOrCreateSnapshot(
  '/path/to/screenshot.png',
  { method: 'core-native' },
  { testPath: __filename, testName: 'test name' }
);

带有图像缓冲

const imageData = {
  data: new Uint8Array([...]),
  width: 800,
  height: 600,
};

const result = await getOrCreateSnapshot(
  imageData,
  { method: 'core' },
  { testPath: __filename, testName: 'test name' }
);

自定义阈值

const result = await getOrCreateSnapshot(
  imagePath,
  {
    method: 'core',
    failureThreshold: 0.1,
    failureThresholdType: 'percent', // Allow 0.1% difference
    diff: { threshold: 0.05 }, // Stricter per-pixel color threshold
  },
  { testPath: __filename, testName: 'test name' }
);

不同的比较方法

// Fastest - Rust native (paths, PNG buffers or raw images)
await getOrCreateSnapshot(imagePath, { method: 'core-native' }, context);

// Pure JavaScript
await getOrCreateSnapshot(imageBuffer, { method: 'core' }, context);

// Perceptual similarity
await getOrCreateSnapshot(imageBuffer, { method: 'ssim' }, context);

// Gradient-based
await getOrCreateSnapshot(imageBuffer, { method: 'gmsd' }, context);

框架整合

这个软件包为特定框架的整合提供了核心逻辑:

• @blazediff/快讯 - 最佳配对者
• @ blazediff/vitest (英语) - 维特匹配者
• @ blazediff/ bun (英语) - Bun测试匹配器

链接

• GitHub 仓库
• 文档
• 国家防范机制一揽子计划