vitest-plugin-vis 3.2.0 → 3.3.0

package/esm/client-api.d.ts

@@ -6,6 +6,7 @@ export * from './client/actions/match_page_image_snapshot_action.ts';
 export { setAutoSnapshotOptions, type MetaTask } from './client/auto_snapshot_options.ts';
 export * from './client/expect/expectation_result.ts';
 export type * from './client/expect/to_match_image_snapshot.types.ts';
+export * from './client/setup/create_vis.ts';
 export * from './client/task_id.ts';
 export * from './shared/constants.ts';
 export type * from './shared/types.ts';

package/esm/client-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-api.d.ts","sourceRoot":"","sources":["../src/client-api.ts"],"names":[],"mappings":"AAAA,OAAO,8BAA8B,CAAA;AAErC,cAAc,+CAA+C,CAAA;AAC7D,cAAc,wDAAwD,CAAA;AACtE,cAAc,iDAAiD,CAAA;AAC/D,cAAc,sDAAsD,CAAA;AACpE,OAAO,EAAE,sBAAsB,EAAE,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAA;AACzF,cAAc,uCAAuC,CAAA;AACrD,mBAAmB,kDAAkD,CAAA;AACrE,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,mBAAmB,mBAAmB,CAAA"}
+{"version":3,"file":"client-api.d.ts","sourceRoot":"","sources":["../src/client-api.ts"],"names":[],"mappings":"AAAA,OAAO,8BAA8B,CAAA;AAErC,cAAc,+CAA+C,CAAA;AAC7D,cAAc,wDAAwD,CAAA;AACtE,cAAc,iDAAiD,CAAA;AAC/D,cAAc,sDAAsD,CAAA;AACpE,OAAO,EAAE,sBAAsB,EAAE,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAA;AACzF,cAAc,uCAAuC,CAAA;AACrD,mBAAmB,kDAAkD,CAAA;AACrE,cAAc,8BAA8B,CAAA;AAC5C,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,mBAAmB,mBAAmB,CAAA"}

package/esm/client-api.js

@@ -5,5 +5,6 @@ export * from "./client/actions/match_image_snapshot_action.js";
 export * from "./client/actions/match_page_image_snapshot_action.js";
 export { setAutoSnapshotOptions } from "./client/auto_snapshot_options.js";
 export * from "./client/expect/expectation_result.js";
+export * from "./client/setup/create_vis.js";
 export * from "./client/task_id.js";
 export * from "./shared/constants.js";

package/esm/config/types.d.ts

@@ -16,12 +16,14 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
     /**
      * Loads the `test.setupFiles` of the specified preset.
      *
-     * Note: 'enable` is deprecated. Use `manual` for the same effect.
+     * Note:
+     * - 'enable` is deprecated. Use `manual` for the same effect.
+     * - 'none` is deprecated. Use `custom` for the same effect.
      *
      * @default 'auto'
      *
      */
-    preset?: 'enable' | 'manual' | 'auto' | 'none' | undefined;
+    preset?: 'enable' | 'manual' | 'auto' | 'custom' | 'none' | undefined;
     /**
      * The snapshot folder relative to the root of the project.
      *

package/esm/config/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,MAAM,oBAAoB,CAAA;AAE3B,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,CAAA;AAElH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,gBAAgB,GAAG,OAAO,IAAI,CAAC,CAAC,SAAS,MAAM,GAC7E;IACA,gBAAgB,EAAE,CAAC,CAAA;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;CAClD,GACA;IACA,gBAAgB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;CAC1C,CAAC,GACH,uBAAuB,GACvB,2BAA2B,GAC3B,uBAAuB,GACvB,2BAA2B,GAAG;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAC1D;;;;OAIG;IACH,eAAe,CAAC,EACb,MAAM,GACN,CAAC,CAAC,OAAO,EAAE;QACX,EAAE,EAAE,OAAO,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACxC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KACvC,KAAK,MAAM,CAAC,GACb,SAAS,CAAA;IACZ;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;CACxE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,MAAM,oBAAoB,CAAA;AAE3B,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,CAAA;AAElH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,gBAAgB,GAAG,OAAO,IAAI,CAAC,CAAC,SAAS,MAAM,GAC7E;IACA,gBAAgB,EAAE,CAAC,CAAA;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;CAClD,GACA;IACA,gBAAgB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;CAC1C,CAAC,GACH,uBAAuB,GACvB,2BAA2B,GAC3B,uBAAuB,GACvB,2BAA2B,GAAG;IAC7B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAA;IACrE;;;;OAIG;IACH,eAAe,CAAC,EACb,MAAM,GACN,CAAC,CAAC,OAAO,EAAE;QACX,EAAE,EAAE,OAAO,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QAChC,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,kBAAkB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;QACxC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KACvC,KAAK,MAAM,CAAC,GACb,SAAS,CAAA;IACZ;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC,GAAG,SAAS,CAAA;CACxE,CAAA"}

package/esm/config/vis.js

@@ -19,7 +19,7 @@ export function vis(options = { preset: 'auto' }) {
                         name: undefined,
                         commands,
                     },
-                    setupFiles: preset && preset !== 'none' ? [`vitest-plugin-vis/presets/${preset}`] : [],
+                    setupFiles: preset && preset !== 'none' && preset !== 'custom' ? [`vitest-plugin-vis/presets/${preset}`] : [],
                 },
             };
         },

package/esm/server/snapshot_path.d.ts

@@ -1,6 +1,14 @@
 import type { VisOptions } from '../config/types.ts';
 import type { PartialBrowserCommandContext } from './vis_server_context.types.ts';
 export declare function resolveSnapshotRootDir(browserCommandContext: PartialBrowserCommandContext, options: VisOptions): string;
-export declare function getSnapshotRootDir(snapshotRootDir: string): string;
+/**
+ * Gets the root directory for storing snapshots.
+ *
+ * @param snapshotRootDir - Base directory for snapshots. Defaults to `__vis__`.
+ * @returns The full snapshot root directory path, which includes a platform-specific subdirectory:
+ * - When running in CI: `<snapshotRootDir>/<platform>` (e.g. `__vis__/linux`)
+ * - When running locally: `<snapshotRootDir>/local`
+ */
+export declare function getSnapshotRootDir(snapshotRootDir?: string): string;
 export declare function getSnapshotSubpath(suiteName: string, options: Pick<VisOptions, 'snapshotSubpath'>): string;
 //# sourceMappingURL=snapshot_path.d.ts.map

package/esm/server/snapshot_path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot_path.d.ts","sourceRoot":"","sources":["../../src/server/snapshot_path.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAGpD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAEjF,wBAAgB,sBAAsB,CAAC,qBAAqB,EAAE,4BAA4B,EAAE,OAAO,EAAE,UAAU,UAY9G;AAED,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,UAEzD;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,UAGjG"}
+{"version":3,"file":"snapshot_path.d.ts","sourceRoot":"","sources":["../../src/server/snapshot_path.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAGpD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAEjF,wBAAgB,sBAAsB,CAAC,qBAAqB,EAAE,4BAA4B,EAAE,OAAO,EAAE,UAAU,UAY9G;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,SAAoB,UAErE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,UAGjG"}

package/esm/server/snapshot_path.js

@@ -17,7 +17,15 @@ export function resolveSnapshotRootDir(browserCommandContext, options) {
         screenshotDirectory: browserCommandContext.provider.options?.screenshotDirectory,
     });
 }
-export function getSnapshotRootDir(snapshotRootDir) {
+/**
+ * Gets the root directory for storing snapshots.
+ *
+ * @param snapshotRootDir - Base directory for snapshots. Defaults to `__vis__`.
+ * @returns The full snapshot root directory path, which includes a platform-specific subdirectory:
+ * - When running in CI: `<snapshotRootDir>/<platform>` (e.g. `__vis__/linux`)
+ * - When running locally: `<snapshotRootDir>/local`
+ */
+export function getSnapshotRootDir(snapshotRootDir = SNAPSHOT_ROOT_DIR) {
     return `${snapshotRootDir}/${ci ? platform : 'local'}`;
 }
 export function getSnapshotSubpath(suiteName, options) {

package/esm/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AACA,OAAO,2BAA2B,CAAA;AAClC,OAAO,yBAAyB,CAAA;AAEhC,cAAc,uBAAuB,CAAA;AAIrC,cAAc,8BAA8B,CAAA"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AACA,OAAO,2BAA2B,CAAA;AAClC,OAAO,yBAAyB,CAAA;AAEhC,cAAc,uBAAuB,CAAA;AAGrC,cAAc,8BAA8B,CAAA"}

package/esm/setup.js

@@ -2,6 +2,5 @@
 import "./client/expect/extend.js";
 import "./client/page/extend.js";
 export * from "./client/setup/vis.js";
-// This is exported for main/app boundary separation
-// They can co-exist in the same export file thanks to ESM.
+// This is deprecated and moved to `/client-api`.
 export * from "./client/setup/create_vis.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -80,22 +80,31 @@
     "type-plus": "8.0.0-beta.7"
   },
   "devDependencies": {
+    "@repobuddy/storybook": "^1.0.0",
     "@repobuddy/typescript": "^2.1.0",
+    "@storybook/addon-docs": "^9.0.4",
+    "@storybook/addon-vitest": "^9.0.4",
+    "@storybook/react-vite": "^9.0.4",
+    "@tailwindcss/vite": "^4.1.7",
     "@types/is-ci": "^3.0.4",
     "@types/pngjs": "^6.0.5",
     "@types/react": "^18.2.65",
-    "@vitest/browser": "^3.0.9",
-    "@vitest/coverage-istanbul": "^3.0.9",
-    "@vitest/coverage-v8": "^3.0.9",
-    "@vitest/expect": "^3.0.9",
+    "@vitest/browser": "^3.1.4",
+    "@vitest/coverage-istanbul": "^3.1.4",
+    "@vitest/coverage-v8": "^3.1.4",
+    "@vitest/expect": "^3.1.4",
     "cross-env": "^7.0.3",
     "never-fail": "^1.1.4",
     "npm-run-all2": "^8.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "storybook": "^9.0.4",
+    "storybook-addon-tag-badges": "^2.0.0",
+    "storybook-dark-mode2": "^5.0.2",
+    "tailwindcss": "^4.1.7",
     "typescript": "^5.7.2",
     "vite": "^6.2.3",
-    "vitest": "^3.0.9",
+    "vitest": "^3.1.4",
     "vitest-browser-react": "^0.2.0"
   },
   "peerDependencies": {
@@ -114,6 +123,7 @@
     "coverage": "cross-env COVERAGE=true vitest run --coverage",
     "dev": "run-p build:watch w",
     "nuke": "rimraf node_modules",
+    "sb": "storybook dev -p 6007",
     "t:node": "vitest --project=vpv:node",
     "t:pw": "vitest run --project=\"vpv:pw (*)\"",
     "t:wd": "vitest run --project=\"vpv:wd (*)\"",

package/src/changelog.mdx

@@ -0,0 +1,6 @@
+import { Meta, Markdown } from "@storybook/addon-docs/blocks";
+import changelog from "../CHANGELOG.md?raw";
+
+<Meta title="Changelog" />
+
+<Markdown>{changelog}</Markdown>

package/src/client/auto_snapshot_options.mdx

@@ -0,0 +1,255 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { setAutoSnapshotOptions } from '../index'
+
+<Meta title="vitest-plugin-vis/setAutoSnapshotOptions" />
+
+# setAutoSnapshotOptions
+
+A function to configure visual snapshot testing options for the current test or test suite.
+
+## Usage
+
+You can use `setAutoSnapshotOptions` in `beforeAll`, `beforeEach`, or individual test cases to control snapshot behavior:
+
+```ts
+import { setAutoSnapshotOptions } from 'vitest-plugin-vis'
+
+beforeAll(() => {
+	setAutoSnapshotOptions(...)
+})
+
+beforeEach(() => {
+	setAutoSnapshotOptions(...)
+})
+
+// Set options for a specific test
+it('...', () => {
+	setAutoSnapshotOptions(...)
+})
+```
+
+## Options
+
+The function accepts either a boolean value or an options object with the following properties:
+
+### Basic Control
+
+#### `enable` (boolean)
+Controls whether auto snapshots are enabled for the test.
+
+```ts
+// Enable auto snapshots
+setAutoSnapshotOptions({ enable: true })
+
+// Disable auto snapshots
+setAutoSnapshotOptions({ enable: false })
+
+// Shorthand for enable: true
+setAutoSnapshotOptions(true)
+
+// Shorthand for enable: false
+setAutoSnapshotOptions(false)
+```
+
+### Subject Selection
+
+#### `subject` (string)
+Specifies the CSS selector for the element to snapshot. If not provided or element not found, defaults to `document.body`.
+
+```ts
+// Snapshot a specific element
+setAutoSnapshotOptions({
+  subject: '[data-testid="main-content"]'
+})
+
+// Snapshot by class name
+setAutoSnapshotOptions({
+  subject: '.my-component'
+})
+
+// Snapshot by ID
+setAutoSnapshotOptions({
+  subject: '#app-container'
+})
+```
+
+### Snapshot Identification
+
+#### `snapshotKey` (string)
+Customizes the snapshot key/name for the test.
+
+```ts
+// Custom snapshot key
+setAutoSnapshotOptions({
+  snapshotKey: 'my-custom-snapshot'
+})
+
+// Dynamic snapshot key based on test data
+setAutoSnapshotOptions({
+  snapshotKey: `user-profile-${userId}`
+})
+```
+
+### Timing Options
+
+#### `timeout` (number)
+Sets the timeout for taking the snapshot in milliseconds. Default is 30000ms (30 seconds).
+
+```ts
+// Set custom timeout
+setAutoSnapshotOptions({
+  timeout: 60000 // 60 seconds
+})
+
+// Quick timeout for fast tests
+setAutoSnapshotOptions({
+  timeout: 5000 // 5 seconds
+})
+```
+
+### Comparison Methods
+
+#### `comparisonMethod` ('pixel' | 'ssim')
+Specifies the algorithm used for image comparison.
+
+```ts
+// Use pixel-based comparison (default)
+setAutoSnapshotOptions({
+  comparisonMethod: 'pixel'
+})
+
+// Use SSIM (Structural Similarity Index) comparison
+setAutoSnapshotOptions({
+  comparisonMethod: 'ssim'
+})
+```
+
+### Failure Thresholds
+
+#### `failureThreshold` (number)
+Sets the tolerance level for differences before considering a test failed.
+
+```ts
+// Allow 5% difference
+setAutoSnapshotOptions({
+  failureThreshold: 0.05,
+  failureThresholdType: 'percent'
+})
+
+// Allow 100 different pixels
+setAutoSnapshotOptions({
+  failureThreshold: 100,
+  failureThresholdType: 'pixel'
+})
+```
+
+#### `failureThresholdType` ('pixel' | 'percent')
+Specifies whether the failure threshold is measured in pixels or percentage. Default is 'pixel'.
+
+```ts
+// Threshold as percentage
+setAutoSnapshotOptions({
+  failureThreshold: 2.5,
+  failureThresholdType: 'percent'
+})
+
+// Threshold as pixel count (default)
+setAutoSnapshotOptions({
+  failureThreshold: 50,
+  failureThresholdType: 'pixel'
+})
+```
+
+### Diff Options
+
+#### `diffOptions` (object)
+Provides custom options for the comparison algorithm.
+
+For pixel comparison (using pixelmatch):
+```ts
+setAutoSnapshotOptions({
+  comparisonMethod: 'pixel',
+  diffOptions: {
+    threshold: 0.1,        // Matching threshold (0-1)
+    includeAA: false,      // Include anti-aliased pixels
+    alpha: 0.1,            // Blending factor of unchanged pixels
+    aaColor: [255, 255, 0], // Color of anti-aliased pixels
+    diffColor: [255, 0, 255] // Color of different pixels
+  }
+})
+```
+
+For SSIM comparison:
+```ts
+setAutoSnapshotOptions({
+  comparisonMethod: 'ssim',
+  diffOptions: {
+    ssim: 'fast',          // 'fast', 'original', or 'bezkrovny'
+    windowSize: 11,        // Window size for SSIM calculation
+    k1: 0.01,             // Algorithm parameter
+    k2: 0.03              // Algorithm parameter
+  }
+})
+```
+
+### Testing Options
+
+#### `expectToFail` (boolean)
+Expects the snapshot comparison to fail. Useful for testing error conditions.
+
+```ts
+// Expect this snapshot to fail
+setAutoSnapshotOptions({
+  expectToFail: true
+})
+```
+
+## Complete Examples
+
+### Basic Setup
+```ts
+beforeEach(() => {
+  setAutoSnapshotOptions({
+    enable: true,
+    subject: '[data-testid="app"]',
+    timeout: 10000
+  })
+})
+```
+
+### High-Precision SSIM Comparison
+```ts
+it('should match with high precision', () => {
+  setAutoSnapshotOptions({
+    comparisonMethod: 'ssim',
+    diffOptions: { ssim: 'bezkrovny' },
+    failureThreshold: 0.01,
+    failureThresholdType: 'percent'
+  })
+})
+```
+
+### Pixel-Perfect Comparison
+```ts
+it('should be pixel perfect', () => {
+  setAutoSnapshotOptions({
+    comparisonMethod: 'pixel',
+    diffOptions: { threshold: 0 },
+    failureThreshold: 0,
+    failureThresholdType: 'pixel'
+  })
+})
+```
+
+### Custom Subject with Tolerance
+```ts
+it('should snapshot modal with tolerance', () => {
+  setAutoSnapshotOptions({
+    subject: '[data-testid="modal"]',
+    failureThreshold: 5,
+    failureThresholdType: 'percent',
+    snapshotKey: 'modal-open'
+  })
+})
+```
+