@ blazediff/ bun (英语)

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

特征

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

安装

npm install --dev @blazediff/bun

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

快速启动

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测试匹配器,用于图像快照比较.

选项

见 @ blazediff/ marcher (英语) 用于完整选项文档.

用法图案

基本快照测试

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',
  });
});

不同的比较方法

// 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',
});

更新快照

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

# Or using environment variable
BUN_UPDATE_SNAPSHOTS=true bun test

或在方案方面:

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

自定义阈值

// 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',
});

自定义快照目录

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

与剧作家

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();
});

否认

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

序列测试

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

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数字 :

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

测试路径检测

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

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

设置

自动设置( 建议)

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

import '@blazediff/bun';

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

手动设置

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

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

setupBlazediffMatchers();

类型脚本

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

import '@blazediff/bun';

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

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

链接

• GitHub 仓库
• 文档
• 国家防范机制一揽子计划
• @ blazediff/ marcher (英语) - 核心匹配者逻辑