CSF: Add Storybook test syntax (Storybook v10)

.gitignore

@@ -57,7 +57,7 @@ code/bench-results/
 /packs
 code/.nx/cache
 code/.nx/workspace-data
-code/.vite-inspect
+.vite-inspect
 .nx/cache
 .nx/workspace-data
 !**/fixtures/**/yarn.lock

code/.storybook/main.ts

@@ -136,6 +136,7 @@ const config = defineMain({
   },
   features: {
     developmentModeForBuild: true,
+    experimentalTestSyntax: true,
   },
   staticDirs: [{ from: './bench/bundle-analyzer', to: '/bundle-analyzer' }],
   viteFinal: async (viteConfig, { configType }) => {

code/.storybook/preview.tsx

@@ -216,18 +216,21 @@ const decorators = [
    * This decorator renders the stories side-by-side, stacked or default based on the theme switcher
    * in the toolbar
    */
-  (StoryFn, { globals, playFunction, args, storyGlobals, parameters }) => {
+  (StoryFn, { globals, playFunction, testFunction, args, storyGlobals, parameters }) => {
     let theme = globals.sb_theme;
     let showPlayFnNotice = false;
 
     // this makes the decorator be out of 'phase' with the actually selected theme in the toolbar
     // but this is acceptable, I guess
     // we need to ensure only a single rendering in chromatic
     // a more 'correct' approach would be to set a specific theme global on every story that has a playFunction
-    if (playFunction && args.autoplay !== false && !(theme === 'light' || theme === 'dark')) {
+    if (
+      (testFunction || (playFunction && args.autoplay !== false)) &&
+      !(theme === 'light' || theme === 'dark')
+    ) {
       theme = 'light';
       showPlayFnNotice = true;
-    } else if (isChromatic() && !storyGlobals.sb_theme && !playFunction) {
+    } else if (isChromatic() && !storyGlobals.sb_theme && !playFunction && !testFunction) {
       theme = 'stacked';
     }
 
@@ -282,8 +285,8 @@ const decorators = [
               <>
                 <PlayFnNotice>
                   <span>
-                    Detected play function in Chromatic. Rendering only light theme to avoid
-                    multiple play functions in the same story.
+                    Detected play/test function in Chromatic. Rendering only light theme to avoid
+                    multiple play/test functions in the same story.
                   </span>
                 </PlayFnNotice>
                 <div style={{ marginBottom: 20 }} />

code/addons/docs/src/blocks/blocks/external/ExternalPreview.ts

@@ -71,9 +71,11 @@ export class ExternalPreview<TRenderer extends Renderer = Renderer> extends Prev
         title,
         name,
         type: 'story',
+        subtype: 'story',
       };
     });
 
+    // TODO: We probably need to do something here about story tests
     this.onStoriesChanged({ storyIndex: this.storyIndex });
 
     return csfFile;

code/addons/docs/src/preview.ts

@@ -1,12 +1,5 @@
 import type { PreparedStory } from 'storybook/internal/types';
 
-import * as tocbot from 'tocbot';
-
-if (!globalThis.__STORYBOOK_UNSAFE_TOCBOT__) {
-  // Users that load dynamic content need to have a way to refresh the TOC, so we expose the tocbot instance
-  globalThis.__STORYBOOK_UNSAFE_TOCBOT__ = tocbot.default ?? tocbot;
-}
-
 const excludeTags = Object.entries(globalThis.TAGS_OPTIONS ?? {}).reduce(
   (acc, entry) => {
     const [tag, option] = entry;

code/addons/docs/src/typings.d.ts

@@ -7,7 +7,6 @@ declare var __DOCS_CONTEXT__: any;
 declare var PREVIEW_URL: any;
 declare var LOGLEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined;
 declare var TAGS_OPTIONS: import('storybook/internal/types').TagsOptions;
-declare var __STORYBOOK_UNSAFE_TOCBOT__: typeof import('tocbot').default;
 
 declare module '*.md';
 declare module '*.md?raw';

code/addons/vitest/src/components/TestProviderRender.stories.tsx

@@ -310,6 +310,7 @@ export const InSidebarContextMenu: Story = {
     entry: {
       id: 'story-id-1',
       type: 'story',
+      subtype: 'story',
       name: 'Example Story',
       tags: [],
       title: 'Example Story',

code/addons/vitest/src/components/TestProviderRender.tsx

@@ -242,15 +242,19 @@ export const TestProviderRender: FC<TestProviderRenderProps> = ({
               <IconButton
                 aria-label="Start test run"
                 size="medium"
-                onClick={() =>
+                onClick={() => {
+                  let storyIds;
+                  if (entry) {
+                    // Don't send underlying child test ids when running on a story
+                    // Vitest Manager already handles running the underlying tests
+                    storyIds =
+                      entry.type === 'story' ? [entry.id] : api.findAllLeafStoryIds(entry.id);
+                  }
                   store.send({
                     type: 'TRIGGER_RUN',
-                    payload: {
-                      storyIds: entry ? api.findAllLeafStoryIds(entry.id) : undefined,
-                      triggeredBy: entry ? entry.type : 'global',
-                    },
-                  })
-                }
+                    payload: { storyIds, triggeredBy: entry?.type ?? 'global' },
+                  });
+                }}
               >
                 <PlayHollowIcon />
               </IconButton>

code/addons/vitest/src/node/test-manager.test.ts

@@ -15,6 +15,7 @@ import path from 'pathe';
 import { STATUS_TYPE_ID_A11Y, STATUS_TYPE_ID_COMPONENT_TEST, storeOptions } from '../constants';
 import type { StoreEvent, StoreState } from '../types';
 import { TestManager, type TestManagerOptions } from './test-manager';
+import { DOUBLE_SPACES } from './vitest-manager';
 
 const setTestNamePattern = vi.hoisted(() => vi.fn());
 const vitest = vi.hoisted(() => ({
@@ -103,6 +104,7 @@ global.fetch = vi.fn().mockResolvedValue({
         entries: {
           'story--one': {
             type: 'story',
+            subtype: 'story',
             id: 'story--one',
             name: 'One',
             title: 'story/one',
@@ -111,12 +113,32 @@ global.fetch = vi.fn().mockResolvedValue({
           },
           'another--one': {
             type: 'story',
+            subtype: 'story',
             id: 'another--one',
             name: 'One',
             title: 'another/one',
             importPath: 'path/to/another/file',
             tags: ['test'],
           },
+          'parent--story': {
+            type: 'story',
+            subtype: 'story',
+            id: 'parent--story',
+            name: 'Parent story',
+            title: 'parent/story',
+            importPath: 'path/to/parent/file',
+            tags: ['test'],
+          },
+          'parent--story:test': {
+            type: 'story',
+            subtype: 'test',
+            id: 'parent--story:test',
+            name: 'Test name',
+            title: 'parent/story',
+            parent: 'parent--story',
+            importPath: 'path/to/parent/file',
+            tags: ['test', 'test-fn'],
+          },
         },
       } as StoryIndex)
     ),
@@ -184,10 +206,56 @@ describe('TestManager', () => {
         triggeredBy: 'global',
       },
     });
-    expect(setTestNamePattern).toHaveBeenCalledWith(/^One$/);
+    expect(setTestNamePattern).toHaveBeenCalledWith(new RegExp(`^One$`));
     expect(vitest.runTestSpecifications).toHaveBeenCalledWith(tests.slice(0, 1), true);
   });
 
+  it('should trigger a single story render test', async () => {
+    vitest.globTestSpecifications.mockImplementation(() => tests);
+    const testManager = await TestManager.start(options);
+
+    await testManager.handleTriggerRunEvent({
+      type: 'TRIGGER_RUN',
+      payload: {
+        storyIds: ['another--one'],
+        triggeredBy: 'global',
+      },
+    });
+    // regex should be exact match of the story name
+    expect(setTestNamePattern).toHaveBeenCalledWith(new RegExp(`^One$`));
+  });
+
+  it('should trigger a single story test', async () => {
+    vitest.globTestSpecifications.mockImplementation(() => tests);
+    const testManager = await TestManager.start(options);
+
+    await testManager.handleTriggerRunEvent({
+      type: 'TRIGGER_RUN',
+      payload: {
+        storyIds: ['parent--story:test'],
+        triggeredBy: 'global',
+      },
+    });
+    // regex should be Parent Story Name + Test Name
+    expect(setTestNamePattern).toHaveBeenCalledWith(
+      new RegExp(`^Parent story${DOUBLE_SPACES} Test name$`)
+    );
+  });
+
+  it('should trigger all tests of a story', async () => {
+    vitest.globTestSpecifications.mockImplementation(() => tests);
+    const testManager = await TestManager.start(options);
+
+    await testManager.handleTriggerRunEvent({
+      type: 'TRIGGER_RUN',
+      payload: {
+        storyIds: ['parent--story'],
+        triggeredBy: 'global',
+      },
+    });
+    expect(setTestNamePattern).toHaveBeenCalledWith(new RegExp(`^Parent story${DOUBLE_SPACES}`));
+  });
+
   it('should restart Vitest before a test run if coverage is enabled', async () => {
     const testManager = await TestManager.start(options);
     expect(createVitest).toHaveBeenCalledTimes(1);

code/addons/vitest/src/node/vitest-manager.ts

@@ -16,7 +16,6 @@ import * as find from 'empathic/find';
 import path, { dirname, join, normalize } from 'pathe';
 import slash from 'slash';
 
-import { resolvePackageDir } from '../../../../core/src/shared/utils/module';
 import { COVERAGE_DIRECTORY } from '../constants';
 import { log } from '../logger';
 import type { TriggerRunEvent } from '../types';
@@ -30,6 +29,17 @@ const VITEST_WORKSPACE_FILE_EXTENSION = ['ts', 'js', 'json'];
 // We have to tell Vitest that it runs as part of Storybook
 process.env.VITEST_STORYBOOK = 'true';
 
+/**
+ * The Storybook vitest plugin adds double space characters so that it's possible to do a regex for
+ * all test run use cases. Otherwise, if there were two unrelated stories like "Primary Button" and
+ * "Primary Button Mobile", once you run tests for "Primary Button" and its children it would also
+ * match "Primary Button Mobile". As it turns out, this limitation is also present in the Vitest
+ * VSCode extension and the issue would occur with normal vitest tests as well, but because we use
+ * double spaces, we circumvent the issue.
+ */
+export const DOUBLE_SPACES = '  ';
+const getTestName = (name: string) => `${name}${DOUBLE_SPACES}`;
+
 export class VitestManager {
   vitest: Vitest | null = null;
 
@@ -168,7 +178,7 @@ export class VitestManager {
     });
   }
 
-  private async fetchStories(requestStoryIds?: string[]) {
+  private async fetchStories(requestStoryIds?: string[]): Promise<StoryIndexEntry[]> {
     const indexUrl = this.testManager.store.getState().indexUrl;
     if (!indexUrl) {
       throw new Error(
@@ -264,18 +274,50 @@ export class VitestManager {
     await this.cancelCurrentRun();
 
     const testSpecifications = await this.getStorybookTestSpecifications();
-    const stories = await this.fetchStories(runPayload?.storyIds);
+    const allStories = await this.fetchStories();
+
+    const filteredStories = runPayload.storyIds
+      ? allStories.filter((story) => runPayload.storyIds?.includes(story.id))
+      : allStories;
 
     const isSingleStoryRun = runPayload.storyIds?.length === 1;
     if (isSingleStoryRun) {
-      const storyName = stories[0].name;
-      const regex = new RegExp(`^${storyName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`);
+      const selectedStory = filteredStories.find((story) => story.id === runPayload.storyIds?.[0]);
+      if (!selectedStory) {
+        throw new Error(`Story ${runPayload.storyIds?.[0]} not found`);
+      }
+
+      const storyName = selectedStory.name;
+      let regex: RegExp;
+
+      const isParentStory = allStories.some((story) => selectedStory.id === story.parent);
+      const hasParentStory = allStories.some((story) => selectedStory.parent === story.id);
+
+      if (isParentStory) {
+        // Use case 1: "Single" story run on a story with tests
+        // -> run all tests of that story, as storyName is a describe block
+        const parentName = getTestName(selectedStory.name);
+        regex = new RegExp(`^${parentName}`);
+      } else if (hasParentStory) {
+        // Use case 2: Single story run on a specific story test
+        // in this case the regex pattern should be the story parentName + space + story.name
+        const parentStory = allStories.find((story) => story.id === selectedStory.parent);
+        if (!parentStory) {
+          throw new Error(`Parent story not found for story ${selectedStory.id}`);
+        }
+
+        const parentName = getTestName(parentStory.name);
+        regex = new RegExp(`^${parentName} ${storyName}$`);
+      } else {
+        // Use case 3: Single story run on a story without tests, should be exact match of story name
+        regex = new RegExp(`^${storyName}$`);
+      }
       this.vitest!.setGlobalTestNamePattern(regex);
     }
 
     const { filteredTestSpecifications, filteredStoryIds } = this.filterTestSpecifications(
       testSpecifications,
-      stories
+      filteredStories
     );
 
     this.testManager.store.setState((s) => ({

code/addons/vitest/src/vitest-plugin/index.ts

@@ -144,6 +144,7 @@ export const storybookTest = async (options?: UserOptions): Promise<Plugin[]> =>
     previewLevelTags,
     core,
     extraOptimizeDeps,
+    features,
   ] = await Promise.all([
     getStoryGlobsAndFiles(presets, directories),
     presets.apply('framework', undefined),
@@ -153,6 +154,7 @@ export const storybookTest = async (options?: UserOptions): Promise<Plugin[]> =>
     extractTagsFromPreview(finalOptions.configDir),
     presets.apply('core'),
     presets.apply('optimizeViteDeps', []),
+    presets.apply('features', {}),
   ]);
 
   const pluginsToIgnore = [
@@ -332,6 +334,7 @@ export const storybookTest = async (options?: UserOptions): Promise<Plugin[]> =>
           ...(frameworkName?.includes('vue3')
             ? { __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false' }
             : {}),
+          FEATURES: JSON.stringify(features),
         },
       };
 

code/addons/vitest/src/vitest-plugin/test-utils.ts

@@ -1,6 +1,7 @@
 import { type RunnerTask, type TaskMeta, type TestContext } from 'vitest';
 
-import type { ComponentAnnotations, ComposedStoryFn } from 'storybook/internal/types';
+import { type Meta, type Story, getStoryChildren, isStory, toTestId } from 'storybook/internal/csf';
+import type { ComponentAnnotations, ComposedStoryFn, Renderer } from 'storybook/internal/types';
 
 import { server } from '@vitest/browser/context';
 import { type Report, composeStory, getCsfFactoryAnnotations } from 'storybook/preview-api';
@@ -32,14 +33,24 @@ export const convertToFilePath = (url: string): string => {
 
 export const testStory = (
   exportName: string,
-  story: ComposedStoryFn,
-  meta: ComponentAnnotations,
-  skipTags: string[]
+  story: ComposedStoryFn | Story<Renderer>,
+  meta: ComponentAnnotations | Meta<Renderer>,
+  skipTags: string[],
+  storyId: string,
+  testName?: string
 ) => {
   return async (context: TestContext & { story: ComposedStoryFn }) => {
     const annotations = getCsfFactoryAnnotations(story, meta);
+
+    const test =
+      isStory(story) && testName
+        ? getStoryChildren(story).find((child) => child.input.name === testName)
+        : undefined;
+
+    const storyAnnotations = test ? test.input : annotations.story;
+
     const composedStory = composeStory(
-      annotations.story,
+      storyAnnotations,
       annotations.meta!,
       { initialGlobals: (await getInitialGlobals?.()) ?? {} },
       annotations.preview ?? globalThis.globalProjectAnnotations,
@@ -55,10 +66,14 @@ export const testStory = (
     const _task = context.task as RunnerTask & {
       meta: TaskMeta & { storyId: string; reports: Report[] };
     };
-    _task.meta.storyId = composedStory.id;
+
+    // The id will always be present, calculated by CsfFile
+    // and is needed so that we can add the test to the story in Storybook's UI for the status
+    _task.meta.storyId = storyId;
 
     await setViewport(composedStory.parameters, composedStory.globals);
-    await composedStory.run();
+
+    await composedStory.run(undefined);
 
     _task.meta.reports = composedStory.reporting.reports;
   };