@blazediff/bun 1.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Teimur Gasanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# @blazediff/bun
+
+<div align="center">
+
+[![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fbun)](https://www.npmjs.com/package/@blazediff/bun)
+[![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fbun)](https://www.npmjs.com/package/@blazediff/bun)
+
+</div>
+
+Bun test matcher for visual regression testing with blazediff. Powered by @blazediff/matcher with Bun-specific snapshot state integration.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install --dev @blazediff/bun
+```
+
+**Peer dependencies**: Bun >= 1.0.0
+
+## Quick Start
+
+```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 Reference
+
+### toMatchImageSnapshot(options?)
+
+Bun test matcher for image snapshot comparison.
+
+<table>
+  <tr>
+    <th width="500">Parameter</th>
+    <th width="500">Type</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>options</code></td>
+    <td>Partial&lt;MatcherOptions&gt;</td>
+    <td>Optional comparison options (see below)</td>
+  </tr>
+</table>
+
+#### Options
+
+<table>
+  <tr>
+    <th width="500">Option</th>
+    <th width="500">Type</th>
+    <th width="500">Default</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>method</code></td>
+    <td>'core' | 'bin' | 'ssim' | 'msssim' | 'hitchhikers-ssim' | 'gmsd'</td>
+    <td>'core'</td>
+    <td>Comparison algorithm to use</td>
+  </tr>
+  <tr>
+    <td><code>failureThreshold</code></td>
+    <td>number</td>
+    <td>0</td>
+    <td>Number of pixels or percentage difference allowed</td>
+  </tr>
+  <tr>
+    <td><code>failureThresholdType</code></td>
+    <td>'pixel' | 'percent'</td>
+    <td>'pixel'</td>
+    <td>How to interpret failureThreshold</td>
+  </tr>
+  <tr>
+    <td><code>snapshotsDir</code></td>
+    <td>string</td>
+    <td>'__snapshots__'</td>
+    <td>Directory to store snapshots relative to test file</td>
+  </tr>
+  <tr>
+    <td><code>snapshotIdentifier</code></td>
+    <td>string</td>
+    <td>'snapshot'</td>
+    <td>Identifier for the snapshot file (required for Bun)</td>
+  </tr>
+  <tr>
+    <td><code>updateSnapshots</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Force update snapshots</td>
+  </tr>
+  <tr>
+    <td><code>threshold</code></td>
+    <td>number</td>
+    <td>0.1</td>
+    <td>Color difference threshold (0-1) for core/bin methods</td>
+  </tr>
+</table>
+
+See [@blazediff/matcher](https://www.npmjs.com/package/@blazediff/matcher) for full options documentation.
+
+## Usage Patterns
+
+### Basic Snapshot Test
+
+```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',
+  });
+});
+```
+
+### Different Comparison Methods
+
+```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',
+});
+```
+
+### Update Snapshots
+
+```bash
+# Update all snapshots
+bun test -u
+
+# Or
+bun test --update
+```
+
+Or programmatically:
+
+```typescript
+await expect(screenshot).toMatchImageSnapshot({
+  method: 'core',
+  snapshotIdentifier: 'homepage',
+  updateSnapshots: true,
+});
+```
+
+### Custom Thresholds
+
+```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',
+});
+```
+
+### Custom Snapshot Directory
+
+```typescript
+await expect(screenshot).toMatchImageSnapshot({
+  method: 'core',
+  snapshotIdentifier: 'homepage',
+  snapshotsDir: '__image_snapshots__',
+});
+```
+
+### With Playwright
+
+```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();
+});
+```
+
+### Negation
+
+```typescript
+// Assert images are different
+await expect(screenshot).not.toMatchImageSnapshot({
+  method: 'core',
+  snapshotIdentifier: 'different',
+});
+```
+
+### Serial Tests
+
+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
+
+### Snapshot Identifier Required
+
+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
+});
+```
+
+### Test Path Detection
+
+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
+
+### Auto-setup (Recommended)
+
+Simply import the package in your test file:
+
+```typescript
+import '@blazediff/bun';
+```
+
+The matcher is automatically registered when imported.
+
+### Manual Setup
+
+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<T = unknown> {
+    toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<MatcherResult>;
+  }
+}
+```
+
+The type augmentation is automatically included when you import the package.
+
+## Links
+
+- [GitHub Repository](https://github.com/teimurjan/blazediff)
+- [Documentation](https://blazediff.dev/docs/bun)
+- [NPM Package](https://www.npmjs.com/package/@blazediff/bun)
+- [@blazediff/matcher](https://www.npmjs.com/package/@blazediff/matcher) - Core matcher logic

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import { MatcherOptions } from '@blazediff/matcher';
+export { ComparisonResult, ImageInput, MatcherOptions } from '@blazediff/matcher';
+
+declare module "bun:test" {
+    interface Matchers<T> {
+        /**
+         * Compare an image against a stored snapshot.
+         *
+         * On first run, creates a new snapshot.
+         * On subsequent runs, compares against the stored snapshot.
+         *
+         * @param options - Matcher options including comparison method and thresholds
+         *
+         * @example
+         * ```typescript
+         * // Compare file path
+         * await expect('/path/to/screenshot.png').toMatchImageSnapshot({
+         *   method: 'bin',
+         *   failureThreshold: 100,
+         *   failureThresholdType: 'pixel',
+         * });
+         *
+         * // Compare image buffer
+         * await expect({
+         *   data: imageBuffer,
+         *   width: 800,
+         *   height: 600
+         * }).toMatchImageSnapshot({
+         *   method: 'ssim',
+         *   failureThreshold: 0.01,
+         *   failureThresholdType: 'percent',
+         * });
+         * ```
+         */
+        toMatchImageSnapshot(options?: Partial<MatcherOptions>): Promise<T>;
+    }
+    interface AsymmetricMatchers {
+        toMatchImageSnapshot(options?: Partial<MatcherOptions>): void;
+    }
+}
+
+/**
+ * Setup blazediff matchers for Bun test
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupBlazediffMatchers } from '@blazediff/bun';
+ * setupBlazediffMatchers();
+ *
+ * // Or just import the package (auto-setup)
+ * import '@blazediff/bun';
+ * ```
+ */
+declare function setupBlazediffMatchers(): void;
+
+export { setupBlazediffMatchers as default, setupBlazediffMatchers };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { MatcherOptions } from '@blazediff/matcher';
+export { ComparisonResult, ImageInput, MatcherOptions } from '@blazediff/matcher';
+
+declare module "bun:test" {
+    interface Matchers<T> {
+        /**
+         * Compare an image against a stored snapshot.
+         *
+         * On first run, creates a new snapshot.
+         * On subsequent runs, compares against the stored snapshot.
+         *
+         * @param options - Matcher options including comparison method and thresholds
+         *
+         * @example
+         * ```typescript
+         * // Compare file path
+         * await expect('/path/to/screenshot.png').toMatchImageSnapshot({
+         *   method: 'bin',
+         *   failureThreshold: 100,
+         *   failureThresholdType: 'pixel',
+         * });
+         *
+         * // Compare image buffer
+         * await expect({
+         *   data: imageBuffer,
+         *   width: 800,
+         *   height: 600
+         * }).toMatchImageSnapshot({
+         *   method: 'ssim',
+         *   failureThreshold: 0.01,
+         *   failureThresholdType: 'percent',
+         * });
+         * ```
+         */
+        toMatchImageSnapshot(options?: Partial<MatcherOptions>): Promise<T>;
+    }
+    interface AsymmetricMatchers {
+        toMatchImageSnapshot(options?: Partial<MatcherOptions>): void;
+    }
+}
+
+/**
+ * Setup blazediff matchers for Bun test
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupBlazediffMatchers } from '@blazediff/bun';
+ * setupBlazediffMatchers();
+ *
+ * // Or just import the package (auto-setup)
+ * import '@blazediff/bun';
+ * ```
+ */
+declare function setupBlazediffMatchers(): void;
+
+export { setupBlazediffMatchers as default, setupBlazediffMatchers };

package/dist/index.js

@@ -0,0 +1,2 @@
+'use strict';Object.defineProperty(exports,'__esModule',{value:true});var bun_test=require('bun:test'),matcher=require('@blazediff/matcher');function r(){bun_test.expect.extend({toMatchImageSnapshot:async function(o,e){let a=i(),c=e?.snapshotIdentifier||"snapshot",p=e?.updateSnapshots||process.env.UPDATE_SNAPSHOTS==="true"||Bun.argv.includes("-u")||Bun.argv.includes("--update"),s=await matcher.getOrCreateSnapshot(o,{method:"core",...e,updateSnapshots:p},{testPath:a,testName:c}),t=this.snapshotState;if(t&&s.snapshotStatus)switch(s.snapshotStatus){case "added":t.added=(t.added||0)+1;break;case "updated":t.updated=(t.updated||0)+1;break;case "matched":t.matched=(t.matched||0)+1;break;case "failed":t.unmatched=(t.unmatched||0)+1;break}return {pass:s.pass,message:()=>s.message}}});}function i(){if(typeof Bun<"u"&&Bun.main)return Bun.main;let n=new Error().stack;if(n){let o=n.split(`
+`);for(let e of o){let a=e.match(/at\s+(.+\.test\.[tj]s)/);if(a)return a[1]}}return "unknown"}r();var f=r;exports.default=f;exports.setupBlazediffMatchers=r;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import {expect}from'bun:test';import {getOrCreateSnapshot}from'@blazediff/matcher';function r(){expect.extend({toMatchImageSnapshot:async function(o,e){let a=i(),c=e?.snapshotIdentifier||"snapshot",p=e?.updateSnapshots||process.env.UPDATE_SNAPSHOTS==="true"||Bun.argv.includes("-u")||Bun.argv.includes("--update"),s=await getOrCreateSnapshot(o,{method:"core",...e,updateSnapshots:p},{testPath:a,testName:c}),t=this.snapshotState;if(t&&s.snapshotStatus)switch(s.snapshotStatus){case "added":t.added=(t.added||0)+1;break;case "updated":t.updated=(t.updated||0)+1;break;case "matched":t.matched=(t.matched||0)+1;break;case "failed":t.unmatched=(t.unmatched||0)+1;break}return {pass:s.pass,message:()=>s.message}}});}function i(){if(typeof Bun<"u"&&Bun.main)return Bun.main;let n=new Error().stack;if(n){let o=n.split(`
+`);for(let e of o){let a=e.match(/at\s+(.+\.test\.[tj]s)/);if(a)return a[1]}}return "unknown"}r();var f=r;export{f as default,r as setupBlazediffMatchers};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@blazediff/bun",
+  "version": "1.0.1",
+  "description": "Bun test matcher for visual regression testing with blazediff",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "bun",
+    "image",
+    "comparison",
+    "diff",
+    "visual-testing",
+    "matcher",
+    "snapshot"
+  ],
+  "author": "Teimur Gasanov <me@teimurjan.dev> (https://github.com/teimurjan)",
+  "repository": "https://github.com/teimurjan/blazediff",
+  "homepage": "https://blazediff.dev",
+  "license": "MIT",
+  "dependencies": {
+    "@blazediff/matcher": "1.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.10",
+    "@types/node": "^24.3.0",
+    "tsup": "8.5.0",
+    "typescript": "5.9.2"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "test": "bun test"
+  }
+}