@blazediff/vitest 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,339 @@
+# @blazediff/vitest
+
+<div align="center">
+
+[![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fvitest)](https://www.npmjs.com/package/@blazediff/vitest)
+[![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fvitest)](https://www.npmjs.com/package/@blazediff/vitest)
+
+</div>
+
+Vitest matcher for visual regression testing with blazediff. Powered by @blazediff/matcher with Vitest-specific snapshot state integration.
+
+## Features
+
+- **Native Vitest matcher**: `toMatchImageSnapshot()` extends Vitest's expect
+- **Snapshot state tracking**: Vitest reports accurate snapshot counts (added/matched/updated/failed)
+- **Multiple comparison algorithms**: `core`, `bin`, `ssim`, `msssim`, `hitchhikers-ssim`, `gmsd`
+- **Auto-setup**: Imports and registers automatically
+- **Update mode**: Works with Vitest's `-u` flag
+- **TypeScript support**: Full type definitions included
+
+## Installation
+
+```bash
+npm install --save-dev @blazediff/vitest
+```
+
+**Peer dependencies**: Vitest >= 1.0.0
+
+## Quick Start
+
+```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 Reference
+
+### toMatchImageSnapshot(options?)
+
+Vitest 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>auto-generated</td>
+    <td>Custom identifier for the snapshot file</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 'vitest';
+import '@blazediff/vitest';
+
+it('renders correctly', async () => {
+  const screenshot = await page.screenshot();
+
+  await expect(screenshot).toMatchImageSnapshot({
+    method: 'core',
+  });
+});
+```
+
+### Different Comparison Methods
+
+```typescript
+// Fast Rust-native comparison (file paths only)
+await expect('/path/to/image.png').toMatchImageSnapshot({
+  method: 'bin',
+});
+
+// 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',
+});
+```
+
+### Update Snapshots
+
+```bash
+# Update all snapshots
+vitest -u
+
+# Update snapshots for specific test
+vitest -u path/to/test.spec.ts
+```
+
+Or programmatically:
+
+```typescript
+await expect(screenshot).toMatchImageSnapshot({
+  method: 'core',
+  updateSnapshots: true,
+});
+```
+
+### Custom Thresholds
+
+```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',
+});
+```
+
+### Custom Snapshot Directory
+
+```typescript
+await expect(screenshot).toMatchImageSnapshot({
+  method: 'core',
+  snapshotsDir: '__image_snapshots__',
+});
+```
+
+### Custom Snapshot Identifier
+
+```typescript
+await expect(screenshot).toMatchImageSnapshot({
+  method: 'core',
+  snapshotIdentifier: 'homepage-desktop-chrome',
+});
+```
+
+### With Playwright
+
+```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();
+});
+```
+
+### Negation
+
+```typescript
+// Assert images are different
+await expect(screenshot).not.toMatchImageSnapshot({
+  method: 'core',
+});
+```
+
+### Sequential Tests
+
+For tests that might interfere with each other (e.g., cleaning up snapshots), use sequential execution:
+
+```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' });
+  });
+});
+```
+
+## Snapshot State Tracking
+
+This matcher integrates with Vitest's snapshot state tracking system. Vitest will report accurate counts in test summaries:
+
+```
+Snapshots  2 written | 1 updated | 5 passed
+```
+
+The matcher updates Vitest's internal counters:
+- **Written**: New snapshots created
+- **Updated**: Snapshots updated with `-u` flag
+- **Passed**: Existing snapshots matched
+- **Failed**: Snapshot comparisons failed
+
+## Setup
+
+### Auto-setup (Recommended)
+
+Simply import the package in your test file:
+
+```typescript
+import '@blazediff/vitest';
+```
+
+The matcher is automatically registered when imported.
+
+### Manual Setup
+
+Alternatively, call the setup function explicitly:
+
+```typescript
+import { setupBlazediffMatchers } from '@blazediff/vitest';
+
+setupBlazediffMatchers();
+```
+
+### Global Setup
+
+To avoid importing in every test file, add to your Vitest config:
+
+```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 types are included. To use the matcher with TypeScript:
+
+```typescript
+import '@blazediff/vitest';
+
+declare module 'vitest' {
+  interface Assertion<T = any> {
+    toMatchImageSnapshot(options?: Partial<import('@blazediff/matcher').MatcherOptions>): Promise<void>;
+  }
+}
+```
+
+The type augmentation is automatically included when you import the package.
+
+## Links
+
+- [GitHub Repository](https://github.com/teimurjan/blazediff)
+- [Documentation](https://blazediff.dev/docs/vitest)
+- [NPM Package](https://www.npmjs.com/package/@blazediff/vitest)
+- [@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 "vitest" {
+    interface Matchers<T = any> {
+        /**
+         * 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 Vitest
+ *
+ * @example
+ * ```typescript
+ * // In your vitest setup file or test file
+ * import { setupBlazediffMatchers } from '@blazediff/vitest';
+ * setupBlazediffMatchers();
+ *
+ * // Or just import the package (auto-setup)
+ * import '@blazediff/vitest';
+ * ```
+ */
+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 "vitest" {
+    interface Matchers<T = any> {
+        /**
+         * 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 Vitest
+ *
+ * @example
+ * ```typescript
+ * // In your vitest setup file or test file
+ * import { setupBlazediffMatchers } from '@blazediff/vitest';
+ * setupBlazediffMatchers();
+ *
+ * // Or just import the package (auto-setup)
+ * import '@blazediff/vitest';
+ * ```
+ */
+declare function setupBlazediffMatchers(): void;
+
+export { setupBlazediffMatchers as default, setupBlazediffMatchers };

package/dist/index.js

@@ -0,0 +1 @@
+'use strict';Object.defineProperty(exports,'__esModule',{value:true});var matcher=require('@blazediff/matcher'),vitest=require('vitest');function n(){vitest.expect.extend({async toMatchImageSnapshot(r,s){let p=this.testPath||"",a=this.currentTestName||"unknown",t=this.snapshotState,c=s?.updateSnapshots||t?._updateSnapshot==="all"||process.env.UPDATE_SNAPSHOTS==="true",e=await matcher.getOrCreateSnapshot(r,{method:"core",...s,updateSnapshots:c},{testPath:p,testName:a});if(t&&e.snapshotStatus)switch(e.snapshotStatus){case "added":t.added.increment(a),t._dirty=true;break;case "updated":t.updated.increment(a),t._dirty=true;break;case "matched":t.matched.increment(a);break;case "failed":t.unmatched.increment(a);break}return {pass:e.pass,message:()=>e.message,actual:e.receivedPath,expected:e.baselinePath}}});}n();var m=n;exports.default=m;exports.setupBlazediffMatchers=n;

package/dist/index.mjs

@@ -0,0 +1 @@
+import {getOrCreateSnapshot}from'@blazediff/matcher';import {expect}from'vitest';function n(){expect.extend({async toMatchImageSnapshot(r,s){let p=this.testPath||"",a=this.currentTestName||"unknown",t=this.snapshotState,c=s?.updateSnapshots||t?._updateSnapshot==="all"||process.env.UPDATE_SNAPSHOTS==="true",e=await getOrCreateSnapshot(r,{method:"core",...s,updateSnapshots:c},{testPath:p,testName:a});if(t&&e.snapshotStatus)switch(e.snapshotStatus){case "added":t.added.increment(a),t._dirty=true;break;case "updated":t.updated.increment(a),t._dirty=true;break;case "matched":t.matched.increment(a);break;case "failed":t.unmatched.increment(a);break}return {pass:e.pass,message:()=>e.message,actual:e.receivedPath,expected:e.baselinePath}}});}n();var m=n;export{m as default,n as setupBlazediffMatchers};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@blazediff/vitest",
+  "version": "1.0.1",
+  "description": "Vitest 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": [
+    "vitest",
+    "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/node": "^24.3.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "8.5.0",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "vitest": ">=1.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}