Bun test matcher for visual regression testing with blazediff
npm install @blazediff/bun

Bun test matcher for visual regression testing with blazediff. Powered by @blazediff/matcher with Bun-specific snapshot state integration.
- Native Bun matcher: toMatchImageSnapshot() extends Bun's expect
- Snapshot state tracking: Bun reports accurate snapshot counts (when API available)
- Multiple comparison algorithms: core, bin, ssim, msssim, hitchhikers-ssim, gmsd
- Auto-setup: Imports and registers automatically
- Update mode: Works with Bun's -u/--update flag
- TypeScript support: Full type definitions included
``bash`
npm install --dev @blazediff/bun
Peer dependencies: Bun >= 1.0.0
`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',
});
});
`
Bun test matcher for image snapshot comparison.
| Parameter | Type | Description |
|---|---|---|
options | Partial<MatcherOptions> | Optional comparison options (see below) |
#### Options
| Option | Type | Default | Description |
|---|---|---|---|
method | 'core' | 'bin' | 'ssim' | 'msssim' | 'hitchhikers-ssim' | 'gmsd' | 'core' | Comparison algorithm to use |
failureThreshold | number | 0 | Number of pixels or percentage difference allowed |
failureThresholdType | 'pixel' | 'percent' | 'pixel' | How to interpret failureThreshold |
snapshotsDir | string | '__snapshots__' | Directory to store snapshots relative to test file |
snapshotIdentifier | string | 'snapshot' | Identifier for the snapshot file (required for Bun) |
updateSnapshots | boolean | false | Force update snapshots |
threshold | number | 0.1 | Color difference threshold (0-1) for core/bin methods |
See @blazediff/matcher for full options documentation.
`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 (file paths only)
await expect('/path/to/image.png').toMatchImageSnapshot({
method: 'bin',
snapshotIdentifier: 'image-bin',
});
// 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',
});
`
`bashUpdate all snapshots (recommended)
bun test --update-snapshots
Or programmatically:
`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'homepage',
updateSnapshots: true,
});
`$3
`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',
});
`$3
`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'homepage',
snapshotsDir: '__image_snapshots__',
});
`$3
`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();
});
`$3
`typescript
// Assert images are different
await expect(screenshot).not.toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'different',
});
`$3
For tests that might interfere with each other (e.g., cleaning up snapshots), use serial execution:
`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',
});
});
});
`Snapshot State Tracking
This matcher attempts to integrate with Bun's snapshot state tracking system. If Bun exposes the snapshot state API to custom matchers, test summaries will show accurate counts:
`
Snapshots 2 written | 1 updated | 5 passed
`Note: Bun's snapshot state API for custom matchers is limited. If snapshot state is unavailable, image snapshots will still work correctly but may not appear in Bun's test summary counts.
Bun-Specific Notes
$3
Unlike Jest and Vitest which can auto-generate snapshot identifiers from test names, Bun has limited context exposure. It's recommended to always provide a
snapshotIdentifier:`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'my-component-state', // Recommended
});
`$3
Bun provides
Bun.main which is used to determine the test file path. In some edge cases, you may need to specify snapshotsDir as an absolute path:`typescript
await expect(screenshot).toMatchImageSnapshot({
method: 'core',
snapshotIdentifier: 'homepage',
snapshotsDir: '/absolute/path/to/snapshots',
});
`Setup
$3
Simply import the package in your test file:
`typescript
import '@blazediff/bun';
`The matcher is automatically registered when imported.
$3
Alternatively, call the setup function explicitly:
`typescript
import { setupBlazediffMatchers } from '@blazediff/bun';setupBlazediffMatchers();
`TypeScript
TypeScript types are included. To use the matcher with TypeScript:
`typescript
import '@blazediff/bun';declare module 'bun:test' {
interface Matchers {
toMatchImageSnapshot(options?: Partial): Promise;
}
}
``The type augmentation is automatically included when you import the package.
- GitHub Repository
- Documentation
- NPM Package
- @blazediff/matcher - Core matcher logic