Test: Add mount property to the story context

code/addons/links/package.json

@@ -67,7 +67,7 @@
  "prep": "node --loader ../../../scripts/node_modules/esbuild-register/loader.js -r ../../../scripts/node_modules/esbuild-register/register.js ../../../scripts/prepare/addon-bundle.ts"
  },
  "dependencies": {
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/global": "^5.0.0",
  "ts-dedent": "^2.0.0"
  },

code/lib/codemod/package.json

@@ -57,7 +57,7 @@
  "@babel/core": "^7.24.4",
  "@babel/preset-env": "^7.24.4",
  "@babel/types": "^7.24.0",
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/csf-tools": "workspace:*",
  "@storybook/node-logger": "workspace:*",
  "@storybook/types": "workspace:*",

code/lib/core-events/package.json

@@ -78,7 +78,7 @@
  "prep": "node --loader ../../../scripts/node_modules/esbuild-register/loader.js -r ../../../scripts/node_modules/esbuild-register/register.js ../../../scripts/prepare/bundle.ts"
  },
  "dependencies": {
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "ts-dedent": "^2.0.0"
  },
  "devDependencies": {

code/lib/core-events/src/errors/preview-errors.ts

@@ -238,6 +238,63 @@ export class StoryStoreAccessedBeforeInitializationError extends StorybookError
  }
 }
 
+export class MountMustBeDestructured extends StorybookError {
+ readonly category = Category.PREVIEW_API;
+
+ readonly code = 12;
+
+ constructor(public data: { playFunction: string }) {
+ super();
+ }
+
+ template() {
+ return dedent`
+ To use mount in the play function, you must use object destructuring, e.g. play: ({ mount }) => {}.
+
+ Instead received:
+ ${this.data.playFunction}
+ `;
+ }
+}
+
+export class TestingLibraryMustBeConfigured extends StorybookError {
+ readonly category = Category.PREVIEW_API;
+
+ readonly code = 13;
+
+ template() {
+ return dedent`
+ You must configure testingLibraryRender to use play in portable stories.
+
+ import { render } from '@testing-library/[renderer]';
+
+ setProjectAnnotations({
+ testingLibraryRender: render,
+ });
+
+ For other testing renderers, you can configure renderToCanvas:
+
+ import { render } from 'your-renderer';
+
+ setProjectAnnotations({
+ renderToCanvas: ({ storyFn }) => {
+ const Story = storyFn();
+
+ // Svelte
+ render(Story.Component, Story.props);
+
+ // Vue
+ render(Story);
+
+ // or for React
+ render(<Story/>);
+ },
+ });
+
+ `;
+ }
+}
+
 export class NextJsSharpError extends StorybookError {
  readonly category = Category.FRAMEWORK_NEXTJS;
 

code/lib/core-server/package.json

@@ -63,7 +63,7 @@
  "@storybook/channels": "workspace:*",
  "@storybook/core-common": "workspace:*",
  "@storybook/core-events": "workspace:*",
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/csf-tools": "workspace:*",
  "@storybook/docs-mdx": "3.1.0-next.0",
  "@storybook/global": "^5.0.0",

code/lib/csf-tools/package.json

@@ -46,7 +46,7 @@
  "@babel/parser": "^7.24.4",
  "@babel/traverse": "^7.24.1",
  "@babel/types": "^7.24.0",
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/types": "workspace:*",
  "fs-extra": "^11.1.0",
  "recast": "^0.23.5",

code/lib/manager-api/package.json

@@ -47,7 +47,7 @@
  "@storybook/channels": "workspace:*",
  "@storybook/client-logger": "workspace:*",
  "@storybook/core-events": "workspace:*",
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/global": "^5.0.0",
  "@storybook/icons": "^1.2.5",
  "@storybook/router": "workspace:*",

code/lib/preview-api/package.json

@@ -47,7 +47,7 @@
  "@storybook/channels": "workspace:*",
  "@storybook/client-logger": "workspace:*",
  "@storybook/core-events": "workspace:*",
- "@storybook/csf": "0.1.10--canary.99.ba76785.0",
+ "@storybook/csf": "0.1.10--canary.100.877a297.0",
  "@storybook/global": "^5.0.0",
  "@storybook/types": "workspace:*",
  "@types/qs": "^6.9.5",

code/lib/preview-api/src/modules/preview-web/Preview.tsx

@@ -47,6 +47,7 @@ import { StoryStore } from '../../store';
 import { StoryRender } from './render/StoryRender';
 import type { CsfDocsRender } from './render/CsfDocsRender';
 import type { MdxDocsRender } from './render/MdxDocsRender';
+import { mountDestructured } from './render/mount-utils';
 
 const { fetch } = global;
 
@@ -295,7 +296,9 @@ export class Preview<TRenderer extends Renderer> {
  await Promise.all(
  this.storyRenders
  .filter((r) => r.id === storyId && !r.renderOptions.forceInitialArgs)
- .map((r) => r.rerender())
+ .map((r) =>
+ r.story && mountDestructured(r.story.playFunction) ? r.remount() : r.rerender()
+ )
  );
 
  this.channel.emit(STORY_ARGS_UPDATED, {

code/lib/preview-api/src/modules/preview-web/PreviewWeb.test.ts

@@ -3626,6 +3626,7 @@ describe('PreviewWeb', () => {
  "dev",
  "test",
  ],
+ "testingLibraryRender": undefined,
  "title": "Component One",
  },
  "component-one--b": {
@@ -3674,6 +3675,7 @@ describe('PreviewWeb', () => {
  "dev",
  "test",
  ],
+ "testingLibraryRender": undefined,
  "title": "Component One",
  },
  "component-one--e": {
@@ -3700,6 +3702,7 @@ describe('PreviewWeb', () => {
  "dev",
  "test",
  ],
+ "testingLibraryRender": undefined,
  "title": "Component One",
  },
  "component-two--c": {
@@ -3736,6 +3739,7 @@ describe('PreviewWeb', () => {
  "dev",
  "test",
  ],
+ "testingLibraryRender": undefined,
  "title": "Component Two",
  },
  }

code/lib/preview-api/src/modules/preview-web/PreviewWithSelection.tsx

@@ -471,17 +471,9 @@ export class PreviewWithSelection<TRenderer extends Renderer> extends Preview<TR
  this.channel.emit(STORY_THREW_EXCEPTION, { name, message, stack });
  this.channel.emit(STORY_RENDER_PHASE_CHANGED, { newPhase: 'errored', storyId });
 
- // Ignored exceptions exist for control flow purposes, and are typically handled elsewhere.
- //
- // FIXME: Should be '=== IGNORED_EXCEPTION', but currently the object
- // is coming from two different bundles (index.js vs index.mjs)
- //
- // https://github.com/storybookjs/storybook/issues/19321
- if (!error.message?.startsWith('ignoredException')) {
- this.view.showErrorDisplay(error);
- logger.error(`Error rendering story '${storyId}':`);
- logger.error(error);
- }
+ this.view.showErrorDisplay(error);
+ logger.error(`Error rendering story '${storyId}':`);
+ logger.error(error);
  }
 
  // renderError is used by the various app layers to inform the user they have done something

code/lib/preview-api/src/modules/preview-web/render/StoryRender.test.ts

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 import { describe, it, expect, vi } from 'vitest';
 import { Channel } from '@storybook/channels';
-import type { Renderer, StoryIndexEntry } from '@storybook/types';
+import type { Renderer, StoryContext, StoryIndexEntry } from '@storybook/types';
 import type { StoryStore } from '../../store';
 import { PREPARE_ABORTED } from './Render';
 
@@ -26,6 +26,13 @@ const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
 
 window.location = { reload: vi.fn() } as any;
 
+const mount = (context: StoryContext) => {
+ return async () => {
+ await context.renderToCanvas();
+ return {};
+ };
+};
+
 describe('StoryRender', () => {
  it('does run play function if passed autoplay=true', async () => {
  const story = {
@@ -38,6 +45,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
 
  const render = new StoryRender(
@@ -66,6 +74,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
 
  const render = new StoryRender(
@@ -86,6 +95,8 @@ describe('StoryRender', () => {
  it('only rerenders once when triggered multiple times while pending', async () => {
  // Arrange - setup StoryRender and async gate blocking applyLoaders
  const [loaderGate, openLoaderGate] = createGate();
+ const renderToScreen = vi.fn();
+
  const story = {
  id: 'id',
  title: 'title',
@@ -96,13 +107,13 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
  const store = {
  getStoryContext: () => ({}),
  cleanupStory: vi.fn(),
  addCleanupCallbacks: vi.fn(),
  };
- const renderToScreen = vi.fn();
  const render = new StoryRender(
  new Channel({}),
  store as any,
@@ -182,6 +193,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
  const store = {
  getStoryContext: () => ({}),
@@ -225,6 +237,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
  const store = {
  getStoryContext: () => ({}),
@@ -271,6 +284,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(() => playGate),
  prepareContext: vi.fn(),
+ mount,
  };
  const store = {
  getStoryContext: () => ({}),
@@ -317,6 +331,7 @@ describe('StoryRender', () => {
  unboundStoryFn: vi.fn(),
  playFunction: vi.fn(),
  prepareContext: vi.fn(),
+ mount,
  };
  const store = {
  getStoryContext: () => ({}),

code/lib/preview-api/src/modules/preview-web/render/StoryRender.ts

@@ -19,6 +19,8 @@ import {
 import type { StoryStore } from '../../store';
 import type { Render, RenderType } from './Render';
 import { PREPARE_ABORTED } from './Render';
+import { getUsedProps } from './mount-utils';
+import { MountMustBeDestructured } from '@storybook/core-events/preview-errors';
 
 const { AbortController } = globalThis;
 
@@ -178,6 +180,8 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
  // abort controller may be torn down (above) before we actually check the signal.
  const abortSignal = (this.abortController as AbortController).signal;
 
+ let mounted = false;
+
  try {
  const context: StoryContext<TRenderer> = {
  ...this.storyContext(),
@@ -188,8 +192,17 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
  step: (label, play) => runStep(label, play, context),
  context: null!,
  canvas: {},
+ mount: null!,
+ renderToCanvas: async () => {
+ await this.runPhase(abortSignal, 'rendering', async () => {
+ const teardown = await this.renderToScreen(renderContext, canvasElement);
+ this.teardownRender = teardown || (() => {});
+ mounted = true;
+ });
+ },
  };
  context.context = context;
+ context.mount = this.story.mount(context);
 
  const renderContext: RenderContext<TRenderer> = {
  componentId,
@@ -226,10 +239,11 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
 
  if (abortSignal.aborted) return;
 
- await this.runPhase(abortSignal, 'rendering', async () => {
- const teardown = await this.renderToScreen(renderContext, canvasElement);
- this.teardownRender = teardown || (() => {});
- });
+ const mountDestructured = playFunction && getUsedProps(playFunction).includes('mount');
+
+ if (!mounted && !mountDestructured) {
+ await context.mount();
+ }
 
  this.notYetRendered = false;
  if (abortSignal.aborted) return;
@@ -247,6 +261,11 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
  window.addEventListener('unhandledrejection', onError);
  this.disableKeyListeners = true;
  try {
+ if (!mountDestructured) {
+ context.mount = async () => {
+ throw new MountMustBeDestructured({ playFunction: playFunction.toString() });
+ };
+ }
  await this.runPhase(abortSignal, 'playing', async () => {
  await playFunction(context);
  });

code/lib/preview-api/src/modules/preview-web/render/mount-utils.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from 'vitest';
+import { getUsedProps } from './mount-utils';
+
+const StoryWithContext = {
+ play: async (context: any) => {
+ console.log(context);
+ },
+};
+
+const StoryWitCanvasElement = {
+ play: async ({ canvasElement }: any) => {
+ console.log(canvasElement);
+ },
+};
+
+const MountStory = {
+ play: async ({ mount }: any) => {
+ await mount();
+ },
+};
+
+test('Detect destructure', () => {
+ expect(getUsedProps(StoryWithContext.play)).toMatchInlineSnapshot(`[]`);
+ expect(getUsedProps(StoryWitCanvasElement.play)).toMatchInlineSnapshot(`
+ [
+ "canvasElement",
+ ]
+ `);
+
+ expect(getUsedProps(MountStory.play)).toMatchInlineSnapshot(`
+ [
+ "mount",
+ ]
+ `);
+});