Merge pull request #31438 from storybookjs/valentin/stabilize-experimental-after-each

valentinpalkovic · web-flow · commit 461246769fe5 · 2025-05-12T11:00:54.000+02:00
Hooks: Stabilize experimental afterEach hook
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -24,6 +24,7 @@
     - [Story Store API Changes](#story-store-api-changes)
     - [Global State Management](#global-state-management)
     - [Experimental Status API has turned into a Status Store](#experimental-status-api-has-turned-into-a-status-store)
+    - [`experimental_afterEach` has been stabilized](#experimental_aftereach-has-been-stabilized)
     - [Testing Module Changes](#testing-module-changes)
     - [Consolidate `@storybook/blocks` into addon docs](#consolidate-storybookblocks-into-addon-docs)
   - [Configuration and Type Changes](#configuration-and-type-changes)
@@ -862,6 +863,21 @@ addons.register(MY_ADDON_ID, (api) => {
 +  }]);
 ```
 
+#### `experimental_afterEach` has been stabilized
+
+The experimental_afterEach hook has been promoted to a stable API and renamed to afterEach.
+
+To migrate, simply replace all instances of experimental_afterEach with afterEach in your stories, preview files, and configuration.
+
+```diff
+ export const MyStory = {
+-   experimental_afterEach: async ({ canvasElement }) => {
++   afterEach: async ({ canvasElement }) => {
+     // cleanup logic
+   },
+ };
+```
+
 #### Testing Module Changes
 
 The `TESTING_MODULE_RUN_ALL_REQUEST` event has been removed:
diff --git a/code/addons/a11y/src/preview.test.tsx b/code/addons/a11y/src/preview.test.tsx
@@ -4,8 +4,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { StoryContext } from 'storybook/internal/csf';
 
 import { run } from './a11yRunner';
-import { withLinkPaths } from './a11yRunnerUtils';
-import { experimental_afterEach } from './preview';
+import { afterEach } from './preview';
 import { getIsVitestRunning, getIsVitestStandaloneRun } from './utils';
 
 const mocks = vi.hoisted(() => {
@@ -107,7 +106,7 @@ describe('afterEach', () => {
 
     mockedRun.mockResolvedValue(result as any);
 
-    await expect(() => experimental_afterEach(context)).rejects.toThrow();
+    await expect(() => afterEach(context)).rejects.toThrow();
 
     expect(mockedRun).toHaveBeenCalledWith(context.parameters.a11y, context.id);
 
@@ -128,7 +127,7 @@ describe('afterEach', () => {
     mockedRun.mockResolvedValue(result as any);
     mocks.getIsVitestStandaloneRun.mockReturnValue(false);
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).toHaveBeenCalledWith(context.parameters.a11y, context.id);
 
@@ -155,7 +154,7 @@ describe('afterEach', () => {
     mockedRun.mockResolvedValue(result as any);
     mocks.getIsVitestStandaloneRun.mockReturnValue(false);
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).toHaveBeenCalledWith(context.parameters.a11y, context.id);
 
@@ -174,7 +173,7 @@ describe('afterEach', () => {
     };
     mockedRun.mockResolvedValue(result as any);
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).toHaveBeenCalledWith(context.parameters.a11y, context.id);
     expect(context.reporting.addReport).toHaveBeenCalledWith({
@@ -194,7 +193,7 @@ describe('afterEach', () => {
       },
     });
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).not.toHaveBeenCalled();
     expect(context.reporting.addReport).not.toHaveBeenCalled();
@@ -209,7 +208,7 @@ describe('afterEach', () => {
       },
     });
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).not.toHaveBeenCalled();
     expect(context.reporting.addReport).not.toHaveBeenCalled();
@@ -224,7 +223,7 @@ describe('afterEach', () => {
       },
     });
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).not.toHaveBeenCalled();
     expect(context.reporting.addReport).not.toHaveBeenCalled();
@@ -235,7 +234,7 @@ describe('afterEach', () => {
     const error = new Error('Test error');
     mockedRun.mockRejectedValue(error);
 
-    await expect(() => experimental_afterEach(context)).rejects.toThrow();
+    await expect(() => afterEach(context)).rejects.toThrow();
 
     expect(mockedRun).toHaveBeenCalledWith(context.parameters.a11y, context.id);
     expect(context.reporting.addReport).toHaveBeenCalledWith({
@@ -253,7 +252,7 @@ describe('afterEach', () => {
       viewMode: 'docs',
     });
 
-    await experimental_afterEach(context);
+    await afterEach(context);
 
     expect(mockedRun).not.toHaveBeenCalled();
     expect(context.reporting.addReport).not.toHaveBeenCalled();
diff --git a/code/addons/a11y/src/preview.tsx b/code/addons/a11y/src/preview.tsx
@@ -8,7 +8,7 @@ import { getIsVitestStandaloneRun } from './utils';
 
 let vitestMatchersExtended = false;
 
-export const experimental_afterEach: AfterEach<any> = async ({
+export const afterEach: AfterEach<any> = async ({
   id: storyId,
   reporting,
   parameters,
diff --git a/code/core/src/components/components/Checkbox/Checkbox.stories.tsx b/code/core/src/components/components/Checkbox/Checkbox.stories.tsx
@@ -31,7 +31,7 @@ export const All: Story = {
       <small>(native)</small>
     </div>
   ),
-  experimental_afterEach: async ({ canvasElement }) => {
+  afterEach: async ({ canvasElement }) => {
     canvasElement.querySelectorAll<HTMLInputElement>('[data-indeterminate]').forEach((checkbox) => {
       checkbox.indeterminate = true;
     });
@@ -52,7 +52,7 @@ export const Checked: Story = {
 };
 
 export const Indeterminate: Story = {
-  experimental_afterEach: async ({ canvasElement }) => {
+  afterEach: async ({ canvasElement }) => {
     canvasElement.getElementsByTagName('input')[0].indeterminate = true;
   },
 };
@@ -74,7 +74,7 @@ export const DisabledIndeterminate: Story = {
   args: {
     disabled: true,
   },
-  experimental_afterEach: async ({ canvasElement }) => {
+  afterEach: async ({ canvasElement }) => {
     canvasElement.getElementsByTagName('input')[0].indeterminate = true;
   },
 };
diff --git a/code/core/src/csf/story.test.ts b/code/core/src/csf/story.test.ts
@@ -58,7 +58,7 @@ const simple: XMeta = {
     await doSomething();
     return cleanup;
   },
-  async experimental_afterEach() {
+  async afterEach() {
     await validateSomething();
   },
   args: { x: '1' },
@@ -77,7 +77,7 @@ const strict: XMeta<ButtonArgs> = {
     await doSomething();
     return cleanup;
   },
-  async experimental_afterEach() {
+  async afterEach() {
     await validateSomething();
   },
   argTypes: { x: { type: { name: 'string' } } },
diff --git a/code/core/src/csf/story.ts b/code/core/src/csf/story.ts
@@ -370,7 +370,7 @@ export interface BaseAnnotations<TRenderer extends Renderer = Renderer, TArgs =
    * `afterEach` can be added to preview, the default export and to a specific story. They are run
    * (and awaited) reverse order: preview, default export, story
    */
-  experimental_afterEach?: AfterEach<TRenderer, TArgs>[] | AfterEach<TRenderer, TArgs>;
+  afterEach?: AfterEach<TRenderer, TArgs>[] | AfterEach<TRenderer, TArgs>;
 
   /**
    * Define a custom render function for the story(ies). If not passed, a default render function by
diff --git a/code/core/src/preview-api/modules/store/csf/composeConfigs.test.ts b/code/core/src/preview-api/modules/store/csf/composeConfigs.test.ts
@@ -24,7 +24,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -52,7 +52,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -84,7 +84,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -122,7 +122,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -163,7 +163,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -195,7 +195,7 @@ describe('composeConfigs', () => {
       loaders: ['1', '2', '3', '4'],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -227,7 +227,7 @@ describe('composeConfigs', () => {
       loaders: ['1', '2', '3'],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -255,7 +255,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -284,7 +284,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       runStep: expect.any(Function),
       tags: [],
     });
@@ -316,7 +316,7 @@ describe('composeConfigs', () => {
       loaders: [],
       beforeAll: expect.any(Function),
       beforeEach: [],
-      experimental_afterEach: [],
+      afterEach: [],
       render: 'render-2',
       renderToCanvas: 'renderToCanvas-2',
       applyDecorators: 'applyDecorators-2',
diff --git a/code/core/src/preview-api/modules/store/csf/composeConfigs.ts b/code/core/src/preview-api/modules/store/csf/composeConfigs.ts
@@ -64,7 +64,7 @@ export function composeConfigs<TRenderer extends Renderer>(
     loaders: getArrayField(moduleExportList, 'loaders'),
     beforeAll: composeBeforeAllHooks(beforeAllHooks),
     beforeEach: getArrayField(moduleExportList, 'beforeEach'),
-    experimental_afterEach: getArrayField(moduleExportList, 'experimental_afterEach'),
+    afterEach: getArrayField(moduleExportList, 'afterEach'),
     render: getSingletonField(moduleExportList, 'render'),
     renderToCanvas: getSingletonField(moduleExportList, 'renderToCanvas'),
     applyDecorators: getSingletonField(moduleExportList, 'applyDecorators'),
diff --git a/code/core/src/preview-api/modules/store/csf/normalizeProjectAnnotations.ts b/code/core/src/preview-api/modules/store/csf/normalizeProjectAnnotations.ts
@@ -21,7 +21,7 @@ export function normalizeProjectAnnotations<TRenderer extends Renderer>({
   decorators,
   loaders,
   beforeEach,
-  experimental_afterEach,
+  afterEach,
   initialGlobals,
   ...annotations
 }: ProjectAnnotations<TRenderer>): NormalizedProjectAnnotations<TRenderer> {
@@ -31,7 +31,7 @@ export function normalizeProjectAnnotations<TRenderer extends Renderer>({
     decorators: normalizeArrays(decorators),
     loaders: normalizeArrays(loaders),
     beforeEach: normalizeArrays(beforeEach),
-    experimental_afterEach: normalizeArrays(experimental_afterEach),
+    afterEach: normalizeArrays(afterEach),
     argTypesEnhancers: [
       ...(argTypesEnhancers || []),
       inferArgTypes,
diff --git a/code/core/src/preview-api/modules/store/csf/normalizeStory.test.ts b/code/core/src/preview-api/modules/store/csf/normalizeStory.test.ts
@@ -52,11 +52,11 @@ describe('normalizeStory', () => {
       const meta = { id: 'title', title: 'title' };
       expect(normalizeStory('storyExport', storyFn, meta)).toMatchInlineSnapshot(`
         {
+          "afterEach": [],
           "argTypes": {},
           "args": {},
           "beforeEach": [],
           "decorators": [],
-          "experimental_afterEach": [],
           "globals": {},
           "id": "title--story-export",
           "loaders": [],
@@ -124,11 +124,11 @@ describe('normalizeStory', () => {
         const normalized = normalizeStory('storyExport', storyObj, meta);
         expect(normalized).toMatchInlineSnapshot(`
           {
+            "afterEach": [],
             "argTypes": {},
             "args": {},
             "beforeEach": [],
             "decorators": [],
-            "experimental_afterEach": [],
             "globals": {},
             "id": "title--story-export",
             "loaders": [],
@@ -154,6 +154,7 @@ describe('normalizeStory', () => {
         const { moduleExport, ...normalized } = normalizeStory('storyExport', storyObj, meta);
         expect(normalized).toMatchInlineSnapshot(`
           {
+            "afterEach": [],
             "argTypes": {
               "storyArgType": {
                 "name": "storyArgType",
@@ -169,7 +170,6 @@ describe('normalizeStory', () => {
             "decorators": [
               [Function],
             ],
-            "experimental_afterEach": [],
             "globals": {},
             "id": "title--story-export",
             "loaders": [
@@ -205,6 +205,7 @@ describe('normalizeStory', () => {
         const { moduleExport, ...normalized } = normalizeStory('storyExport', storyObj, meta);
         expect(normalized).toMatchInlineSnapshot(`
           {
+            "afterEach": [],
             "argTypes": {
               "storyArgType": {
                 "name": "storyArgType",
@@ -228,7 +229,6 @@ describe('normalizeStory', () => {
               [Function],
               [Function],
             ],
-            "experimental_afterEach": [],
             "globals": {},
             "id": "title--story-export",
             "loaders": [
diff --git a/code/core/src/preview-api/modules/store/csf/normalizeStory.ts b/code/core/src/preview-api/modules/store/csf/normalizeStory.ts
@@ -58,9 +58,9 @@ export function normalizeStory<TRenderer extends Renderer>(
     ...normalizeArrays(story?.beforeEach),
   ];
 
-  const experimental_afterEach = [
-    ...normalizeArrays(storyObject.experimental_afterEach),
-    ...normalizeArrays(story?.experimental_afterEach),
+  const afterEach = [
+    ...normalizeArrays(storyObject.afterEach),
+    ...normalizeArrays(story?.afterEach),
   ];
   const { render, play, tags = [], globals = {} } = storyObject;
 
@@ -76,7 +76,7 @@ export function normalizeStory<TRenderer extends Renderer>(
     argTypes: normalizeInputTypes(argTypes),
     loaders,
     beforeEach,
-    experimental_afterEach,
+    afterEach,
     globals,
     ...(render && { render }),
     ...(userStoryFn && { userStoryFn }),
diff --git a/code/core/src/preview-api/modules/store/csf/prepareStory.ts b/code/core/src/preview-api/modules/store/csf/prepareStory.ts
@@ -88,9 +88,9 @@ export function prepareStory<TRenderer extends Renderer>(
 
   const applyAfterEach = async (context: StoryContext<TRenderer>): Promise<void> => {
     const reversedFinalizers = [
-      ...normalizeArrays(projectAnnotations.experimental_afterEach),
-      ...normalizeArrays(componentAnnotations.experimental_afterEach),
-      ...normalizeArrays(storyAnnotations.experimental_afterEach),
+      ...normalizeArrays(projectAnnotations.afterEach),
+      ...normalizeArrays(componentAnnotations.afterEach),
+      ...normalizeArrays(storyAnnotations.afterEach),
     ].reverse();
     for (const finalizer of reversedFinalizers) {
       if (context.abortSignal.aborted) {
diff --git a/code/core/template/stories/order-of-hooks.stories.ts b/code/core/template/stories/order-of-hooks.stories.ts
