vitest-plugin-vis 3.1.0 → 3.3.0

package/src/setup.ts

@@ -4,6 +4,5 @@ import './client/page/extend.ts'
 
 export * from './client/setup/vis.ts'
 
-// 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.ts'

package/src/setup.vis.mdx

@@ -0,0 +1,122 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="vitest-plugin-vis/setup/vis" />
+
+`vis` from `vitest-plugin-vis/setup` is the main mechanism to setup the plugin on the client side.
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+vis.setup()
+```
+
+## Basic Setup
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+// Basic setup - enables visual testing without auto snapshots
+vis.setup()
+
+// Enable auto snapshots for all tests
+vis.setup({ auto: true })
+
+// Disable auto snapshots (same as vis.setup())
+vis.setup({ auto: false })
+```
+
+## Conditional Auto Snapshots
+
+You can control when auto snapshots are taken based on test metadata:
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+// Take snapshots only for tests with specific metadata
+vis.setup({
+	auto: async ({ meta }) => meta['visualTest'] === true
+})
+
+// Skip snapshots for tests marked as 'skipSnapshot'
+vis.setup({
+	auto: async ({ meta }) => !meta['skipSnapshot']
+})
+```
+
+## Multi-Theme Setup
+
+Set up automatic snapshots for multiple themes (e.g., light and dark mode):
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+vis.setup({
+	auto: {
+		async light() {
+			document.body.classList.remove('dark')
+			document.body.classList.add('light')
+		},
+		async dark() {
+			document.body.classList.add('dark')
+			document.body.classList.remove('light')
+		}
+	}
+})
+```
+
+## Conditional Theme Snapshots
+
+You can conditionally skip themes based on test metadata:
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+vis.setup({
+	auto: {
+		async light({ meta }) {
+			if (meta['skipLight']) return false
+			document.body.classList.remove('dark')
+		},
+		async dark({ meta }) {
+			if (meta['skipDark']) return false
+			document.body.classList.add('dark')
+		}
+	}
+})
+```
+
+## Advanced Theme Configuration
+
+You can set up more complex theme configurations:
+
+```ts
+// vitest.setup.ts
+import { vis } from 'vitest-plugin-vis/setup'
+
+vis.setup({
+	auto: {
+		async desktop() {
+			document.body.style.width = '1200px'
+			document.body.classList.add('desktop')
+		},
+		async tablet() {
+			document.body.style.width = '768px'
+			document.body.classList.add('tablet')
+		},
+		async mobile() {
+			document.body.style.width = '375px'
+			document.body.classList.add('mobile')
+		},
+		async 'dark-desktop'({ meta }) {
+			if (meta['skipDark']) return false
+			document.body.style.width = '1200px'
+			document.body.classList.add('desktop', 'dark')
+		}
+	}
+})
+```

package/src/shared/trim_common_folder.mdx

@@ -0,0 +1,153 @@
+import { Meta, Source } from "@storybook/addon-docs/blocks";
+
+<Meta title="vitest-plugin-vis/config/trimCommonFolder" />
+
+# trimCommonFolder
+
+The `trimCommonFolder` function is a utility that removes common folder prefixes from file paths to generate cleaner snapshot sub-paths.
+
+## Purpose
+
+When generating snapshot paths, test files are often located in common directories like `src`, `tests`, `test`, etc. The `trimCommonFolder` function removes these common prefixes to create shorter, more meaningful snapshot directory structures.
+
+## Usage
+
+The default `snapshotSubpath` option in `vitest-plugin-vis/config` uses this function to trim common folder prefixes from the test file path:
+
+```ts
+// vitest.config.ts
+import { vis, trimCommonFolder } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		snapshotSubpath: ({ subpath }) => trimCommonFolder(subpath)
+	})]
+})
+```
+
+You can use it in your own custom `snapshotSubpath` function.
+
+## Function Signature
+
+```ts
+function trimCommonFolder(suiteName: string): string
+```
+
+## Supported Common Folders
+
+The function recognizes and removes the following common folder prefixes:
+
+- `tests` - Common test directory
+- `test` - Alternative test directory
+- `src` - Source code directory
+- `source` - Alternative source directory
+- `js` - JavaScript files directory
+- `ts` - TypeScript files directory
+- `lib` - Library files directory
+
+## Examples
+
+### Trimming Source Directories
+
+```ts
+trimCommonFolder('src/components/Button.spec.ts')
+// Returns: 'components/Button.spec.ts'
+
+trimCommonFolder('source/utils/helpers.test.ts')
+// Returns: 'utils/helpers.test.ts'
+```
+
+### Trimming Test Directories
+
+```ts
+trimCommonFolder('tests/unit/Button.spec.ts')
+// Returns: 'unit/Button.spec.ts'
+
+trimCommonFolder('test/integration/api.test.ts')
+// Returns: 'integration/api.test.ts'
+```
+
+### Trimming Language-Specific Directories
+
+```ts
+trimCommonFolder('js/components/Modal.spec.js')
+// Returns: 'components/Modal.spec.js'
+
+trimCommonFolder('ts/types/User.test.ts')
+// Returns: 'types/User.test.ts'
+
+trimCommonFolder('lib/utils/format.spec.ts')
+// Returns: 'utils/format.spec.ts'
+```
+
+### No Trimming Cases
+
+```ts
+// Unrecognized folder - no trimming
+trimCommonFolder('app/components/Button.spec.ts')
+// Returns: 'app/components/Button.spec.ts'
+
+// File in root - no trimming
+trimCommonFolder('Button.spec.ts')
+// Returns: 'Button.spec.ts'
+
+// No slash separator - no trimming
+trimCommonFolder('index.ts')
+// Returns: 'index.ts'
+```
+
+### Before and After Snapshot Paths
+
+Without `trimCommonFolder`:
+```
+__vis__/local/__baselines__/src/components/Button.spec.ts/Button/should-render-correctly-auto.png
+```
+
+With `trimCommonFolder`:
+```
+__vis__/local/__baselines__/components/Button.spec.ts/Button/should-render-correctly-auto.png
+```
+
+## Custom Implementation
+
+You can create your own trimming logic by implementing a similar function:
+
+```ts
+// Custom trimming function
+function customTrimFolder(suiteName: string) {
+  const customFolders = ['app', 'pages', 'components']
+  const suiteDir = suiteName.split('/', 1)[0]!
+
+  if (customFolders.includes(suiteDir)) {
+    return suiteName.slice(suiteDir.length + 1)
+  }
+
+  return suiteName
+}
+
+// Use in config
+export default defineConfig({
+  plugins: [
+    vis({
+      snapshotSubpath: ({ subpath }) => customTrimFolder(subpath)
+    })
+  ]
+})
+```
+
+### Case Sensitivity
+
+The function is case-sensitive and only matches exact lowercase folder names:
+
+```ts
+trimCommonFolder('SRC/components/Button.spec.ts')
+// Returns: 'SRC/components/Button.spec.ts' (no trimming)
+
+trimCommonFolder('Src/components/Button.spec.ts')
+// Returns: 'Src/components/Button.spec.ts' (no trimming)
+```
+
+## Related
+
+- [vis config](/docs/vitest-plugin-vis-config-vis--docs) - Main plugin configuration
+- [Snapshot Path Customization](/docs/vitest-plugin-vis-config-vis--docs#customizing-snapshot-path) - How to customize snapshot paths