diff --git a/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.js.mdx b/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.js.mdx new file mode 100644 index 000000000000..e9523fa3b322 --- /dev/null +++ b/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.js.mdx @@ -0,0 +1,69 @@ +```js +// storybook.test.js +import path from 'path'; +import * as glob from 'glob'; + +//๐Ÿ‘‡ Augment expect with jest-specific-snapshot +import 'jest-specific-snapshot'; + +import { describe, test, expect } from '@jest/globals'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +const compose = (entry) => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`, + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your stories files + const storyFiles = glob.sync( + path.join(__dirname, 'stories/**/*.{stories,story}.{js,jsx,mjs,ts,tsx}'), + ); + + return storyFiles.map((filePath) => { + const storyFile = require(filePath); + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + + return { filePath, storyFile, storyDir, componentName }; + }); +} + +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + // Defines the custom snapshot path location and file name + const customSnaphotPath = `./__snapshots__/${componentName}.test.js.snap`; + expect(mounted.container).toMatchSpecificSnapshot(customSnaphotPath); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.ts.mdx b/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.ts.mdx new file mode 100644 index 000000000000..e245ec4c1ee9 --- /dev/null +++ b/docs/snippets/common/individual-snapshot-tests-portable-stories.jest.ts.mdx @@ -0,0 +1,82 @@ +```ts +// storybook.test.ts +// Replace your-framework with one of the supported Storybook frameworks (react, vue3) +import type { Meta, StoryFn } from '@storybook/your-framework'; + +import path from "path"; +import * as glob from "glob"; + +//๐Ÿ‘‡ Augment expect with jest-specific-snapshot +import "jest-specific-snapshot"; + +import { describe, test, expect } from "@jest/globals"; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +type StoryFile = { + default: Meta; + [name: string]: StoryFn | Meta; +}; + +const compose = ( + entry: StoryFile +): ReturnType> => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}` + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your stories files + const storyFiles = glob.sync( + path.join(__dirname, 'stories/**/*.{stories,story}.{js,jsx,mjs,ts,tsx}'), + ); + + return storyFiles.map((filePath) => { + const storyFile = require(filePath); + const storyDir = path.dirname(filePath); + const componentName = path + .basename(filePath) + .replace(/\.(stories|story)\.[^/.]+$/, ""); + + return { filePath, storyFile, storyDir, componentName }; + }); +} + +describe("Stories Snapshots", () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map( + ([name, story]) => ({ name, story }) + ); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.` + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + // Defines the custom snapshot path location and file name + const customSnaphotPath = `./__snapshots__/${componentName}.test.ts.snap`; + expect(mounted.container).toMatchSpecificSnapshot(customSnaphotPath); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.js.mdx b/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.js.mdx new file mode 100644 index 000000000000..111149d958bb --- /dev/null +++ b/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.js.mdx @@ -0,0 +1,64 @@ +```js +// storybook.test.js +// @vitest-environment jsdom + +import path from 'path'; +import { describe, expect, test } from 'vitest'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +const compose = (entry) => { + try { + return composeStories(entry); + } catch (error) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${error}`, + ); + } +}; +function getAllStoryFiles() { + // Place the glob you want to match your story files + const storyFiles = Object.entries( + import.meta.glob('./stories/**/*.(stories|story).@(js|jsx|mjs|ts|tsx)', { + eager: true, + }), + ); + + return storyFiles.map(([filePath, storyFile]) => { + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + return { filePath, storyFile, componentName, storyDir }; + }); +} +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + // Defines the custom snapshot path location and file name + const customSnaphotPath = `./__snapshots__/${componentName}.spec.js.snap`; + expect(mounted.container).toMatchFileSnapshot(customSnaphotPath); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.ts.mdx b/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.ts.mdx new file mode 100644 index 000000000000..5c3f6097dae8 --- /dev/null +++ b/docs/snippets/common/individual-snapshot-tests-portable-stories.vitest.ts.mdx @@ -0,0 +1,74 @@ +```ts +// storybook.test.ts +// @vitest-environment jsdom + +// Replace your-framework with one of the supported Storybook frameworks (react, vue3) +import type { Meta, StoryFn } from '@storybook/your-framework'; + +import path from 'path'; +import { describe, expect, test } from 'vitest'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +type StoryFile = { + default: Meta; + [name: string]: StoryFn | Meta; +}; + +const compose = (entry: StoryFile): ReturnType> => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`, + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your story files + const storyFiles = Object.entries( + import.meta.glob('./stories/**/*.(stories|story).@(js|jsx|mjs|ts|tsx)', { + eager: true, + }), + ); + + return storyFiles.map(([filePath, storyFile]) => { + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + return { filePath, storyFile, componentName, storyDir }; + }); +} + +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + // Defines the custom snapshot path location and file name + const customSnaphotPath = `./__snapshots__/${componentName}.spec.ts.snap`; + expect(mounted.container).toMatchFileSnapshot(customSnaphotPath); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/snapshot-tests-portable-stories.jest.js.mdx b/docs/snippets/common/snapshot-tests-portable-stories.jest.js.mdx new file mode 100644 index 000000000000..eddd82a08227 --- /dev/null +++ b/docs/snippets/common/snapshot-tests-portable-stories.jest.js.mdx @@ -0,0 +1,64 @@ +```js +// storybook.test.js +import path from 'path'; +import * as glob from 'glob'; + +import { describe, test, expect } from '@jest/globals'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +const compose = (entry) => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`, + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your stories files + const storyFiles = glob.sync( + path.join(__dirname, 'stories/**/*.{stories,story}.{js,jsx,mjs,ts,tsx}'), + ); + + return storyFiles.map((filePath) => { + const storyFile = require(filePath); + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + + return { filePath, storyFile, storyDir, componentName }; + }); +} + +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + expect(mounted.container).toMatchSnapshot(); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/snapshot-tests-portable-stories.jest.ts.mdx b/docs/snippets/common/snapshot-tests-portable-stories.jest.ts.mdx new file mode 100644 index 000000000000..1cfbe1bdbb35 --- /dev/null +++ b/docs/snippets/common/snapshot-tests-portable-stories.jest.ts.mdx @@ -0,0 +1,72 @@ +```ts +// storybook.test.ts +// Replace your-framework with one of the supported Storybook frameworks (react, vue3) +import type { Meta, StoryFn } from '@storybook/your-framework'; + +import path from 'path'; +import * as glob from 'glob'; + +import { describe, test, expect } from '@jest/globals'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +type StoryFile = { + default: Meta; + [name: string]: StoryFn | Meta; +}; + +const compose = (entry: StoryFile): ReturnType> => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`, + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your stories files + const storyFiles = glob.sync( + path.join(__dirname, 'stories/**/*.{stories,story}.{js,jsx,mjs,ts,tsx}'), + ); + + return storyFiles.map((filePath) => { + const storyFile = require(filePath); + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + + return { filePath, storyFile, storyDir, componentName }; + }); +} + +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + expect(mounted.container).toMatchSnapshot(); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/snapshot-tests-portable-stories.vitest.js.mdx b/docs/snippets/common/snapshot-tests-portable-stories.vitest.js.mdx new file mode 100644 index 000000000000..dbaa397f1bb3 --- /dev/null +++ b/docs/snippets/common/snapshot-tests-portable-stories.vitest.js.mdx @@ -0,0 +1,62 @@ +```js +// storybook.test.js +// @vitest-environment jsdom + +import path from 'path'; +import { describe, expect, test } from 'vitest'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +const compose = (entry) => { + try { + return composeStories(entry); + } catch (error) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${error}`, + ); + } +}; +function getAllStoryFiles() { + // Place the glob you want to match your story files + const storyFiles = Object.entries( + import.meta.glob('./stories/**/*.(stories|story).@(js|jsx|mjs|ts|tsx)', { + eager: true, + }), + ); + + return storyFiles.map(([filePath, storyFile]) => { + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + return { filePath, storyFile, componentName, storyDir }; + }); +} +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + expect(mounted.container).toMatchSnapshot(); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/snapshot-tests-portable-stories.vitest.ts.mdx b/docs/snippets/common/snapshot-tests-portable-stories.vitest.ts.mdx new file mode 100644 index 000000000000..456bf5a1ae9d --- /dev/null +++ b/docs/snippets/common/snapshot-tests-portable-stories.vitest.ts.mdx @@ -0,0 +1,72 @@ +```ts +// storybook.test.ts +// @vitest-environment jsdom + +// Replace your-framework with one of the supported Storybook frameworks (react, vue3) +import type { Meta, StoryFn } from '@storybook/your-framework'; + +import path from 'path'; +import { describe, expect, test } from 'vitest'; + +// Replace your-testing-library with one of the supported testing libraries (e.g., react, vue) +import { render } from '@testing-library/your-testing-library'; + +// Adjust the import based on the supported framework or Storybook's testing libraries (e.g., react, vue3) +import { composeStories } from '@storybook/your-framework'; + +type StoryFile = { + default: Meta; + [name: string]: StoryFn | Meta; +}; + +const compose = (entry: StoryFile): ReturnType> => { + try { + return composeStories(entry); + } catch (e) { + throw new Error( + `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`, + ); + } +}; + +function getAllStoryFiles() { + // Place the glob you want to match your story files + const storyFiles = Object.entries( + import.meta.glob('./stories/**/*.(stories|story).@(js|jsx|mjs|ts|tsx)', { + eager: true, + }), + ); + + return storyFiles.map(([filePath, storyFile]) => { + const storyDir = path.dirname(filePath); + const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, ''); + return { filePath, storyFile, componentName, storyDir }; + }); +} + +describe('Stories Snapshots', () => { + getAllStoryFiles().forEach(({ storyFile, componentName }) => { + const meta = storyFile.default; + const title = meta.title || componentName; + + describe(title, () => { + const stories = Object.entries(compose(storyFile)).map(([name, story]) => ({ name, story })); + + if (stories.length <= 0) { + throw new Error( + `No stories found for this module: ${title}. Make sure there is at least one valid story for this module.`, + ); + } + + stories.forEach(({ name, story }) => { + test(name, async () => { + const mounted = render(story()); + // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot. + await new Promise((resolve) => setTimeout(resolve, 1)); + expect(mounted.container).toMatchSnapshot(); + }); + }); + }); + }); +}); +``` diff --git a/docs/snippets/common/test-runner-snapshot-resolver-custom-directory.js.mdx b/docs/snippets/common/test-runner-snapshot-resolver-custom-directory.js.mdx new file mode 100644 index 000000000000..203c8d30cbb2 --- /dev/null +++ b/docs/snippets/common/test-runner-snapshot-resolver-custom-directory.js.mdx @@ -0,0 +1,19 @@ +```js +// ./snapshot-resolver.js +import path from 'path'; + +export default { + resolveSnapshotPath: (testPath) => { + const fileName = path.basename(testPath); + const fileNameWithoutExtension = fileName.replace(/\.[^/.]+$/, ''); + // Defines the file extension for the snapshot file + const modifiedFileName = `${fileNameWithoutExtension}.snap`; + + // Configure Jest to generate snapshot files using the following convention (./src/test/__snapshots__/Button.stories.snap) + return path.join('./src/test/__snapshots__', modifiedFileName); + }, + resolveTestPath: (snapshotFilePath, snapshotExtension) => + path.basename(snapshotFilePath, snapshotExtension), + testPathForConsistencyCheck: 'example', +}; +``` diff --git a/docs/snippets/react/button-snapshot-test-portable-stories.jest.js.mdx b/docs/snippets/react/button-snapshot-test-portable-stories.jest.js.mdx new file mode 100644 index 000000000000..335eb461d736 --- /dev/null +++ b/docs/snippets/react/button-snapshot-test-portable-stories.jest.js.mdx @@ -0,0 +1,14 @@ +```js +// test/Button.test.js|ts +import { render } from '@testing-library/react'; + +import { composeStories } from '@storybook/react'; + +import * as stories from '../stories/Button.stories'; + +const { Primary } = composeStories(stories); +test('Button snapshot', async () => { + const mounted = render(); + expect(mounted.container).toMatchSnapshot(); +}); +``` diff --git a/docs/snippets/react/button-snapshot-test-portable-stories.vitest.js.mdx b/docs/snippets/react/button-snapshot-test-portable-stories.vitest.js.mdx new file mode 100644 index 000000000000..982992cc65aa --- /dev/null +++ b/docs/snippets/react/button-snapshot-test-portable-stories.vitest.js.mdx @@ -0,0 +1,18 @@ +```js +// test/Button.test.js|ts +// @vitest-environment jsdom + +import { expect, test } from 'vitest'; + +import { render } from '@testing-library/react'; + +import { composeStories } from '@storybook/react'; + +import * as stories from '../stories/Button.stories'; + +const { Primary } = composeStories(stories); +test('Button snapshot', async () => { + const mounted = render(Primary()); + expect(mounted.container).toMatchSnapshot(); +}); +``` diff --git a/docs/snippets/react/storybook-testing-addon-optional-config.vite.js.mdx b/docs/snippets/react/storybook-testing-addon-optional-config.vite.js.mdx new file mode 100644 index 000000000000..a50bd78cb49b --- /dev/null +++ b/docs/snippets/react/storybook-testing-addon-optional-config.vite.js.mdx @@ -0,0 +1,20 @@ +```js +// vitest.config.js + +import { defineConfig } from 'vitest/config'; +import { mergeConfig } from 'vite'; + +import viteConfig from './vite.config'; + +export default mergeConfig( + viteConfig, + defineConfig({ + test: { + globals: true, + environment: 'jsdom', + clearMocks: true, + setupFiles: './src/setupTests.js', //๐Ÿ‘ˆ Our configuration file enabled here + }, + }), +); +``` diff --git a/docs/snippets/react/storybook-testing-addon-optional-config.vite.ts.mdx b/docs/snippets/react/storybook-testing-addon-optional-config.vite.ts.mdx new file mode 100644 index 000000000000..3161eb45448c --- /dev/null +++ b/docs/snippets/react/storybook-testing-addon-optional-config.vite.ts.mdx @@ -0,0 +1,21 @@ +```ts +// vitest.config.ts + +/// +import { defineConfig } from 'vitest/config'; +import { mergeConfig } from 'vite'; + +import viteConfig from './vite.config'; + +export default mergeConfig( + viteConfig, + defineConfig({ + test: { + globals: true, + environment: 'jsdom', + clearMocks: true, + setupFiles: './src/setupTests.ts', //๐Ÿ‘ˆ Our configuration file enabled here + }, + }), +); +``` diff --git a/docs/snippets/vue/button-snapshot-test-portable-stories.js.mdx b/docs/snippets/vue/button-snapshot-test-portable-stories.js.mdx new file mode 100644 index 000000000000..06d28200e454 --- /dev/null +++ b/docs/snippets/vue/button-snapshot-test-portable-stories.js.mdx @@ -0,0 +1,18 @@ +```js +// __tests__/Button.spec.js|ts +// @vitest-environment jsdom + +import { expect, test } from 'vitest'; + +import { render } from '@testing-library/vue'; + +import { composeStories } from '@storybook/vue3'; + +import * as stories from '../stories/Button.stories'; + +const { Primary } = composeStories(stories); +test('Button snapshot', async () => { + const mounted = render(Primary()); + expect(mounted.container).toMatchSnapshot(); +}); +``` diff --git a/docs/toc.js b/docs/toc.js index 37149c7e8f23..aecde723f11f 100644 --- a/docs/toc.js +++ b/docs/toc.js @@ -183,12 +183,12 @@ module.exports = { children: [ { pathSegment: 'snapshot-testing', - title: 'Storyshots', + title: 'Write', type: 'link', }, { pathSegment: 'storyshots-migration-guide', - title: 'Migration guide', + title: 'Storyshots migration guide', type: 'link', }, ], diff --git a/docs/writing-tests/snapshot-testing.md b/docs/writing-tests/snapshot-testing.md index 438258b36adb..36616674380d 100644 --- a/docs/writing-tests/snapshot-testing.md +++ b/docs/writing-tests/snapshot-testing.md @@ -1,5 +1,5 @@ --- -title: 'Snapshot testing with Storyshots' +title: 'Write snapshot tests' --- Snapshot tests compare the rendered markup of every story against known baselines. Itโ€™s a way to identify markup changes that trigger rendering errors and warnings. @@ -8,118 +8,195 @@ Storybook is a helpful tool for snapshot testing because every story is essentia ![Example Snapshot test](./snapshot-test.png) -## Migrating Tests + -The Storyshots addon was the original testing solution for Storybook, offering a highly extensible API and a wide range of configuration options for testing. However, it was difficult to set up and maintain, and it needed to be compatible with the latest version of Storybook, which introduced some significant architectural changes, including a high-performance [on-demand story loading](../configure/index.md#on-demand-story-loading) feature. As a result, Storyshots is now officially deprecated, is no longer being maintained, and will be removed in the next major release of Storybook. We recommend following the [migration guide](./storyshots-migration-guide.md) we've prepared to help you during this transition period. +If you're [upgrading](../configure/upgrading.md) to Storybook 8.0 and were using the Storyshots addon for snapshot testing, it was officially deprecated and removed with this release. See the [migration guide](./storyshots-migration-guide.md) for more information. -## Set up Storyshots + + +## Automate snapshot tests with the test-runner + +Storybook test-runner turns all of your stories into executable tests. Powered by [Jest](https://jestjs.io/) and [Playwright](https://playwright.dev/). It's a standalone, framework-agnostic utility that runs parallel to your Storybook. It enables you to run multiple testing patterns in a multi-browser environment, including interaction testing with the [play function](./interaction-testing.md), DOM snapshot, and [accessibility testing](./accessibility-testing.md). - +### Setup -The Storyshots addon was deprecated and has been removed in Storybook 8. See the [migration guide](./storyshots-migration-guide.md) for more information. +To enable snapshot testing with the test-runner, you'll need to take additional steps to set it up properly. We recommend you go through the [test-runner documentation](./test-runner.md) before proceeding with the rest of the required configuration to learn more about the available options and APIs. + +Add a new [configuration file](./test-runner.md#test-hook-api) inside your Storybook directory with the following inside: + + + + + + + + + +The `postVisit` hook allows you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api). -[Storyshots](https://storybook.js.org/addons/@storybook/addon-storyshots/) is a Storybook addon that enables snapshot testing, powered by [Jest](https://jestjs.io/docs/getting-started). +When you execute the test-runner (for example, with `yarn test-storybook`), it will run through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the `__snapshots__` directory. + +### Configure -Run the following command to install Storyshots: +Out of the box, the test-runner provides an inbuilt snapshot testing configuration covering most use cases. You can also fine-tune the configuration to fit your needs via `test-storybook --eject` or by creating a `test-runner-jest.config.js` file at the root of your project. + +#### Override the default snapshot directory + +The test-runner uses a specific naming convention and path for the generated snapshot files by default. If you need to customize the snapshot directory, you can define a custom snapshot resolver to specify the directory where the snapshots are stored. + +Create a `snapshot-resolver.js` file to implement a custom snapshot resolver: -Add a test file to your environment with the following contents to configure Storyshots: +Update the `test-runner-jest.config.js` file and enable the `snapshotResolver` option to use the custom snapshot resolver: - +When the test-runner is executed, it will cycle through all of your stories and run the snapshot tests, generating a snapshot file for each story in your project located in the custom directory you specified. -You can name the test file differently to suit your needs. Bear in mind that it requires to be picked up by Jest. +#### Customize snapshot serialization - +By default, the test-runner uses [`jest-serializer-html`](https://github.com/algolia/jest-serializer-html) to serialize HTML snapshots. This may cause issues if you use specific CSS-in-JS libraries like [Emotion](https://emotion.sh/docs/introduction), Angular's `ng` attributes, or similar libraries that generate hash-based identifiers for CSS classes. If you need to customize the serialization of your snapshots, you can define a custom snapshot serializer to specify how the snapshots are serialized. -Run your first test. Storyshots will recognize your stories (based on [.storybook/main.js's setup](../configure/story-rendering.md)) and save them in the **snapshots** directory. +Create a `snapshot-serializer.js` file to implement a custom snapshot serializer: -```shell -npm test storybook.test.js -``` + -![Successful snapshot tests](./storyshots-pass.png) + -When you make changes to your components or stories, rerun the test to identify the changes to the rendered markup. + -![Failing snapshots](./storyshots-fail.png) +Update the `test-runner-jest.config.js` file and enable the `snapshotSerializers` option to use the custom snapshot resolver: -If they're intentional, accept them as new baselines. If the changes are bugs, fix the underlying code, then rerun the snapshot tests. + -### Configure the snapshot's directory + -If your project has a custom setup for snapshot testing, you'll need to take additional steps to run Storyshots. You'll need to install both [@storybook/addon-storyshots-puppeteer](https://storybook.js.org/addons/@storybook/addon-storyshots-puppeteer) and [puppeteer](https://github.com/puppeteer/puppeteer): + + +When the test-runner executes your tests, it will introspect the resulting HTML, replacing the dynamically generated attributes with the static ones provided by the regular expression in the custom serializer file before snapshotting the component. This ensures that the snapshots are consistent across different test runs. + + + + -```shell -# With npm -npm i -D @storybook/addon-storyshots-puppeteer puppeteer +## Snapshot tests with Portable Stories -# With yarn -yarn add @storybook/addon-storyshots-puppeteer puppeteer -``` +Storybook provides a `composeStories` utility that helps convert stories from a test file into renderable elements that can be reused in your Node tests with JSDOM. It also allows you to apply other Storybook features that you have enabled your project (e.g., [decorators](../writing-stories/decorators.md), [args](../writing-stories/args.md)) into your tests, enabling you to reuse your stories in your testing environment of choice (e.g., [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/)), ensuring your tests are always in sync with your stories without having to rewrite them. This is what we refer to as portable stories in Storybook. -Next, update your test file (for example, `storybook.test.js`) to the following: +### Configure + +By default, Storybook offers a zero-config setup for React, Vue, and other frameworks via addons, allowing you to run your stories as tests with your testing environment of choice. However, if you're running tests and you've set up specific configurations in your Storybook instance (e.g., global [decorators](../writing-stories/decorators.md#global-decorators), [parameters](../writing-stories/parameters.md#global-parameters)) that you want to use in your tests, you'll need to extend your test setup to include these configurations. To do so, create a `setup.js|ts` file as follows: - +Update your test configuration file (e.g., `vite.config.js|ts`) if you're using [Vitest](https://vitest.dev/) or your test script if you're using [Jest](https://jestjs.io/): -Don't forget to replace your-custom-directory with your own. + - + -When you run your tests, the snapshots will be available in your specified directory. + -### Framework configuration +### Run tests on a single story -By default, Storyshots detects your project's framework. If you encounter a situation where this is not the case, you can adjust the configuration object and specify your framework. For example, if you wanted to configure the addon for a Vue 3 project: +If you need to run tests on a single story, you can use the `composeStories` function from the appropriate framework to process it and apply any configuration you've defined in your stories (e.g., [decorators](../writing-stories/decorators.md), [args](../writing-stories/args.md)) and combine it with your testing environment to generate a snapshot file. For example, if you're working on a component and you want to test its default state, ensuring the expected DOM structure doesn't change, here's how you could write your test: -These are the frameworks currently supported by Storyshots: `angular`, `html`, `preact`, `react`, `react-native`, `svelte`, `vue`, `vue3`, and `web-components`. +### Execute tests on multiple stories -### Additional customization +You can also use the `composeStories` function to test multiple stories. This is useful when you want to extend your test coverage to generate snapshots for the different states of the components in your project. To do so, you can write your test as follows: -Storyshots is highly customizable and includes options for various advanced use cases. You can read more in the [addonโ€™s documentation](https://github.com/storybookjs/storybook/tree/master/addons/storyshots/storyshots-core#options). + ---- + + + + +When your tests are executed in your testing environment, they will generate a single snapshot file with all the stories in your project (i.e.,`storybook.test.ts|js.snap`). However, if you need, you can extend your test file to generate individual snapshot files for each story in your project with Vitest's [`toMatchFileSnapshot`](https://vitest.dev/guide/snapshot.html#file-snapshots) API or Jest's [`jest-specific-snapshot`](https://github.com/igor-dv/jest-specific-snapshot) package. For example: + + + + + + + + #### Whatโ€™s the difference between snapshot tests and visual tests? diff --git a/docs/writing-tests/storyshots-fail.png b/docs/writing-tests/storyshots-fail.png deleted file mode 100644 index 1cf3677509f5..000000000000 Binary files a/docs/writing-tests/storyshots-fail.png and /dev/null differ diff --git a/docs/writing-tests/storyshots-pass.png b/docs/writing-tests/storyshots-pass.png deleted file mode 100644 index b93d218c8f34..000000000000 Binary files a/docs/writing-tests/storyshots-pass.png and /dev/null differ