# @blazediff/vitest 中文文档

规范地址：https://npmcn.com/package/%40blazediff/vitest/

版本：2\.0\.0
npm 元数据更新时间：2026-11-05T04:25:45.021Z
中文译文更新时间：2026-11-08T06:29:22.701Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blazediff/vitest
原文对照：https://npmcn.com/package/%40blazediff/vitest/?lang=original
项目主页：https://blazediff.dev/
源码仓库：https://github.com/teimurjan/blazediff

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

- 包体积（解压后）：14 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vitest \>=1\.0\.0
- 首次发布：2026-01-05T11:54:18.720Z
- 最新版本发布：2026-11-05T04:25:44.648Z
- 近 30 天下载量：6436（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

使用 blazediff 进行视觉回归测试的比对器

## 安装

```sh
npm install @blazediff/vitest
```

也可以使用：`pnpm add @blazediff/vitest`、`yarn add @blazediff/vitest`、`bun add @blazediff/vitest`

## README

# @ blazediff/vitest (英语)

[![npm bundle size](https://img.shields.io/npm/unpacked-size/%40blazediff%2Fvitest?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/vitest) [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fvitest?style=for-the-badge)](https://www.npmjs.com/package/@blazediff/vitest)

Vitest匹配器,用于用blazediff进行视觉回归测试. 由 @blazediff/ matcher提供.

## 特征

-   **本地维特匹配器**数字 : `toMatchImageSnapshot()` 延长Vitest的预期
-   **快照状态跟踪**: Vitest报告准确的快照清点(增加/匹配/更新/失败)
-   **多重比较算法**数字 : `core`, (中文(简体) ), `core-native`, (中文(简体) ), `ssim`, (中文(简体) ), `msssim`, (中文(简体) ), `hitchhikers-ssim`, (中文(简体) ), `gmsd`
-   **自动设置**: 自动导入和登记
-   **更新模式**: 工作与维特 `-u` 旗帜
-   **类型脚本支持**: 包括完整类型定义

## 安装

```bash
npm install --save-dev @blazediff/vitest
```

**同伴依赖关系**(原始内容存档于2018-03-01) (中文(简体) ). Vitest >= 1.0.0

## 快速启动

```typescript
import { expect, it } from 'vitest';
import '@blazediff/vitest';

it('should match screenshot', async () => {
  const screenshot = await takeScreenshot();

  await expect(screenshot).toMatchImageSnapshot({
    method: 'core',
  });
});
```

## API 参考

### 到MatchImageSnapshot( 选项 )

图像快照比较的比对器 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `options` | 部分“ Matcher 选项” | 可选比较方案(见下文) |

#### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `method` | “ 核心 ” “ 核心内在 ” “ sim ” “ mssim ” “ hitchhikers ” “ gmsd ” | "核心" ("核心") | 要使用的比较算法 |
| `failureThreshold` | 编号 | 0 个 | 允许的像素数或百分比差异 |
| `failureThresholdType` | “ 像素”“%” | "像素"(像素) | 如何解释失败风险 |
| `snapshotsDir` | 字符串 | "... 弹出..." | 相对于测试文件存储快取目录 |
| `snapshotIdentifier` | 字符串 | 自动生成 | 自定义快照文件的标识符 |
| `updateSnapshots` | 布尔 | 虚假 | 强制更新快照 |
| `diff` | 对象 | \- 说吧 | 核心、核心瓦斯和核心内在的备选办法,例如: `{ threshold: 0.1, antialiasing: true }`。 。 。 . `ssim` 财务报告和审定财务报表 `gmsd` 掌握这些方法的选择。 请参看 @ blazediff/ matcher |
| `runInWorker` | 布尔 | 真实 | 运行工人线条的比较,以提高业绩 |

见 [@ blazediff/ marcher (英语)](https://www.npmjs.com/package/@blazediff/matcher) 用于完整选项文档.

## 用法图案

### 基本快照测试

```typescript
import { expect, it } from 'vitest';
import '@blazediff/vitest';

it('renders correctly', async () => {
  const screenshot = await page.screenshot();

  await expect(screenshot).toMatchImageSnapshot({
    method: 'core',
  });
});
```

### 不同的比较方法

```typescript
// Fast Rust-native comparison (paths, PNG buffers or raw images)
await expect('/path/to/image.png').toMatchImageSnapshot({
  method: 'core-native',
});

// Pure JavaScript comparison
await expect(imageBuffer).toMatchImageSnapshot({
  method: 'core',
});

// Perceptual similarity (SSIM)
await expect(imageBuffer).toMatchImageSnapshot({
  method: 'ssim',
});

// Gradient-based comparison
await expect(imageBuffer).toMatchImageSnapshot({
  method: 'gmsd',
});
```

### 更新快照

```bash
# Update all snapshots
vitest -u

# Update snapshots for specific test
vitest -u path/to/test.spec.ts

# Or using environment variable
VITEST_UPDATE_SNAPSHOTS=true vitest
```

或在方案方面:

```typescript
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  updateSnapshots: true,
});
```

### 自定义阈值

```typescript
// Allow up to 100 pixels difference
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  failureThreshold: 100,
  failureThresholdType: 'pixel',
});

// Allow up to 0.1% difference
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  failureThreshold: 0.1,
  failureThresholdType: 'percent',
});
```

### 自定义快照目录

```typescript
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotsDir: '__image_snapshots__',
});
```

### 自定义快照标识符

```typescript
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotIdentifier: 'homepage-desktop-chrome',
});
```

### 与剧作家

```typescript
import { test, expect } from 'vitest';
import '@blazediff/vitest';
import { chromium } from 'playwright';

test('visual regression with Playwright', async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  const screenshot = await page.screenshot();
  await expect(screenshot).toMatchImageSnapshot({
    method: 'core',
  });

  await browser.close();
});
```

### 否认

```typescript
// Assert images are different
await expect(screenshot).not.toMatchImageSnapshot({
  method: 'core',
});
```

### 序列测试

对于可能相互干扰的测试(如清理快照),使用相继执行:

```typescript
import { describe, it } from 'vitest';

describe.sequential('Visual regression tests', () => {
  it('test 1', async () => {
    await expect(image1).toMatchImageSnapshot({ method: 'core' });
  });

  it('test 2', async () => {
    await expect(image2).toMatchImageSnapshot({ method: 'core' });
  });
});
```

## 快照状态跟踪

这个匹配器与Vitest的快照状态跟踪系统相融合. Vitest将在测试摘要中报告准确的计数:

```
Snapshots  2 written | 1 updated | 5 passed
```

匹配者更新了Vitest的内部计数器:

-   **写入**: 创建了新快照
-   **更新**: 以 `-u` 旗帜
-   **通过**: 现有快照匹配
-   **失败**: 快照比较失败

## 设置

### 自动设置( 建议)

简单地导入测试文件中的软件包 :

```typescript
import '@blazediff/vitest';
```

匹配器在导入时自动注册.

### 手动设置

或者,明确调用设置函数:

```typescript
import { setupBlazediffMatchers } from '@blazediff/vitest';

setupBlazediffMatchers();
```

### 全球设置

为避免在每个测试文件中导入, 请在您的 Vitest 配置中添加 :

```typescript
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['./vitest.setup.ts'],
  },
});
```

```typescript
// vitest.setup.ts
import '@blazediff/vitest';
```

## 类型脚本

包含类型脚本。 要使用 TypeScript 的匹配器 :

```typescript
import '@blazediff/vitest';

declare module 'vitest' {
  interface Assertion<T = any> {
    toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<void>;
  }
}
```

在导入软件包时自动包含类型增强.

## 链接

-   [GitHub 仓库](https://github.com/teimurjan/blazediff)
-   [文档](https://blazediff.dev/docs/vitest)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@blazediff/vitest)
-   [@ blazediff/ marcher (英语)](https://www.npmjs.com/package/@blazediff/matcher) - 核心匹配者逻辑

## 常见问题

### @blazediff/vitest 是什么？

使用 blazediff 进行视觉回归测试的比对器

### 如何安装 @blazediff/vitest？

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

### @blazediff/vitest 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blazediff/vitest 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @blazediff/vitest 可以商用吗？

@blazediff/vitest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blazediff/vitest 的下载量有多少？

根据 npm 官方下载统计，@blazediff/vitest 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,436 次，日均约 215 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blazediff/vitest 还在维护吗？

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