# @blazediff/bun 中文文档

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

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

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

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

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

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

## 中文简介

Bun 测试比对器, 用于用 blazediff 进行视觉回归测试

## 安装

```sh
npm install @blazediff/bun
```

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

## README

# @ blazediff/ bun (英语)

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

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

## 特征

-   **原装匹配器**数字 : `toMatchImageSnapshot()` 延长 Bun 的预期
-   **快照状态跟踪**: Bun 报告准确的快照数( 当 API 可用时)
-   **多重比较算法**数字 : `core`, (中文(简体) ), `core-native`, (中文(简体) ), `ssim`, (中文(简体) ), `msssim`, (中文(简体) ), `hitchhikers-ssim`, (中文(简体) ), `gmsd`
-   **自动设置**: 自动导入和登记
-   **更新模式**: 与 Bun 工作 `-u`编号 :`--update` 旗帜
-   **类型脚本支持**: 包括完整类型定义

## 安装

```bash
npm install --dev @blazediff/bun
```

**同伴依赖关系**(单位:千分之一)

## 快速启动

```typescript
import { expect, it } from 'bun:test';
import '@blazediff/bun';

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

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

## API 参考

### 到MatchImageSnapshot( 选项 )

Bun测试匹配器,用于图像快照比较.

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

#### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `method` | “ 核心 ” “ 核心内在 ” “ sim ” “ mssim ” “ hitchhikers ” “ gmsd ” | "核心" ("核心") | 要使用的比较算法 |
| `failureThreshold` | 编号 | 0 个 | 允许的像素数或百分比差异 |
| `failureThresholdType` | “ 像素”“%” | "像素"(像素) | 如何解释失败风险 |
| `snapshotsDir` | 字符串 | "... 弹出..." | 相对于测试文件存储快取目录 |
| `snapshotIdentifier` | 字符串 | "弹出" | 快取文件的标识符( Bun 需要) |
| `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 'bun:test';
import '@blazediff/bun';

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

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

### 不同的比较方法

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

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

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

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

### 更新快照

```bash
# Update all snapshots (recommended)
bun test --update-snapshots

# Or using environment variable
BUN_UPDATE_SNAPSHOTS=true bun test
```

或在方案方面:

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

### 自定义阈值

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

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

### 自定义快照目录

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

### 与剧作家

```typescript
import { test, expect } from 'bun:test';
import '@blazediff/bun';
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',
    snapshotIdentifier: 'homepage',
  });

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

### 否认

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

### 序列测试

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

```typescript
import { describe, it } from 'bun:test';

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

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

## 快照状态跟踪

这个匹配器试图与Bun的快照状态跟踪系统整合. 如果 Bun 将快照状态 API 暴露给自定义匹配者, 测试摘要将显示准确的计数 :

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

**说明**: Bun的快照状态API对于自定义匹配者是有限的. 如果快照状态不可用, 图像快照仍将正确工作, 但可能不会出现在 Bun 的测试摘要计数中 .

## Bun- Special 注释

### 需要抓图标识符

不像Jest和Vitest可以自动生成测试名称的快照标识,Bun的上下文曝光有限。 建议永远提供 `snapshotIdentifier`数字 :

```typescript
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotIdentifier: 'my-component-state', // Recommended
});
```

### 测试路径检测

Bun 提供 `Bun.main` 用于确定测试文件路径。 在一些边缘情况下,您可能需要指定 `snapshotsDir` 作为绝对路径 :

```typescript
await expect(screenshot).toMatchImageSnapshot({
  method: 'core',
  snapshotIdentifier: 'homepage',
  snapshotsDir: '/absolute/path/to/snapshots',
});
```

## 设置

### 自动设置( 建议)

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

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

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

### 手动设置

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

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

setupBlazediffMatchers();
```

## 类型脚本

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

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

declare module 'bun:test' {
  interface Matchers<T = unknown> {
    toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<MatcherResult>;
  }
}
```

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

## 链接

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

## 常见问题

### @blazediff/bun 是什么？

Bun 测试比对器, 用于用 blazediff 进行视觉回归测试

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

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

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

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

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

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

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

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

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

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

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

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