Core: Introduce Reporting API and STORY_COMPLETED Event

code/addons/interactions/src/components/InteractionsPanel.stories.tsx

@@ -56,6 +56,17 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Passing: Story = {
+  // TODO: Remove after prototyping
+  beforeEach: async ({ reporting }) => {
+    reporting.addReport({
+      id: 'a11y',
+      status: 'passed',
+      version: 1,
+      result: {
+        violations: [{ id: 'a11y', impact: 'critical', description: 'A11y violation' }],
+      },
+    });
+  },
   args: {
     interactions: getInteractions(CallStates.DONE),
   },

code/addons/test/src/node/reporter.ts

@@ -6,6 +6,7 @@ import type {
   TestingModuleProgressReportPayload,
   TestingModuleProgressReportProgress,
 } from 'storybook/internal/core-events';
+import type { Report } from 'storybook/internal/preview-api';
 
 import type { API_StatusUpdate } from '@storybook/types';
 
@@ -26,13 +27,15 @@ export type TestResultResult =
       storyId: string;
       testRunId: string;
       duration: number;
+      reports: Report[];
     }
   | {
       status: 'failed';
       storyId: string;
       duration: number;
       testRunId: string;
       failureMessages: string[];
+      reports: Report[];
     };
 
 export type TestResult = {
@@ -113,16 +116,26 @@ export class StorybookReporter implements Reporter {
 
         const status = StatusMap[t.result?.state || t.mode] || 'skipped';
         const storyId = (t.meta as any).storyId as string;
+        const reports = (t.meta as any).reports as Report[];
         const duration = t.result?.duration || 0;
         const testRunId = this.start.toString();
 
         switch (status) {
           case 'passed':
           case 'pending':
-            return [{ status, storyId, duration, testRunId } as TestResultResult];
+            return [{ status, storyId, duration, testRunId, reports } as TestResultResult];
           case 'failed':
             const failureMessages = t.result?.errors?.map((e) => e.stack || e.message) || [];
-            return [{ status, storyId, duration, failureMessages, testRunId } as TestResultResult];
+            return [
+              {
+                status,
+                storyId,
+                duration,
+                failureMessages,
+                testRunId,
+                reports,
+              } as TestResultResult,
+            ];
           default:
             return [];
         }

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

@@ -3,7 +3,7 @@
 /* eslint-disable no-underscore-dangle */
 import { type RunnerTask, type TaskContext, type TaskMeta, type TestContext } from 'vitest';
 
-import { composeStory } from 'storybook/internal/preview-api';
+import { type Report, composeStory } from 'storybook/internal/preview-api';
 import type { ComponentAnnotations, ComposedStoryFn } from 'storybook/internal/types';
 
 import { setViewport } from './viewports';
@@ -22,10 +22,14 @@ export const testStory = (
 
     context.story = composedStory;
 
-    const _task = context.task as RunnerTask & { meta: TaskMeta & { storyId: string } };
+    const _task = context.task as RunnerTask & {
+      meta: TaskMeta & { storyId: string; reports: Report[] };
+    };
     _task.meta.storyId = composedStory.id;
 
     await setViewport(composedStory.parameters, composedStory.globals);
     await composedStory.run();
+
+    _task.meta.reports = composedStory.reporting.reports;
   };
 };

code/core/src/core-events/index.ts

@@ -32,6 +32,7 @@ enum events {
   STORY_CHANGED = 'storyChanged',
   STORY_UNCHANGED = 'storyUnchanged',
   STORY_RENDERED = 'storyRendered',
+  STORY_COMPLETED = 'storyCompleted',
   STORY_MISSING = 'storyMissing',
   STORY_ERRORED = 'storyErrored',
   STORY_THREW_EXCEPTION = 'storyThrewException',
@@ -140,6 +141,7 @@ export const {
   STORY_PREPARED,
   STORY_RENDER_PHASE_CHANGED,
   STORY_RENDERED,
+  STORY_COMPLETED,
   STORY_SPECIFIED,
   STORY_THREW_EXCEPTION,
   STORY_UNCHANGED,

code/core/src/manager/globals/exports.ts

@@ -797,6 +797,7 @@ export default {
     'STORIES_EXPAND_ALL',
     'STORY_ARGS_UPDATED',
     'STORY_CHANGED',
+    'STORY_COMPLETED',
     'STORY_ERRORED',
     'STORY_INDEX_INVALIDATED',
     'STORY_MISSING',
@@ -861,6 +862,7 @@ export default {
     'STORIES_EXPAND_ALL',
     'STORY_ARGS_UPDATED',
     'STORY_CHANGED',
+    'STORY_COMPLETED',
     'STORY_ERRORED',
     'STORY_INDEX_INVALIDATED',
     'STORY_MISSING',
@@ -925,6 +927,7 @@ export default {
     'STORIES_EXPAND_ALL',
     'STORY_ARGS_UPDATED',
     'STORY_CHANGED',
+    'STORY_COMPLETED',
     'STORY_ERRORED',
     'STORY_INDEX_INVALIDATED',
     'STORY_MISSING',

code/core/src/preview-api/index.ts

@@ -60,6 +60,6 @@ export { createPlaywrightTest } from './modules/store/csf/portable-stories';
 export type { PropDescriptor } from './store';
 
 /** STORIES API */
-export { StoryStore } from './store';
+export { StoryStore, type Report, ReporterAPI } from './store';
 export { Preview, PreviewWeb, PreviewWithSelection, UrlStore, WebView } from './preview-web';
 export type { SelectionStore, View } from './preview-web';

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

@@ -1,12 +1,14 @@
 // @vitest-environment happy-dom
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { STORY_COMPLETED } from 'storybook/internal/core-events';
+
 import { Channel } from '@storybook/core/channels';
 import type { PreparedStory, Renderer, StoryContext, StoryIndexEntry } from '@storybook/core/types';
 
-import type { StoryStore } from '../../store';
+import { ReporterAPI, type StoryStore } from '../../store';
 import { PREPARE_ABORTED } from './Render';
-import { StoryRender } from './StoryRender';
+import { StoryRender, serializeError } from './StoryRender';
 
 const entry = {
   type: 'story',
@@ -48,7 +50,9 @@ const buildStory = (overrides: Partial<PreparedStory> = {}): PreparedStory =>
 
 const buildStore = (overrides: Partial<StoryStore<Renderer>> = {}): StoryStore<Renderer> =>
   ({
-    getStoryContext: () => ({}),
+    getStoryContext: () => ({
+      reporting: new ReporterAPI(),
+    }),
     addCleanupCallbacks: vi.fn(),
     cleanupStory: vi.fn(),
     ...overrides,
@@ -255,6 +259,93 @@ describe('StoryRender', () => {
     expect(actualMount).toHaveBeenCalled();
   });
 
+  it('should handle the "finished" phase correctly when the story finishes successfully', async () => {
+    // Arrange - setup StoryRender and async gate blocking finished phase
+    const [finishGate, resolveFinishGate] = createGate();
+    const story = buildStory({
+      playFunction: vi.fn(async () => {
+        await finishGate;
+      }),
+    });
+    const store = buildStore();
+
+    const channel = new Channel({});
+    const emitSpy = vi.spyOn(channel, 'emit');
+
+    const render = new StoryRender(
+      channel,
+      store,
+      vi.fn() as any,
+      {} as any,
+      entry.id,
+      'story',
+      { autoplay: true },
+      story
+    );
+
+    // Act - render, resolve finish gate, teardown
+    render.renderToElement({} as any);
+    await tick(); // go from 'loading' to 'rendering' phase
+    resolveFinishGate();
+    await tick(); // go from 'rendering' to 'finished' phase
+    render.teardown();
+
+    // Assert - ensure finished phase is handled correctly
+    expect(render.phase).toBe('finished');
+    expect(emitSpy).toHaveBeenCalledWith(STORY_COMPLETED, {
+      reporters: [],
+      status: 'success',
+      storyId: 'id',
+      unhandledExceptions: [],
+    });
+  });
+
+  it('should handle the "finished" phase correctly when the story throws an error', async () => {
+    // Arrange - setup StoryRender and async gate blocking finished phase
+    const [finishGate, rejectFinishGate] = createGate();
+    const error = new Error('Test error');
+    const story = buildStory({
+      parameters: {},
+      playFunction: vi.fn(async () => {
+        await finishGate;
+        throw error;
+      }),
+    });
+    const store = buildStore();
+
+    const channel = new Channel({});
+    const emitSpy = vi.spyOn(channel, 'emit');
+
+    const render = new StoryRender(
+      channel,
+      store,
+      vi.fn() as any,
+      {
+        showException: vi.fn(),
+      } as any,
+      entry.id,
+      'story',
+      { autoplay: true },
+      story
+    );
+
+    // Act - render, reject finish gate, teardown
+    render.renderToElement({} as any);
+    await tick(); // go from 'loading' to 'rendering' phase
+    rejectFinishGate();
+    await tick(); // go from 'rendering' to 'finished' phase
+    render.teardown();
+
+    // Assert - ensure finished phase is handled correctly
+    expect(render.phase).toBe('finished');
+    expect(emitSpy).toHaveBeenCalledWith(STORY_COMPLETED, {
+      reporters: [],
+      status: 'error',
+      storyId: 'id',
+      unhandledExceptions: [serializeError(error)],
+    });
+  });
+
   describe('teardown', () => {
     it('throws PREPARE_ABORTED if torndown during prepare', async () => {
       const [importGate, openImportGate] = createGate();

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

@@ -14,6 +14,7 @@ import type {
 
 import {
   PLAY_FUNCTION_THREW_EXCEPTION,
+  STORY_COMPLETED,
   STORY_RENDERED,
   STORY_RENDER_PHASE_CHANGED,
   UNHANDLED_ERRORS_WHILE_PLAYING,
@@ -34,10 +35,11 @@ export type RenderPhase =
   | 'playing'
   | 'played'
   | 'completed'
+  | 'finished'
   | 'aborted'
   | 'errored';
 
-function serializeError(error: any) {
+export function serializeError(error: any) {
   try {
     const { name = 'Error', message = String(error), stack } = error;
     return { name, message, stack };
@@ -288,7 +290,7 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
       const ignoreUnhandledErrors =
         this.story.parameters?.test?.dangerouslyIgnoreUnhandledErrors === true;
 
-      const unhandledErrors: Set<unknown> = new Set();
+      const unhandledErrors: Set<unknown> = new Set<unknown>();
       const onError = (event: ErrorEvent | PromiseRejectionEvent) =>
         unhandledErrors.add('error' in event ? event.error : event.reason);
 
@@ -349,9 +351,30 @@ export class StoryRender<TRenderer extends Renderer> implements Render<TRenderer
       await this.runPhase(abortSignal, 'completed', async () =>
         this.channel.emit(STORY_RENDERED, id)
       );
+
+      // The event name 'completed' is unfortunately already reserved by the STORY_RENDERED event
+      await this.runPhase(abortSignal, 'finished', async () =>
+        this.channel.emit(STORY_COMPLETED, {
+          storyId: id,
+          unhandledExceptions: !ignoreUnhandledErrors
+            ? Array.from(unhandledErrors).map(serializeError)
+            : [],
+          status: !ignoreUnhandledErrors && unhandledErrors.size > 0 ? 'error' : 'success',
+          reporters: context.reporting.reports,
+        })
+      );
     } catch (err) {
       this.phase = 'errored';
       this.callbacks.showException(err as Error);
+
+      await this.runPhase(abortSignal, 'finished', async () =>
+        this.channel.emit(STORY_COMPLETED, {
+          storyId: id,
+          unhandledExceptions: [serializeError(err)],
+          status: 'error',
+          reporters: [],
+        })
+      );
     }
 
     // If a rerender was enqueued during the render, clear the queue and render again

code/core/src/preview-api/modules/store/StoryStore.ts

@@ -45,6 +45,7 @@ import {
   prepareStory,
   processCSFFile,
 } from './csf';
+import { ReporterAPI } from './reporter-api';
 
 export function picky<T extends Record<string, any>, K extends keyof T>(
   obj: T,
@@ -253,12 +254,14 @@ export class StoryStore<TRenderer extends Renderer> {
   getStoryContext(story: PreparedStory<TRenderer>, { forceInitialArgs = false } = {}) {
     const userGlobals = this.userGlobals.get();
     const { initialGlobals } = this.userGlobals;
+    const reporting = new ReporterAPI();
     return prepareContext({
       ...story,
       args: forceInitialArgs ? story.initialArgs : this.args.get(story.id),
       initialGlobals,
       globalTypes: this.projectAnnotations.globalTypes,
       userGlobals,
+      reporting,
       globals: {
         ...userGlobals,
         ...story.storyGlobals,

code/core/src/preview-api/modules/store/csf/portable-stories.ts

@@ -26,6 +26,7 @@ import { MountMustBeDestructuredError } from '@storybook/core/preview-errors';
 import { dedent } from 'ts-dedent';
 
 import { HooksContext } from '../../../addons';
+import { ReporterAPI } from '../reporter-api';
 import { composeConfigs } from './composeConfigs';
 import { getValuesFromArgTypes } from './getValuesFromArgTypes';
 import { normalizeComponentAnnotations } from './normalizeComponentAnnotations';
@@ -146,12 +147,15 @@ export function composeStory<TRenderer extends Renderer = Renderer, TArgs extend
     ...story.storyGlobals,
   };
 
+  const reporting = new ReporterAPI();
+
   const initializeContext = () => {
     const context: StoryContext<TRenderer> = prepareContext({
       hooks: new HooksContext(),
       globals,
       args: { ...story.initialArgs },
       viewMode: 'story',
+      reporting,
       loaded: {},
       abortSignal: new AbortController().signal,
       step: (label, play) => story.runStep(label, play, context),
@@ -258,6 +262,7 @@ export function composeStory<TRenderer extends Renderer = Renderer, TArgs extend
       argTypes: story.argTypes as StrictArgTypes<TArgs>,
       play: playFunction!,
       run,
+      reporting,
       tags: story.tags,
     }
   );

code/core/src/preview-api/modules/store/index.ts

@@ -10,3 +10,4 @@ export * from './decorators';
 export * from './args';
 export * from './autoTitle';
 export * from './sortStories';
+export * from './reporter-api';