vitest-plugin-vis 1.0.0

package/esm/testing.d.ts

@@ -0,0 +1,2 @@
+export * from './testing/constants.ts';
+//# sourceMappingURL=testing.d.ts.map

package/esm/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA"}

package/esm/testing.js

@@ -0,0 +1 @@
+export * from "./testing/constants.js";

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "vitest-plugin-vis",
+  "version": "1.0.0",
+  "description": "Vitest visual testing plugin",
+  "keywords": [
+    "image-snapshot",
+    "vitest",
+    "visual-test"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/repobuddy/storybook-image-snapshot",
+    "directory": "packages/vitest-image-snapshot"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Homa Wong",
+    "email": "homawong@gmail.com",
+    "url": "https://github.com/unional"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./esm/index.d.ts",
+      "default": "./esm/index.js"
+    },
+    "./config": {
+      "types": "./esm/config.d.ts",
+      "default": "./esm/config.js"
+    },
+    "./client": {
+      "types": "./esm/client.d.ts",
+      "default": "./esm/client.js"
+    },
+    "./commands": {
+      "types": "./esm/commands.d.ts",
+      "default": "./esm/commands.js"
+    },
+    "./presets/auto": {
+      "types": "./esm/presets/auto.d.ts",
+      "default": "./esm/presets/auto.js"
+    },
+    "./presets/manual": {
+      "types": "./esm/presets/manual.d.ts",
+      "default": "./esm/presets/manual.js"
+    },
+    "./setup": {
+      "types": "./esm/setup.d.ts",
+      "default": "./esm/setup.js"
+    },
+    "./testing": {
+      "types": "./esm/testing.d.ts",
+      "default": "./esm/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "esm",
+    "src",
+    "!**/*.{spec,test,unit,accept,integrate,system,perf,stress}.*"
+  ],
+  "dependencies": {
+    "@types/pixelmatch": "^5.2.6",
+    "dedent": "^1.5.1",
+    "is-ci": "^4.0.0",
+    "mkdirp": "^3.0.1",
+    "pathe": "^1.1.2",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "rimraf": "^6.0.1",
+    "type-plus": "^8.0.0-beta.6"
+  },
+  "devDependencies": {
+    "@repobuddy/typescript": "^2.1.0",
+    "@types/is-ci": "^3.0.4",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.0.2",
+    "@vitest/browser": "^2.1.8",
+    "@vitest/coverage-istanbul": "^2.1.8",
+    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/expect": "^2.1.8",
+    "cross-env": "^7.0.3",
+    "npm-run-all2": "^7.0.2",
+    "playwright": "^1.49.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.2",
+    "vite": "^5.3.5",
+    "vitest": "^2.1.3",
+    "vitest-browser-react": "^0.0.4",
+    "webdriverio": "^9.4.1"
+  },
+  "peerDependencies": {
+    "@vitest/browser": "^2.1.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc -w",
+    "clean": "rimraf coverage esm *.tsbuildinfo vitest.*.timestamp*",
+    "cov": "cross-env COVERAGE=true vitest run --coverage",
+    "coverage": "cross-env COVERAGE=true vitest run --coverage",
+    "dev": "run-p build:watch w",
+    "nuke": "rimraf node_modules",
+    "test": "vitest run",
+    "v": "run-p build cov",
+    "w": "vitest",
+    "w:cov": "cross-env COVERAGE=true vitest --coverage",
+    "w:node": "vitest --project=vpv:node",
+    "w:pw": "vitest --project=vpv:pw",
+    "w:wd": "vitest --project=vpv:wd"
+  }
+}

package/readme.md

@@ -0,0 +1,264 @@
+# Vitest Visual Testing Plugin
+
+Vitest visual testing plugin allowing you to capture and compare image snapshots automatically and manually.
+
+It requires [Vitest Browser Mode][vitest-browser-mode] to work.
+
+This plugin is inspired by [`jest-image-snapshot`][jest-image-snapshot],
+and extracted from [`storybook-addon-vis`][storybook-addon-vis] for better modularity.
+
+## Install
+
+```sh
+npm install --save-dev vitest-plugin-vis
+
+pnpm add --save-dev vitest-plugin-vis
+
+yarn add --save-dev vitest-plugin-vis
+```
+
+## Config
+
+Vitest visual testing plugin supports zero-config setup.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+  plugins: [vis()],
+  test: {
+    browser: {
+      // typical browser config
+      enabled: true,
+      provider: 'playwright',
+      name: 'chromium'
+    }
+  }
+})
+```
+
+This default configuration will:
+
+- Use the `auto` preset, taking image snapshot at the end on each rendering test.
+- Set config to compare image snapshot with a failure threshold of `0 pixels`.
+- Local (non-CI) image snapshots are saved in the `<root>/__vis__/local` directory.
+- CI image snapshots are saved in the `<root>/__vis__/<process.platform>` directory.
+- Image snapshots of the current test run are saved in the `<root>/__vis__/__results__` directory.
+- Diff images are saved in the `<root>/__vis__/__diffs__` directory.
+
+You can customize the configuration:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+  plugins: [
+    vis({
+      preset: 'auto', // preset is disabled by default when you provide a custom config
+      snapshotRootDir: '__vis__',
+      customizeSnapshotSubpath: (subpath) => subpath,
+      customizeSnapshotId: (id, index) => `${id}-${index}`,
+      diffOptions: undefined, // pixelmatch options
+      failureThresholdType: 'pixel',
+      failureThreshold: 0,
+      timeout: 5000 // 30000 on CI
+    })
+  ],
+  test:{
+    browser:{/* ... */}
+  }
+})
+```
+
+If you want to do a custom snapshot at the end of each test,
+such as taking a snapshot for each theme,
+you can set it up using a custom setup file:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+  plugins: [
+    // preset is disabled by default when you provide a custom config
+    vis({}) // or vis({ preset: 'none' })
+  ],
+  test:{
+    browser:{/* ... */},
+    setupFiles: ['vitest.setup.ts']
+  }
+})
+
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+vis.presets.theme({
+  light() { document.body.classList.remove('dark') },
+  dark() { document.body.classList.add('dark') },
+})
+```
+
+## Usage
+
+### Auto Snapshot
+
+By default, the plugin will use the `auto` preset, which will take a snapshot at the end of each test.
+
+You can control how the auto snapshot is taken using the `setAutoSnapshotOptions` function:
+
+```ts
+import { setAutoSnapshotOptions } from 'vitest-plugin-vis'
+import { beforeEach, it } from 'vitest'
+
+beforeAll((suite) => {
+  // Apply options to all tests in the current suite (file)
+  setAutoSnapshotOptions(suite, /* options */)
+})
+
+beforeEach(({ task }) => {
+  // Apply options to all tests in the current scope
+  setAutoSnapshotOptions(task, /* options */)
+  // or
+  setAutoSnapshotOptions(/* options */)
+})
+
+
+it('disable snapshot per test', async ({ task }) => {
+  // Apply options to this test only
+  setAutoSnapshotOptions(task, /* options */)
+  // or
+  setAutoSnapshotOptions(/* options */)
+})
+
+describe('nested scope', () => {
+  beforeEach(({ task }) => {
+    // Apply options to all tests in the current scope
+    setAutoSnapshotOptions(task, /* options */)
+    // or
+    setAutoSnapshotOptions(/* options */)
+  })
+})
+```
+
+### Manual Snapshot
+
+You can also set the preset to `manual` and compare snapshots manually:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  plugins: [
+    vis({ preset: 'manual' })
+  ],
+  test:{
+    browser:{/* ... */}
+  }
+})
+
+// some.test.ts
+import 'vitest-browser-react' // do this in your setup file to get `page.render`
+import { page } from '@vitest/browser/context'
+import { expect, it } from 'vitest'
+
+it('manual snapshot', async () => {
+  page.render(<div data-testid="subject">hello world</div>)
+  await expect(document.body).toMatchImageSnapshot(/* options */)
+  // or
+  const subject = page.getByTestId('subject')
+  await expect(subject).toMatchImageSnapshot(/* options */)
+})
+```
+
+You can customize the snapshot comparison options per assertion:
+
+```ts
+// some.test.ts
+import 'vitest-browser-react' // do this in your setup file to get `page.render`
+import { page } from '@vitest/browser/context'
+import { expect, it } from 'vitest'
+
+it('manual snapshot with options', async () => {
+  page.render(<div data-testid="subject">hello world</div>)
+  const subject = page.getByTestId('subject')
+  await expect(subject).toMatchImageSnapshot({
+    customizeSnapshotId: (id, index) => `${id}-${index}`,
+    failureThreshold: 0.01,
+    failureThresholdType: 'percent',
+    diffOptions: {
+      threshold: 0.1
+    },
+    timeout: 15000
+  })
+})
+```
+
+### Has Snapshot
+
+While less common, you can also check if a snapshot exists:
+
+```ts
+import { page } from '@vitest/browser/context'
+import { expect, it } from 'vitest'
+
+it('Has Snapshot', async () => {
+  const hasSnapshot = await page.hasImageSnapshot(/* options */)
+  if (!hasSnapshot) {
+    // do something
+  }
+  else {
+    // do something else
+  }
+})
+```
+
+This is useful when you are performing some negative test.
+
+## Git Ignore
+
+The local snapshots, current run results, and diffs should be ignored by git.
+Add the following lines to your `.gitignore` file:
+
+```sh
+**/__vis__/__diffs__
+**/__vis__/__results__
+**/__vis__/local
+```
+
+## Vitest Browser Mode
+
+Vitest visual testing plugin runs on [Vitest Browser Mode][vitest-browser-mode].
+Please follow its guide to set up your environment.
+
+Bonus note, if you want to install [Firefox] on WSL,
+you can follow these steps: [Install Firefox on Ubuntu 22.04](https://askubuntu.com/a/1444967).
+
+## Running on CI
+
+When running on CI, the plugin will save the image snapshots in the `<root>/__vis__/<process.platform>` directory.
+
+The image snapshots are taken on the server side using `playwright` or `webdriverio` depending on your browser provider.
+It is recommended to run your tests serially to avoid flakiness.
+
+## FAQ
+
+> feature X in [`jest-image-snapshot`][jest-image-snapshot] is missing
+
+Some features in [`jest-image-snapshot`][jest-image-snapshot] are not implemented in [`vitest-plugin-vis`][vitest-plugin-vis] yet.
+This is because through our own usage, we do not found a good use case for them.
+For example, the `ssim` comparison method is not implemented in [`vitest-plugin-vis`][vitest-plugin-vis],
+because we found that figuring out what is the delta using `ssim` is quite difficult.
+
+If you have a good use case for these features, please open an issue or PR.
+
+[firefox]: https://www.mozilla.org/en-US/firefox/
+[jest-image-snapshot]: https://github.com/americanexpress/jest-image-snapshot
+[storybook-addon-vis]: https://github.com/repobuddy/storybook-addon-vis
+[vitest-browser-mode]: https://vitest.dev/guide/browser/
+[vitest-plugin-vis]: https://www.npmjs.com/package/vitest-plugin-vis

package/src/client/ctx.ts

@@ -0,0 +1,8 @@
+import { getCurrentTest } from 'vitest/suite'
+
+export const ctx = {
+	getCurrentTest,
+	__test__reset() {
+		ctx.getCurrentTest = getCurrentTest
+	},
+}

package/src/client/expect/expectation_result.ts

@@ -0,0 +1,7 @@
+import type { SyncExpectationResult } from '@vitest/expect'
+
+export const success: SyncExpectationResult = {
+	pass: true,
+	/* v8 ignore next */
+	message: () => '',
+}

package/src/client/expect/extend.ts

@@ -0,0 +1,12 @@
+import { expect } from 'vitest'
+import { toMatchImageSnapshot } from './to_match_image_snapshot.ts'
+import type { ImageSnapshotMatcher } from './to_match_image_snapshot.types.ts'
+
+declare global {
+	namespace jest {
+		// biome-ignore lint/correctness/noUnusedVariables: augmentation must have matching type params.
+		interface Matchers<R, T> extends ImageSnapshotMatcher {}
+	}
+}
+
+expect.extend({ toMatchImageSnapshot })

package/src/client/expect/to_match_image_snapshot.logic.ts

@@ -0,0 +1,11 @@
+import { isBase64String } from '../../shared/base64.ts'
+import { convertElementToCssSelector } from '../selector.ts'
+
+export function parseImageSnapshotSubject(subject: any) {
+	if (subject instanceof Element) return convertElementToCssSelector(subject)
+	if (subject?.['selector']) return subject['selector']
+	if (isBase64String(subject)) return subject
+	throw new Error(
+		`'toMatchImageSnapshot()' expects the subject to be an element, locator, or image encoded in base64 string, but got: ${subject}`,
+	)
+}

package/src/client/expect/to_match_image_snapshot.ts

@@ -0,0 +1,43 @@
+import { commands } from '@vitest/browser/context'
+import type { AsyncExpectationResult } from '@vitest/expect'
+import { ctx } from '../ctx.ts'
+import { toTaskId } from '../task_id.ts'
+import { success } from './expectation_result.ts'
+import { parseImageSnapshotSubject } from './to_match_image_snapshot.logic.ts'
+import type { ToMatchImageSnapshotOptions } from './to_match_image_snapshot.types.ts'
+
+export function toMatchImageSnapshot(
+	/**
+	 * The element or locator to take the snapshot of,
+	 * or the base64 value of the image to compare against.
+	 */
+	subject: any,
+	options?: ToMatchImageSnapshotOptions | undefined,
+): AsyncExpectationResult {
+	const test = ctx.getCurrentTest()
+	if (!test) {
+		throw new Error('`toMatchImageSnapshot()` must be called in a test.')
+	}
+
+	if (test.concurrent) {
+		throw new Error(
+			'`toMatchImageSnapshot()` cannot be called in a concurrent test because ' +
+				"concurrent tests run at the same time in the same iframe and affect each other's environment. ",
+		)
+	}
+
+	const s = parseImageSnapshotSubject(subject)
+	const taskId = toTaskId(test)
+	return toMatchImageSnapshotAsync(taskId, s, options).then(() => success)
+}
+
+async function toMatchImageSnapshotAsync(taskId: string, subject: string, options?: ToMatchImageSnapshotOptions) {
+	if (options?.customizeSnapshotId) {
+		const index = await commands.imageSnapshotNextIndex(taskId)
+		const { customizeSnapshotId, ...rest } = options
+		const snapshotFileId = customizeSnapshotId(taskId, index)
+		return commands.matchImageSnapshot(taskId, subject, { ...rest, snapshotFileId })
+	}
+
+	return commands.matchImageSnapshot(taskId, subject, options)
+}

package/src/client/expect/to_match_image_snapshot.types.ts

@@ -0,0 +1,14 @@
+import type {
+	ImageSnapshotCompareOptions,
+	ImageSnapshotIdOptions,
+	ImageSnapshotTimeoutOptions,
+} from '../../shared/types.ts'
+
+export interface ImageSnapshotMatcher {
+	toMatchImageSnapshot(options?: ToMatchImageSnapshotOptions | undefined): Promise<void>
+}
+
+export interface ToMatchImageSnapshotOptions
+	extends ImageSnapshotTimeoutOptions,
+		ImageSnapshotIdOptions,
+		ImageSnapshotCompareOptions {}

package/src/client/page/extend.ts

@@ -0,0 +1,8 @@
+import { page } from '@vitest/browser/context'
+import { type HasImageSnapshotAction, hasImageSnapshot } from './has_image_snapshot.ts'
+
+declare module '@vitest/browser/context' {
+	interface BrowserPage extends HasImageSnapshotAction {}
+}
+
+page.extend({ hasImageSnapshot })

package/src/client/page/has_image_snapshot.ts

@@ -0,0 +1,33 @@
+import { type BrowserPage, commands } from '@vitest/browser/context'
+import type { ImageSnapshotIdOptions } from '../../shared/types.ts'
+import { ctx } from '../ctx.ts'
+import { toTaskId } from '../task_id.ts'
+
+export interface HasImageSnapshotAction {
+	hasImageSnapshot(this: BrowserPage, options?: ImageSnapshotIdOptions | undefined): Promise<boolean>
+}
+
+/**
+ * Check if the snapshot image exists.
+ */
+export function hasImageSnapshot(this: BrowserPage, options?: ImageSnapshotIdOptions | undefined) {
+	const test = ctx.getCurrentTest()
+	if (!test) {
+		throw new Error('`hasImageSnapshot()` must be called in a test.')
+	}
+
+	if (test.concurrent) {
+		throw new Error(
+			'`hasImageSnapshot()` cannot be called in a concurrent test because ' +
+				"concurrent tests run at the same time in the same iframe and affect each other's environment. ",
+		)
+	}
+	const taskId = toTaskId(test)
+	if (options?.customizeSnapshotId) {
+		return commands
+			.imageSnapshotNextIndex(taskId)
+			.then((index) => commands.hasImageSnapshot(taskId, options.customizeSnapshotId!(taskId, index)))
+	}
+
+	return commands.hasImageSnapshot(taskId)
+}

package/src/client/selector.ts

@@ -0,0 +1,118 @@
+/**
+ * Most of the code in this file is copied from Vitest.
+ *
+ * @see https://github.com/vitest-dev/vitest/blob/main/packages/browser/src/client/utils.ts
+ */
+import type { Locator } from '@vitest/browser/context'
+
+export function convertToSelector(elementOrLocator: Element | Locator): string {
+	if (!elementOrLocator) {
+		throw new Error('Expected element or locator to be defined.')
+	}
+	if (elementOrLocator instanceof Element) {
+		return convertElementToCssSelector(elementOrLocator)
+	}
+	if ('selector' in elementOrLocator) {
+		return (elementOrLocator as any).selector
+	}
+	throw new Error('Expected element or locator to be an instance of Element or Locator.')
+}
+export function convertElementToCssSelector(element: Element) {
+	if (!element || !(element instanceof Element)) {
+		throw new Error(`Expected DOM element to be an instance of Element, received ${typeof element}`)
+	}
+
+	return getUniqueCssSelector(element)
+}
+
+function escapeIdForCSSSelector(id: string) {
+	return id
+		.split('')
+		.map((char) => {
+			const code = char.charCodeAt(0)
+
+			if (
+				char === ' ' ||
+				char === '#' ||
+				char === '.' ||
+				char === ':' ||
+				char === '[' ||
+				char === ']' ||
+				char === '>' ||
+				char === '+' ||
+				char === '~' ||
+				char === '\\'
+			) {
+				// Escape common special characters with backslashes
+				return `\\${char}`
+			}
+			if (code >= 0x10000) {
+				// Unicode escape for characters outside the BMP
+				return `\\${code.toString(16).toUpperCase().padStart(6, '0')} `
+			}
+			if (code < 0x20 || code === 0x7f) {
+				// Non-printable ASCII characters (0x00-0x1F and 0x7F) are escaped
+				return `\\${code.toString(16).toUpperCase().padStart(2, '0')} `
+			}
+			if (code >= 0x80) {
+				// Non-ASCII characters (0x80 and above) are escaped
+				return `\\${code.toString(16).toUpperCase().padStart(2, '0')} `
+			}
+			// Allowable characters are used directly
+			return char
+		})
+		.join('')
+}
+
+function getUniqueCssSelector(el: Element) {
+	const path = []
+	let parent: null | ParentNode
+	let hasShadowRoot = false
+	// eslint-disable-next-line no-cond-assign
+	while ((parent = getParent(el))) {
+		if ((parent as Element).shadowRoot) {
+			hasShadowRoot = true
+		}
+
+		const tag = el.tagName
+		if (el.id) {
+			path.push(`#${escapeIdForCSSSelector(el.id)}`)
+		} else if (!el.nextElementSibling && !el.previousElementSibling) {
+			path.push(tag.toLowerCase())
+		} else {
+			let index = 0
+			let sameTagSiblings = 0
+			let elementIndex = 0
+
+			for (const sibling of parent.children) {
+				index++
+				if (sibling.tagName === tag) {
+					sameTagSiblings++
+				}
+				if (sibling === el) {
+					elementIndex = index
+				}
+			}
+
+			if (sameTagSiblings > 1) {
+				path.push(`${tag.toLowerCase()}:nth-child(${elementIndex})`)
+			} else {
+				path.push(tag.toLowerCase())
+			}
+		}
+		el = parent as Element
+	}
+	return `${getBrowserState().provider === 'webdriverio' && hasShadowRoot ? '>>>' : ''}${path.reverse().join(' > ')}`
+}
+
+function getParent(el: Element) {
+	const parent = el.parentNode
+	if (parent instanceof ShadowRoot) {
+		return parent.host
+	}
+	return parent
+}
+function getBrowserState(): { provider: 'webdriverio' | 'playwright' } {
+	// @ts-expect-error not typed global
+	return window.__vitest_browser_runner__
+}

package/src/client/should_take_snapshot.ts

@@ -0,0 +1,15 @@
+import { ctx } from './ctx.ts'
+import { getAutoSnapshotOptions } from './snapshot_options.internal.ts'
+import type { SnapshotMeta } from './snapshot_options.ts'
+
+/**
+ * Determine should snapshot be taken.
+ *
+ * not story: false
+ * no `snapshot` tag: false
+ * disabled by `!snapshot` tag: false
+ */
+export function shouldTakeSnapshot(meta?: SnapshotMeta | undefined) {
+	const m = meta ?? getAutoSnapshotOptions(ctx.getCurrentTest())
+	return document.body.childElementCount > 0 && m?.enable !== false
+}