Merge pull request #17967 from storybookjs/chore_docs_testing_docs_updates_6_5

Chore: (Docs) Storybook 6.5 testing updates

docs/snippets/angular/login-form-with-play-function.mdx.mdx

@@ -5,6 +5,8 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import { LoginForm } from './LoginForm.component';
 
 <Meta title="Form" component={LoginForm} />
@@ -13,7 +15,7 @@ export const Template = (args) => ({ props: args });
 
 <Canvas>
   <Story name="Empty Form">
-    {Template.bind(())}
+    {Template.bind({})}
   </Story>
 
   <Story
@@ -22,17 +24,22 @@ export const Template = (args) => ({ props: args });
       // Starts querying the component from its root element
       const canvas = within(canvasElement);
 
-      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-        delay: 100,
-      });
-      await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-        delay: 100,
-      });
+      // 👇 Simulate interactions with the component
+      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+      await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
+
       // See https://storybook.js.org/docs/angular/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
       await userEvent.click(canvas.getByRole('button'));
+
+      // 👇 Assert DOM structure
+      await expect(
+        canvas.getByText(
+          'Everything is perfect. Your account is ready and we should probably get you started!'
+        )
+      ).toBeInTheDocument();
     }}>
     {Template.bind({})}
   </Story>
-
 </Canvas>
 ```

docs/snippets/angular/login-form-with-play-function.ts.mdx

@@ -5,6 +5,8 @@ import { Meta, Story } from '@storybook/angular';
 
 import { userEvent, within } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import { LoginForm } from './LoginForm.component';
 
 export default {
@@ -27,14 +29,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/angular/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
 ```

docs/snippets/common/component-cypress-test.js.mdx

@@ -8,7 +8,7 @@ describe('Login Form', () => {
     cy.visit('/iframe.html?id=components-login-form--example');
     cy.get('#login-form').within(() => {
       cy.log('**enter the email**');
-      cy.get('#email').should('have.value', 'your-own-emailaddress@provider.com');
+      cy.get('#email').should('have.value', 'email@provider.com');
       cy.log('**enter password**');
       cy.get('#password').should('have.value', 'a-random-password');
     });

docs/snippets/common/component-playwright-test.js.mdx

@@ -7,7 +7,7 @@ test('Login Form inputs', async ({ page }) => {
   await page.goto('http://localhost:6006/iframe.html?id=components-login-form--example');
   const email = await page.inputValue('#email');
   const password = await page.inputValue('#password');
-  await expect(email).toBe('your-own-emailaddress@provider.com');
+  await expect(email).toBe('email@provider.com');
   await expect(password).toBe('a-random-password');
 });
 ```

docs/snippets/common/storybook-a11y-install.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm install @storybook/addon-a11y --save-dev
+```

docs/snippets/common/storybook-a11y-install.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn add --dev @storybook/addon-a11y
+```

docs/snippets/common/storybook-a11y-register.js.mdx

@@ -2,11 +2,10 @@
 // .storybook/main.js
 
 module.exports = {
-  stories:[],
-  addons:[
-    '@storybook/addon-links',
-    '@storybook/addon-essentials',
-    '@storybook/preset-create-react-app',
+  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  addons: [
+    // Other Storybook addons
     '@storybook/addon-a11y', //👈 The a11y addon goes here
+  ],
 };
-```
+```

docs/snippets/common/storybook-a11y-register.ts.mdx

@@ -0,0 +1,16 @@
+```ts
+// .storybook/main.ts
+
+// Imports Storybook's configuration API
+import type { StorybookConfig } from '@storybook/core-common';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  addons: [
+    // Other Storybook addons
+    '@storybook/addon-a11y', //👈 The a11y addon goes here
+  ],
+};
+
+module.exports = config;
+```

docs/snippets/common/storybook-addon-interactions-addon-full-install.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm install @storybook/testing-library @storybook/jest @storybook/addon-interactions --save-dev
+```

docs/snippets/common/storybook-addon-interactions-addon-full-install.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn add --dev @storybook/testing-library @storybook/jest @storybook/addon-interactions
+```

docs/snippets/common/storybook-main-enable-interactive-debugger.js.mdx

@@ -0,0 +1,14 @@
+```js
+// .storybook/main.js|ts
+
+module.exports = {
+  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
+  addons: [
+    // Other Storybook addons
+    '@storybook/addon-interactions', // 👈 Addon is registered here
+  ],
+  features: {
+    interactionsDebugger: true, // 👈 Enable playback controls
+  },
+};
+```

docs/snippets/common/storybook-run-dev.npm.js.mdx

@@ -1,4 +1,3 @@
 ```shell
-# Starts Storybook in development mode
 npm run storybook
 ```

docs/snippets/common/storybook-run-dev.yarn.js.mdx

@@ -1,4 +1,3 @@
 ```shell
-# Starts Storybook in development mode
 yarn storybook
 ```

docs/snippets/common/storybook-test-runner-a11y-config.js.mdx

@@ -0,0 +1,23 @@
+```js
+// .storybook/test-runner.js
+
+const { injectAxe, checkA11y } = require('axe-playwright');
+
+/*
+* See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+* to learn more about the test-runner hooks API.
+*/
+module.exports = {
+  async preRender(page) {
+    await injectAxe(page);
+  },
+  async postRender(page) {
+    await checkA11y(page, '#root', {
+      detailedReport: true,
+      detailedReportOptions: {
+        html: true,
+      },
+    });
+  },
+};
+```

docs/snippets/common/storybook-test-runner-a11y-config.ts.mdx

@@ -0,0 +1,27 @@
+```ts
+// .storybook/test-runner.ts
+
+import { injectAxe, checkA11y } from 'axe-playwright';
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+/*
+* See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+* to learn more about the test-runner hooks API.
+*/
+const a11yConfig: TestRunnerConfig = {
+  async preRender(page) {
+    await injectAxe(page);
+  },
+  async postRender(page) {
+    await checkA11y(page, '#root', {
+      detailedReport: true,
+      detailedReportOptions: {
+        html: true,
+      },
+    });
+  },
+};
+
+module.exports = a11yConfig;
+```

docs/snippets/common/storybook-test-runner-axe-playwright.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm install axe-playwright --save-dev
+```

docs/snippets/common/storybook-test-runner-axe-playwright.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn add --dev axe-playwright
+```

docs/snippets/common/storybook-test-runner-disable-stories-json.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm run test-storybook -- --no-stories-json
+```

docs/snippets/common/storybook-test-runner-disable-stories-json.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn test-storybook --no-stories-json
+```

docs/snippets/common/storybook-test-runner-execute-with-flags.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm run test-storybook -- --watch
+```

docs/snippets/common/storybook-test-runner-execute-with-flags.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn test-storybook --watch
+```

docs/snippets/common/storybook-test-runner-execute-with-url.env-var.js.mdx

@@ -0,0 +1,3 @@
+```shell
+TARGET_URL=https://the-storybook-url-here.com yarn test-storybook
+```

docs/snippets/common/storybook-test-runner-execute-with-url.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm run test-storybook -- --url https://the-storybook-url-here.com
+```

docs/snippets/common/storybook-test-runner-execute-with-url.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn test-storybook --url https://the-storybook-url-here.com
+```

docs/snippets/common/storybook-test-runner-execute.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm run test-storybook
+```

docs/snippets/common/storybook-test-runner-execute.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn test-storybook
+```

docs/snippets/common/storybook-test-runner-hooks-example.js.mdx

@@ -0,0 +1,24 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  // Hook that is executed before the test runner starts running tests
+  setup() {
+    // Add your configuration here.
+  },
+  /* Hook to execute before a story is rendered.
+   * The page argument is the Playwright's page object for the story.
+   * The context argument is a Storybook object containing the story's id, title, and name.
+   */
+  async preRender(page, context) {
+    // Add your configuration here.
+  },
+  /* Hook to execute after a story is rendered.
+   * The page argument is the Playwright's page object for the story
+   * The context argument is a Storybook object containing the story's id, title, and name.
+   */
+  async postRender(page, context) {
+    // Add your configuration here.
+  },
+};
+```

docs/snippets/common/storybook-test-runner-hooks-example.ts.mdx

@@ -0,0 +1,28 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  // Hook that is executed before the test runner starts running tests
+  setup() {
+    // Add your configuration here.
+  },
+  /* Hook to execute before a story is rendered.
+   * The page argument is the Playwright's page object for the story.
+   * The context argument is a Storybook object containing the story's id, title, and name.
+   */
+  async preRender(page, context) {
+    // Add your configuration here.
+  },
+  /* Hook to execute after a story is rendered.
+   * The page argument is the Playwright's page object for the story
+   * The context argument is a Storybook object containing the story's id, title, and name.
+   */
+  async postRender(page, context) {
+    // Add your configuration here.
+  },
+};
+
+module.exports = config;
+```

docs/snippets/common/storybook-test-runner-install.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm install @storybook/test-runner jest --save-dev
+```

docs/snippets/common/storybook-test-runner-install.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn add --dev @storybook/test-runner jest
+```

docs/snippets/common/storybook-test-runner-local-build-workflow.yml.mdx

@@ -0,0 +1,26 @@
+```yml
+# .github/workflows/storybook-tests.yml
+
+name: 'Storybook Tests'
+on: push
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14.x'
+      - name: Install dependencies
+        run: yarn
+      - name: Install Playwright
+        run: npx playwright install --with-deps
+      - name: Build Storybook
+        run: yarn build-storybook --quiet
+      - name: Serve Storybook and run tests
+        run: |
+          npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
+            "npx http-server storybook-static --port 6006 --silent" \
+            "npx wait-on tcp:6006 && yarn test-storybook"
+```

docs/snippets/common/storybook-test-runner-with-deploy-event-workflow.yml.mdx

@@ -0,0 +1,24 @@
+```yml
+# .github/workflows/storybook-tests.yml
+
+name: Storybook Tests
+on: deployment_status
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    if: github.event.deployment_status.state == 'success'
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: '14.x'
+      - name: Install dependencies
+        run: yarn
+      - name: Install Playwright
+        run: npx playwright install --with-deps
+      - name: Run Storybook tests
+        run: yarn test-storybook
+        env:
+          TARGET_URL: '${{ github.event.deployment_status.target_url }}'
+```

docs/snippets/common/storybook-test-runner-with-stories-json.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm run test-storybook -- --stories-json
+```

docs/snippets/common/storybook-test-runner-with-stories-json.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn test-storybook --stories-json
+```

docs/snippets/common/storybook-testing-addon-install.npm.js.mdx

@@ -0,0 +1,3 @@
+```shell
+npm install --save-dev @storybook/testing-( react | vue | vue3 | angular)
+```

docs/snippets/common/storybook-testing-addon-install.yarn.js.mdx

@@ -0,0 +1,3 @@
+```shell
+yarn add --dev @storybook/testing-( react | vue | vue3 | angular )
+```

docs/snippets/react/accessibility-testing-with-jest-axe.js.mdx

@@ -1,23 +0,0 @@
-```js
-// MyComponent.test.js
-
-import { render } from '@testing-library/react';
-
-import { composeStories } from '@storybook/testing-react';
-
-import { axe, toHaveNoViolations } from 'jest-axe';
-
-import * as MyComponentStories from './MyComponent.stories';
-
-const { Accessible } = composeStories(MyComponentStories);
-
-expect.extend(toHaveNoViolations);
-
-test('Example accessibility test', async () => {
-  const { container } = render(<Accessible />);
-
-  const AxeResults = await axe(container);
-
-  expect(AxeResults).toHaveNoViolations();
-});
-```

docs/snippets/react/login-form-with-play-function.js.mdx

@@ -5,6 +5,8 @@ import React from 'react';
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import { LoginForm } from './LoginForm';
 
 export default {
@@ -25,14 +27,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+  
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
-```
+```

docs/snippets/react/login-form-with-play-function.mdx.mdx

@@ -5,6 +5,8 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import { LoginForm } from './LoginForm';
 
 <Meta title="Form" component={LoginForm} />
@@ -22,16 +24,22 @@ export const Template = (args) => <LoginForm {...args} />;
       // Starts querying the component from its root element
       const canvas = within(canvasElement);
 
-     await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-      delay: 100,
-    });
-    await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-      delay: 100,
-    });
-    // See https://storybook.js.org/docs/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
-    await userEvent.click(canvas.getByRole('button'));
-  }}>
-  {Template.bind({})}
+      // 👇 Simulate interactions with the component
+      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+      await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
+
+      // See https://storybook.js.org/docs/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
+      await userEvent.click(canvas.getByRole('button'));
+
+      // 👇 Assert DOM structure
+      await expect(
+        canvas.getByText(
+          'Everything is perfect. Your account is ready and we should probably get you started!'
+        )
+      ).toBeInTheDocument();
+    }}>
+    {Template.bind({})}
   </Story>
 </Canvas>
 ```

docs/snippets/react/login-form-with-play-function.ts.mdx

@@ -7,6 +7,8 @@ import { ComponentStory, ComponentMeta } from '@storybook/react';
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import { LoginForm } from './LoginForm';
 
 export default {
@@ -27,14 +29,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+  
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/react/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
 ```

docs/snippets/svelte/login-form-with-play-function.js.mdx

@@ -3,6 +3,8 @@
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.svelte';
 
 export default {
@@ -26,14 +28,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/svelte/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
 ```

docs/snippets/svelte/login-form-with-play-function.mdx.mdx

@@ -5,6 +5,8 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';
 
 import { within, userEvent } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.svelte';
 
 <Meta title="Form" component={LoginForm} />
@@ -22,19 +24,23 @@ export const Template = (args) => ({
   <Story
     name="Filled Form"
     play={async ({ canvasElement }) => {
-
       // Starts querying the component from its root element
       const canvas = within(canvasElement);
 
-      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-        delay: 100,
-      });
-      await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-        delay: 100,
-      });
+      // 👇 Simulate interactions
+      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+      
+      await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
       // See https://storybook.js.org/docs/svelte/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
       await userEvent.click(canvas.getByRole('button'));
+
+      // 👇 Assert DOM structure
+      await expect(
+        canvas.getByText(
+          'Everything is perfect. Your account is ready and we should probably get you started!'
+        )
+      ).toBeInTheDocument();
     }}>
     {Template.bind({})}
   </Story>

docs/snippets/vue/accessibility-testing-with-jest-axe.js.mdx

@@ -1,23 +0,0 @@
-```js
-// MyComponent.test.js
-
-import { render } from '@testing-library/vue';
-
-import { composeStories } from '@storybook/testing-vue';
-
-import { axe, toHaveNoViolations } from 'jest-axe';
-
-import * as MyComponentStories from './MyComponent.stories';
-
-const { Accessible } = composeStories(MyComponentStories);
-
-expect.extend(toHaveNoViolations);
-
-test('Example accessibility test', async () => {
-  const { container } = render(Accessible());
-
-  const AxeResults = await axe(container);
-
-  expect(AxeResults).toHaveNoViolations();
-});
-```

docs/snippets/vue/login-form-with-play-function.2.js.mdx

@@ -3,6 +3,8 @@
 
 import { userEvent, within } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.vue';
 
 export default {
@@ -27,14 +29,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/vue/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
 ```

docs/snippets/vue/login-form-with-play-function.3.js.mdx

@@ -3,6 +3,8 @@
 
 import { userEvent, within } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.vue';
 
 export default {
@@ -29,14 +31,19 @@ FilledForm.play = async ({ canvasElement }) => {
   // Starts querying the component from its root element
   const canvas = within(canvasElement);
 
-  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-    delay: 100,
-  });
-  await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-    delay: 100,
-  });
+  // 👇 Simulate interactions with the component
+  await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+  await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
   // See https://storybook.js.org/docs/vue/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
   await userEvent.click(canvas.getByRole('button'));
+
+  // 👇 Assert DOM structure
+  await expect(
+    canvas.getByText(
+      'Everything is perfect. Your account is ready and we should probably get you started!'
+    )
+  ).toBeInTheDocument();
 };
 ```

docs/snippets/vue/login-form-with-play-function.mdx-2.mdx

@@ -5,6 +5,8 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';
 
 import { userEvent, within } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.vue';
 
 <Meta title="Form" component={LoginForm} />
@@ -17,7 +19,7 @@ export const Template = (args, { argTypes }) => ({
 
 <Canvas>
   <Story name="Empty Form">
-   {Template.bind({})}
+    {Template.bind({})}
   </Story>
 
   <Story
@@ -26,15 +28,20 @@ export const Template = (args, { argTypes }) => ({
       // Starts querying the component from its root element
       const canvas = within(canvasElement);
 
-      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-        delay: 100,
-      });
-      await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-        delay: 100,
-      });
+      // 👇 Simulate interactions with the component
+      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+      await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
 
       // See https://storybook.js.org/docs/vue/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
       await userEvent.click(canvas.getByRole('button'));
+
+      // 👇 Assert DOM structure
+      await expect(
+        canvas.getByText(
+          'Everything is perfect. Your account is ready and we should probably get you started!'
+        )
+      ).toBeInTheDocument();
     }}>
     {Template.bind({})}
   </Story>

docs/snippets/vue/login-form-with-play-function.mdx-3.mdx

@@ -5,6 +5,8 @@ import { Canvas, Meta, Story } from '@storybook/addon-docs';
 
 import { userEvent, within } from '@storybook/testing-library';
 
+import { expect } from '@storybook/jest';
+
 import LoginForm from './LoginForm.vue';
 
 <Meta title="Form" component={LoginForm} />
@@ -26,17 +28,22 @@ export const Template = (args) => ({
     name="Filled Form"
     play={async ({ canvasElement }) => {
       // Starts querying the component from its root element
-
       const canvas = within(canvasElement);
 
-      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com', {
-        delay: 100,
-      });
-      await userEvent.type(canvas.getByTestId('password'), 'a-random-password', {
-        delay: 100,
-      });
+      // 👇 Simulate interactions with the component
+      await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
+
+      await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
+
       // See https://storybook.js.org/docs/vue/essentials/actions#automatically-matching-args to learn how to setup logging in the Actions panel
       await userEvent.click(canvas.getByRole('button'));
+
+      // 👇 Assert DOM structure
+      await expect(
+        canvas.getByText(
+          'Everything is perfect. Your account is ready and we should probably get you started!'
+        )
+      ).toBeInTheDocument();
     }}>
     {Template.bind({})}
   </Story>

docs/toc.js

@@ -179,6 +179,11 @@ module.exports = {
           title: 'Introduction',
           type: 'link',
         },
+        {
+          pathSegment: 'test-runner',
+          title: 'Test runner',
+          type: 'link',
+        },
         {
           pathSegment: 'visual-testing',
           title: 'Visual tests',

docs/writing-tests/accessibility-testing.md

@@ -6,29 +6,37 @@ Accessibility is the practice of making websites inclusive to all. That means su
 
 Accessibility tests audit the rendered DOM against a set of heuristics based on [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) rules and other industry-accepted best practices. They act as the first line of QA to catch blatant accessibility violations.
 
-Storybook’s official [a11y addon](https://storybook.js.org/addons/@storybook/addon-a11y) runs accessibility audits while you’re developing components to give you a fast feedback loop. It's powered by Deque's [axe-core](https://github.com/dequelabs/axe-core), which automatically catches up to [57% of WCAG issues](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/).
-
 ![Accessibility testing](./accessibility-testing-storybook.gif)
 
-## Setup a11y addon
+## Accessibility checks with a11y addon
 
-To enable accessibility testing with Storybook, you'll need to install the [`@storybook/addon-a11y`](https://storybook.js.org/addons/@storybook/addon-a11y/) addon. Run the following command:
+Storybook provides an official [a11y addon](https://storybook.js.org/addons/@storybook/addon-a11y). Powered by Deque's [axe-core](https://github.com/dequelabs/axe-core), which automatically catches up to [57% of WCAG issues](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/).
 
-```shell
-# With npm
-npm install @storybook/addon-a11y --save-dev
+### Set up the a11y addon
 
-# With yarn
-yarn add --dev @storybook/addon-a11y
-```
+If you want to check accessibility for your stories using the [addon](https://storybook.js.org/addons/@storybook/addon-a11y/), you'll need to install it and add it to your Storybook.
 
-Update your Storybook configuration (in `.storybook/main.js`) to include the accessibility addon:
+Run the following command to install the addon.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-a11y-install.yarn.js.mdx',
+    'common/storybook-a11y-install.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+Update your Storybook configuration (in `.storybook/main.js|ts`) to include the accessibility addon.
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
     'common/storybook-a11y-register.js.mdx',
+    'common/storybook-a11y-register.ts.mdx',
   ]}
 />
 
@@ -73,7 +81,7 @@ Cycling through both stories, you will see that the `Inaccessible` story contain
 
 ### Configure
 
-Out of the box, Storybook's accessibility addon includes a set of accessibility rules that cover most issues. You can also fine tune the [addon configuration](https://github.com/storybookjs/storybook/tree/next/addons/a11y#parameters) or override [Axe's ruleset](https://github.com/storybookjs/storybook/tree/next/addons/a11y#handling-failing-rules) to best suit your needs.
+Out of the box, Storybook's accessibility addon includes a set of accessibility rules that cover most issues. You can also fine-tune the [addon configuration](https://github.com/storybookjs/storybook/tree/next/addons/a11y#parameters) or override [Axe's ruleset](https://github.com/storybookjs/storybook/tree/next/addons/a11y#handling-failing-rules) to best suit your needs.
 
 #### Global a11y configuration
 
@@ -148,37 +156,65 @@ Disable accessibility testing for stories or components by adding the following
 
 <!-- prettier-ignore-end -->
 
-## Automate accessibility tests with Jest
+## Automate accessibility tests with test runner
 
-Accessibility testing with Storybook shortens the feedback loop which means you fix issues faster. Reuse stories in a Jest test and run an accessibility audit on them using the [jest-axe integration](https://github.com/nickcolley/jest-axe). That also unlocks the ability to integrate accessibility tests into your functional testing pipeline.
+The most accurate way to check accessibility is manually on real devices. However, you can use automated tools to catch common accessibility issues. For example, [Axe](https://www.deque.com/axe/), on average, catches upwards to [57% of WCAG issues](https://www.deque.com/blog/automated-testing-study-identifies-57-percent-of-digital-accessibility-issues/) automatically.
 
-For example, include the following test file to run an accessibility test on a story:
+These tools work by auditing the rendered DOM against heuristics based on [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) rules and other industry-accepted best practices. You can then integrate these tools into your test automation pipeline using the Storybook [test runner](./test-runner.md#test-hook-api-experimental) and [axe-playwright](https://github.com/abhinaba-ghosh/axe-playwright).
+
+### Setup
+
+To enable accessibility testing with the test runner, you will need to take additional steps to set it up properly. Detailed below is our recommendation to configure and execute them.
+
+Run the following command to install the required dependencies.
 
 <!-- prettier-ignore-start -->
 
 <CodeSnippets
   paths={[
-    'react/accessibility-testing-with-jest-axe.js.mdx',
-    'vue/accessibility-testing-with-jest-axe.js.mdx',
+    'common/storybook-test-runner-axe-playwright.yarn.js.mdx',
+    'common/storybook-test-runner-axe-playwright.npm.js.mdx',
   ]}
 />
 
 <!-- prettier-ignore-end -->
 
-When you execute your test script, it will run the accessibility audit along with any interaction tests you might have.
+Add a new [configuration file](./test-runner.md#test-hook-api-experimental) inside your Storybook directory with the following inside:
 
-![Accessibility testing with Jest Axe Core](./jest-accessibility-testing-optimized.png)
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-a11y-config.js.mdx',
+    'common/storybook-test-runner-a11y-config.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 `preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. They are **experimental** and subject to changes. Read more about them [here](./test-runner.md#test-hook-api-experimental).
+
+</div>
+
+When you execute the test runner (for example, with `yarn test-storybook`), it will run the accessibility audit and any [interaction tests](./interaction-testing.md) you might have configured for each component story.
+
+It starts checking for issues by traversing the DOM tree starting from the story's root element and generates a detailed report based on the issues it encountered.
+
+![Accessibility testing with the test runner](./test-runner-a11y-optimized.png)
 
 ---
 
 #### What’s the difference between browser-based and linter-based accessibility tests?
 
-Browser-based accessibility tests, like found in Storybook, evaluates the rendered DOM because that gives you the highest accuracy. Auditing code that hasn't been compiled yet is one step removed from the real thing so you won't catch everything the user might experience.
+Browser-based accessibility tests, like those found in Storybook, evaluate the rendered DOM because that gives you the highest accuracy. Auditing code that hasn't been compiled yet is one step removed from the real thing, so you won't catch everything the user might experience.
 
 #### Learn about other UI tests
 
+- [Test runner](./test-runner.md) to automate test execution
 - [Visual tests](./visual-testing.md) for appearance
 - Accessibility tests for accessibility
 - [Interaction tests](./interaction-testing.md) for user behavior simulation
 - [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
-- [Import stories in other tests](./importing-stories-in-tests.md) for other tools
+- [Import stories in other tests](./importing-stories-in-tests.md) for other tools

docs/writing-tests/importing-stories-in-tests.md

@@ -21,13 +21,22 @@ Storybook has test addons for core frameworks React, Vue (2,3), and Angular. Thi
 
 Run the following command to add Storybook's testing addon into your environment:
 
-```shell
-# With npm, don't forget to select only your framework
-npm install --save-dev @storybook/testing-( react | vue | vue3 | angular)
+<!-- prettier-ignore-start -->
 
-# With yarn, don't forget to select only your framework
-yarn add --dev @storybook/testing-( react | vue | vue3 | angular )
-```
+<CodeSnippets
+  paths={[
+    'common/storybook-testing-addon-install.yarn.js.mdx',
+    'common/storybook-testing-addon-install.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 When running the command to install the addon, don't forget to select **only** your framework.
+
+</div>
 
 ### Optional configuration
 
@@ -60,7 +69,7 @@ Update your test script to include the configuration file:
 
 ## Example with Testing Library
 
-[Testing Library](https://testing-library.com/) is a suite of helper libraries for browser-based interaction tests. With [Component Story Format](../api/csf.md), your stories are reusable with Testing Library. Each named export (i.e., a story) is renderable within your testing setup.
+[Testing Library](https://testing-library.com/) is a suite of helper libraries for browser-based interaction tests. With [Component Story Format](../api/csf.md), your stories are reusable with Testing Library. Each named export (story) is renderable within your testing setup.
 
 <div class="aside">
 
@@ -88,7 +97,7 @@ Once the test runs, it loads the story and renders it. [Testing Library](https:/
 
 ## Example with Cypress
 
-[Cypress](https://www.cypress.io/) is an end-to-end testing framework. It enables you to test a complete instance of your application by simulating user behavior. With Component Story Format, your stories are reusable with Cypress. Each named export (i.e., a story) is renderable within your testing setup.
+[Cypress](https://www.cypress.io/) is an end-to-end testing framework. It enables you to test a complete instance of your application by simulating user behavior. With Component Story Format, your stories are reusable with Cypress. Each named export (in other words, a story) is renderable within your testing setup.
 
 An example of an end-to-end test with Cypress and Storybook is testing a login component for the correct inputs. For example, if you had the following story:
 
@@ -130,7 +139,7 @@ When Cypress runs your test, it loads Storybook's isolated iframe and checks if
 
 ## Example with Playwright
 
-[Playwright](https://playwright.dev/) is a browser automation tool and end-to-end testing framework from Microsoft. It offers cross-browser automation, mobile testing with device emulation, and headless testing. With Component Story Format, your stories are reusable with Playwright. Each named export (i.e., a story) is renderable within your testing setup.
+[Playwright](https://playwright.dev/) is a browser automation tool and end-to-end testing framework from Microsoft. It offers cross-browser automation, mobile testing with device emulation, and headless testing. With Component Story Format, your stories are reusable with Playwright. Each named export (in other words, a story) is renderable within your testing setup.
 
 A real-life scenario of user flow testing with Playwright would be how to test a login form for validity. For example, if you had the following story already created:
 
@@ -171,8 +180,9 @@ Once you execute Playwright, it opens a new browser window, loads Storybook's is
 
 #### Learn about other UI tests
 
+- [Test runner](./test-runner.md) to automate test execution
 - [Visual tests](./visual-testing.md) for appearance
 - [Accessibility tests](./accessibility-testing.md) for accessibility
 - [Interaction tests](./interaction-testing.md) for user behavior simulation
 - [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
-- Import stories in other tests for other tools
+- Import stories in other tests for other tools

docs/writing-tests/interaction-testing.md

@@ -6,17 +6,51 @@ As you build more complex UIs like pages, components become responsible for more
 
 In a nutshell, you start by supplying the appropriate props for the initial state of a component. Then simulate user behavior such as clicks and form entries. Finally, check whether the UI and component state update correctly.
 
+In Storybook, this familiar workflow happens in your browser. That makes it easier to debug failures because you're running tests in the same environment as you develop components: the browser.
+
 ![Storybook interaction testing](./storybook-interaction-tests.gif)
 
-## Setup interactions addon
+## How does component testing in Storybook work?
 
-You can set up interaction testing in Storybook using the `play` function and [`@storybook/addon-interactions`](https://storybook.js.org/addons/@storybook/addon-interactions/).
+You start by writing a [**story**](../writing-stories/introduction.md) to set up the component's initial state. Then simulate user behavior using the **play** function. Finally, use the **test-runner** to confirm that the component renders correctly and that your interaction tests with the **play** function pass. Additionally, you can automate test execution via the [command line](./test-runner.md#cli-options) or in your [CI environment](./test-runner.md#set-up-ci-to-run-tests).
 
 - The [`play`](../writing-stories/play-function.md) function is a small snippet of code that runs after a story finishes rendering. You can use this to test user workflows.
+- The test is written using Storybook-instrumented versions of [Jest](https://jestjs.io/) and [Testing Library](https://testing-library.com/).
+- [`@storybook/addon-interactions`](https://storybook.js.org/addons/@storybook/addon-interactions/) visualizes the test in Storybook and provides a playback interface for convenient browser-based debugging.
+- [`@storybook/test-runner`](https://github.com/storybookjs/test-runner) is a standalone utility—powered by [Jest](https://jestjs.io/) and [Playwright](https://playwright.dev/)—that executes all of your interactions tests and catches broken stories.
 
-- [`@storybook/addon-interactions`](https://storybook.js.org/addons/@storybook/addon-interactions) includes helper utilities and a playback interface that simulates user behavior in the browser. It’s powered Testing Library and includes convenient instrumentation for debugging.
+## Set up the interactions addon
 
-Here's an example of how to set up interaction testing in Storybook with the `play` function:
+To enable interaction testing with Storybook, 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.
+
+Run the following command to install the interactions addon and related dependencies.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-addon-interactions-addon-full-install.yarn.js.mdx',
+    'common/storybook-addon-interactions-addon-full-install.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+Update your Storybook configuration (in `.storybook/main.js|ts`) to include the interactions addon and enable playback controls for debugging.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-main-enable-interactive-debugger.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Write an interaction test
+
+The test itself is defined inside a `play` function connected to a story. Here's an example of how to set up an interaction test with Storybook and the `play` function:
 
 <!-- prettier-ignore-start -->
 
@@ -49,7 +83,7 @@ Once the story loads in the UI, it simulates the user's behavior and verifies th
 
 ## API for user-events
 
-Under the hood, Storybook’s interaction addon mirrors Testing Library’s `user-events` API. If you’re familiar with [Testing Library](https://testing-library.com/) you should be at home in Storybook.
+Under the hood, Storybook’s interaction addon mirrors Testing Library’s [`user-events`](https://testing-library.com/docs/user-event/intro/) API. If you’re familiar with [Testing Library](https://testing-library.com/), you should be at home in Storybook.
 
 Below is an abridged API for user-event. For more, check out the [official user-event docs](https://testing-library.com/docs/ecosystem-user-event/).
 
@@ -65,6 +99,17 @@ Below is an abridged API for user-event. For more, check out the [official user-
 | `type`            | Writes text inside inputs, or textareas <br/>`userEvent.type(await within(canvasElement).getByRole('my-input'),'Some text');`                            |
 | `unhover`         | Unhovers out of element <br/>`userEvent.unhover(await within(canvasElement).getByLabelText(/Example/i));`                                                |
 
+### Interactive debugger
+
+If you check your interactions panel, you'll see the step-by-step flow. It also offers a handy set of UI controls to pause, resume, rewind, and step through each interaction.
+
+<video autoPlay muted playsInline loop>
+  <source
+    src="addon-interactions-playback-controls-optimized.mp4"
+    type="video/mp4"
+  />
+</video>
+
 ### Permalinks for reproductions
 
 The `play` function is executed after the story is rendered. If there’s an error, it’ll be shown in the interaction addon panel to help with debugging.
@@ -75,6 +120,33 @@ Since Storybook is a webapp, anyone with the URL can reproduce the error with th
 
 Streamline interaction testing further by automatically [publishing Storybook](../sharing/publish-storybook.md) in pull requests. That gives teams a universal reference point to test and debug stories.
 
+## Execute tests with the test-runner
+
+Storybook only runs the interaction test when you're viewing a story. Therefore, you'd have to go through each story to run all your checks. As your Storybook grows, it becomes unrealistic to review each change manually. Storybook [test-runner](https://github.com/storybookjs/test-runner) automates the process by running all tests for you. To execute the test-runner, open a new terminal window and run the following command:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-execute.yarn.js.mdx',
+    'common/storybook-test-runner-execute.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+![Interaction test with test runner](./storybook-interaction-test-runner-loginform-optimized.png)
+
+<div class="aside">
+
+💡 If you need, you can provide additional flags to the test-runner. Read the [documentation](./test-runner.md#cli-options) to learn more.
+
+</div>
+
+## Automate
+
+Once you're ready to push your code into a pull request, you'll want to automatically run all your checks using a Continuous Integration (CI) service before merging it. Read our [documentation](./test-runner.md#set-up-ci-to-run-tests) for a detailed guide on setting up a CI environment to run tests.
+
 ---
 
 #### What’s the difference between interaction tests and visual tests?
@@ -83,8 +155,9 @@ Interaction tests can be expensive to maintain when applied wholesale to every c
 
 #### Learn about other UI tests
 
+- [Test runner](./test-runner.md) to automate test execution
 - [Visual tests](./visual-testing.md) for appearance
 - [Accessibility tests](accessibility-testing.md) for accessibility
 - Interaction tests for user behavior simulation
 - [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
-- [Import stories in other tests](./importing-stories-in-tests.md) for other tools
+- [Import stories in other tests](./importing-stories-in-tests.md) for other tools

docs/writing-tests/introduction.md

@@ -10,10 +10,13 @@ That means stories are a pragmatic starting point for your UI testing strategy.
 
 The simplest testing method is manual “spot checking”. You run Storybook locally, then eyeball every story to verify its appearance and behavior. [Publish](../sharing/publish-storybook.md) your Storybook online to share reproductions and get teammates involved.
 
-Storybook also comes with tools, test runners, and handy integrations with the larger JavaScript ecosystem to expand your UI test coverage. These docs detail how you can use Storybook for UI testing.
+To test a component in isolation, you often have to mock data, dependencies, or even network requests. Check out our guide on [mocking in Storybook](../writing-stories/build-pages-with-storybook.md#mocking-connected-components) for more info.
 
+Storybook also comes with tools, [a test runner](./test-runner.md), and [handy integrations](./importing-stories-in-tests.md) with the larger JavaScript ecosystem to expand your UI test coverage. These docs detail how you can use Storybook for UI testing.
+
+- [**Test runner**](./test-runner.md) to automatically test your entire Storybook and catch broken stories.
 - [**Visual tests**](./visual-testing.md) capture a screenshot of every story then compare it against baselines to detect appearance and integration issues
 - [**Accessibility tests**](./accessibility-testing.md) catch usability issues related to visual, hearing, mobility, cognitive, speech, or neurological disabilities
 - [**Interaction tests**](./interaction-testing.md) verify component functionality by simulating user behaviour, firing events, and ensuring that state is updated as expected
 - [**Snapshot tests**](./snapshot-testing.md) detect changes in the rendered markup to surface rendering errors or warnings
-- [**Import stories in other tests**](./importing-stories-in-tests.md) to QA even more UI characteristics
+- [**Import stories in other tests**](./importing-stories-in-tests.md) to QA even more UI characteristics

docs/writing-tests/snapshot-testing.md

@@ -64,7 +64,7 @@ npm i -D @storybook/addon-storyshots-puppeteer puppeteer
 yarn add @storybook/addon-storyshots-puppeteer puppeteer
 ```
 
-Next, update your test file (e.g., `storybook.test.js`) to the following:
+Next, update your test file (for example, `storybook.test.js`) to the following:
 
 <!-- prettier-ignore-start -->
 
@@ -110,8 +110,9 @@ Visual tests capture images of stories and compare them against image baselines.
 
 #### Learn about other UI tests
 
+- [Test runner](./test-runner.md) to automate test execution
 - [Visual tests](./visual-testing.md) for appearance
 - [Accessibility tests](./accessibility-testing.md) for accessibility
 - [Interaction tests](./interaction-testing.md) for user behavior simulation
 - Snapshot tests for rendering errors and warnings
-- [Import stories in other tests](./importing-stories-in-tests.md) for other tools
+- [Import stories in other tests](./importing-stories-in-tests.md) for other tools

docs/writing-tests/test-runner.md

@@ -0,0 +1,305 @@
+---
+title: 'Test runner'
+---
+
+Storybook test runner turns all of your stories into executable tests. It is powered by [Jest](https://jestjs.io/) and [Playwright](https://playwright.dev/).
+
+- For those [without a play function](../writing-stories/introduction.md): it verifies whether the story renders without any errors.
+- For those [with a play function](../writing-stories/play-function.md): it also checks for errors in the play function and that all assertions passed.
+
+These tests run in a live browser and can be executed via the [command line](#cli-options) or your [CI server](#set-up-ci-to-run-tests).
+
+## Setup
+
+The test-runner is a standalone, framework-agnostic utility that runs parallel to your Storybook. You will need to take some additional steps to set it up properly. Detailed below is our recommendation to configure and execute it.
+
+Run the following command to install it and the required dependencies.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-install.yarn.js.mdx',
+    'common/storybook-test-runner-install.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+Update your `package.json` scripts and enable the test runner.
+
+```json
+{
+  "scripts": {
+    "test-storybook": "test-storybook"
+  }
+}
+```
+
+Start your Storybook with:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'angular/storybook-run-dev.with-builder.js.mdx',
+    'common/storybook-run-dev.npm.js.mdx',
+    'common/storybook-run-dev.yarn.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+💡 Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests.
+</div>
+
+Finally, open a new terminal window and run the test-runner with:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-execute.yarn.js.mdx',
+    'common/storybook-test-runner-execute.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Configure
+
+Test runner offers zero-config support for Storybook. However, you can run `test-storybook --eject` for more fine-grained control. It generates a `test-runner-jest.config.js` file at the root of your project, which you can modify. Additionally, you can extend the generated configuration file and provide [testEnvironmentOptions](https://github.com/playwright-community/jest-playwright#configuration) as the test runner also uses [jest-playwright](https://github.com/playwright-community/jest-playwright) under the hood.
+
+### CLI Options
+
+The test-runner is powered by [Jest](https://jestjs.io/) and accepts a subset of its [CLI options](https://jestjs.io/docs/cli) (for example, `--watch`, `--maxWorkers`).
+If you're already using any of those flags in your project, you should be able to migrate them into Storybook's test-runner without any issues. Listed below are all the available flags and examples of using them.
+
+| Options                         | Description                                                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `--help`                        | Output usage information <br/>`test-storybook --help`                                                                            |
+| `-s`, `--stories-json`          | Run in stories json mode. Automatically detected (requires a compatible Storybook) <br/>`test-storybook --stories-json`          |
+| `--no-stories-json`             | Disables stories json mode <br/>`test-storybook --no-stories-json`                                                               |
+| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from <br/>`test-storybook -c .storybook`                                        |
+| `--watch`                       | Run in watch mode <br/>`test-storybook --watch`                                                                                  |
+| `--url`                         | Define the URL to run tests in. Useful for custom Storybook URLs <br/>`test-storybook --url http://the-storybook-url-here.com`   |
+| `--browsers`                    | Define browsers to run tests in. One or multiple of: chromium, firefox, webkit <br/>`test-storybook --browsers firefox chromium` |
+| `--maxWorkers [amount]`         | Specifies the maximum number of workers the worker-pool will spawn for running tests <br/>`test-storybook --maxWorkers=2`        |
+| `--no-cache`                    | Disable the cache <br/>`test-storybook --no-cache`                                                                               |
+| `--clearCache`                  | Deletes the Jest cache directory and then exits without running tests <br/>`test-storybook --clearCache`                         |
+| `--verbose`                     | Display individual test results with the test suite hierarchy <br/>`test-storybook --verbose`                                    |
+| `-u`, `--updateSnapshot`        | Use this flag to re-record every snapshot that fails during this test run <br/>`test-storybook -u`                               |
+| `--eject`                       | Creates a local configuration file to override defaults of the test-runner <br/>`test-storybook --eject`                         |
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-execute-with-flags.yarn.js.mdx',
+    'common/storybook-test-runner-execute-with-flags.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+### Run tests against a deployed Storybook
+
+By default, the test-runner assumes that you're running it against a locally served Storybook on port `6006`. If you want to define a target URL to run against deployed Storybooks, you can use the `--url` flag or set the `TARGET_URL` environment variable. For example:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-execute-with-url.yarn.js.mdx',
+    'common/storybook-test-runner-execute-with-url.npm.js.mdx',
+    'common/storybook-test-runner-execute-with-url.env-var.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Set up CI to run tests
+
+You can also configure the test-runner to run tests on a CI environment. Documented below are some recipes to help you get started.
+
+### Run against deployed Storybooks via Github Actions deployment
+
+If you're publishing your Storybook with services such as [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/), they emit a `deployment_status` event in GitHub Actions. You can use it and set the `deployment_status.target_url` as the `TARGET_URL` environment variable. Here's how:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-with-deploy-event-workflow.yml.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 The published Storybook must be publicly available for this example to work. We recommend running the test server using the recipe [below](#run-against-non-deployed-storybooks) if it requires authentication.
+
+</div>
+
+### Run against non-deployed Storybooks
+
+You can use your CI provider (for example, [GitHub Actions](https://github.com/features/actions), [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/), [CircleCI](https://circleci.com/)) to build and run the test runner against your built Storybook. Here's a recipe that relies on third-party libraries, that is to say, [concurrently](https://www.npmjs.com/package/concurrently), [http-server](https://www.npmjs.com/package/http-server), and [wait-on](https://www.npmjs.com/package/wait-on) to build Storybook and run tests with the test-runner.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-local-build-workflow.yml.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 By default Storybook outputs the [build](../sharing/publish-storybook.md#build-storybook-as-a-static-web-application) to the `storybook-static` directory. If you're using a different build directory, you'll need to adjust the recipe accordingly.
+
+</div>
+
+### What's the difference between Chromatic and Test runner?
+
+The test-runner is a generic testing tool that can run locally or on CI and be configured or extended to run all kinds of tests.
+
+[Chromatic](https://www.chromatic.com/) is a cloud-based service that runs [visual](./visual-testing.md) and [interaction tests](./interaction-testing.md) (and soon accessibility tests) without setting up the test runner. It also syncs with your git provider and manages access control for private projects.
+
+However, you might want to pair the test runner and Chromatic in some cases.
+
+- Use it locally and Chromatic on your CI.
+- Use Chromatic for visual and interaction tests and run other custom tests using the test runner.
+
+## Advanced configuration
+
+### Test hook API (experimental)
+
+The test-runner renders a story and executes its [play function](writing-stories/play-function.md) if one exists. However, certain behaviors are impossible to achieve via the play function, which executes in the browser. For example, if you want the test-runner to take visual snapshots for you, this is possible via Playwright/Jest but must be executed in Node.
+
+The test-runner exports test hooks that can be overridden globally to enable use cases like visual or DOM snapshots. These hooks give you access to the test lifecycle _before_ and _after_ the story is rendered.
+Listed below are the available hooks and an overview of how to use them.
+
+| Hook         | Description                                                                   |
+| ------------ | ----------------------------------------------------------------------------- |
+| `setup`      | Executes once before all the tests run<br/>`setup() {}`                       |
+| `preRender`  | Executes before a story is rendered<br/>`async preRender(page, context) {}`   |
+| `postRender` | Executes after the story is rendered<br/>`async postRender(page, context) {}` |
+
+<div class="aside">
+
+💡 These test hooks are experimental and may be subject to breaking changes. We encourage you to test as much as possible within the story's [play function](../writing-stories/play-function.md).
+
+</div>
+
+To enable the hooks API, you'll need to add a new configuration file inside your Storybook directory and set them up as follows:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-hooks-example.js.mdx',
+    'common/storybook-test-runner-hooks-example.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 Except for the `setup` function, all other functions run asynchronously. Both `preRender` and `postRender` functions include two additional arguments, a [Playwright page](https://playwright.dev/docs/pages) and a context object which contains the `id`, `title`, and the `name` of the story.
+
+</div>
+
+When the test-runner executes, your existing tests will go through the following lifecycle:
+
+- The `setup` function is executed before all the tests run.
+- The context object is generated containing the required information.
+- Playwright navigates to the story's page.
+- The `preRender` function is executed.
+- The story is rendered, and any existing `play` functions are executed.
+- The `postRender` function is executed.
+
+### Stories.json mode
+
+The test-runner transforms your story files into tests when testing a local Storybook. For a remote Storybook, it uses the Storybook's [stories.json](../configure/overview.md#feature-flags) file (a static index of all the stories) to run the tests.
+
+#### Why?
+
+Suppose you run into a situation where the local and remote Storybooks appear out of sync, or you might not even have access to the code. In that case, the `stories.json` file is guaranteed to be the most accurate representation of the deployed Storybook you are testing. To test a local Storybook using this feature, use the `--stories-json` flag as follows:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-with-stories-json.yarn.js.mdx',
+    'common/storybook-test-runner-with-stories-json.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+
+💡 The `stories.json` mode is not compatible with watch mode.
+
+</div>
+
+If you need to disable it, use the `--no-stories-json` flag:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-test-runner-disable-stories-json.yarn.js.mdx',
+    'common/storybook-test-runner-disable-stories-json.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+#### How do I check if my Storybook has a `stories.json` file?
+
+Stories.json mode requires a `stories.json` file. Open a browser window and navigate to your deployed Storybook instance (for example, `https://your-storybook-url-here.com/stories.json`). You should see a JSON file that starts with a `"v": 3` key, immediately followed by another key called "stories", which contains a map of story IDs to JSON objects. If that is the case, your Storybook supports [stories.json mode](../configure/overview.md#feature-flags).
+
+---
+
+## Troubleshooting
+
+### The test runner seems flaky and keeps timing out
+
+If your tests time out with the following message:
+
+```shell
+Timeout - Async callback was not invoked within the 15000 ms timeout specified by jest.setTimeout
+```
+
+It might be that Playwright couldn't handle testing the number of stories you have in your project. Perhaps you have a large number of stories, or your CI environment has a really low RAM configuration. In such cases, you should limit the number of workers that run in parallel by adjusting your command as follows:
+
+```json
+{
+  "scripts": {
+    "test-storybook:ci": "yarn test-storybook --maxWorkers=2"
+  }
+}
+```
+
+### The error output in the CLI is too short
+
+By default, the test runner truncates error outputs at 1000 characters, and you can check the full output directly in Storybook in the browser. However, if you want to change that limit, you can do so by setting the `DEBUG_PRINT_LIMIT` environment variable to a number of your choosing, for example, `DEBUG_PRINT_LIMIT=5000 yarn test-storybook`.
+
+### Run the test runner in other CI environments
+
+As the test runner is based on Playwright, you might need to use specific docker images or other configurations depending on your CI setup. In that case, you can refer to the [Playwright CI docs](https://playwright.dev/docs/ci) for more information.
+
+#### Learn about other UI tests
+
+- Test runner to automate test execution
+- [Visual tests](./visual-testing.md) for appearance
+- [Accessibility tests](./accessibility-testing.md) for accessibility
+- [Interaction tests](./interaction-testing.md) for user behavior simulation
+- [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
+- [Import stories in other tests](./importing-stories-in-tests.md) for other tools

docs/writing-tests/visual-testing.md

@@ -50,7 +50,7 @@ View it online at https://www.chromatic.com/build?appId=...&number=1.
 💡 Before running Chromatic's CLI ensure you have at least two commits added to the repository to prevent build failures, as Chromatic relies on a full Git history graph to establish the baselines. Read more about baselines in Chromatic's <a href="https://www.chromatic.com/docs/branching-and-baselines"> documentation</a>
 </div>
 
-When Chromatic finishes, it should have successfully deployed your Storybook and established the baselines (i.e., starting point) for all your component's stories. Additionally, providing you with a link to the published Storybook that you can share with your team to gather feedback.
+When Chromatic finishes, it should have successfully deployed your Storybook and established the baselines, that is to say, the starting point for all your component's stories. Additionally, providing you with a link to the published Storybook that you can share with your team to gather feedback.
 
 ![Chromatic project first build](./chromatic-first-build-optimized.png)
 
@@ -74,8 +74,9 @@ Snapshot tests compare the rendered markup of every story against known baseline
 
 #### Learn about other UI tests
 
+- [Test runner](./test-runner.md) to automate test execution
 - Visual tests for appearance
 - [Accessibility tests](./accessibility-testing.md) for accessibility
 - [Interaction tests](./interaction-testing.md) for user behavior simulation
 - [Snapshot tests](./snapshot-testing.md) for rendering errors and warnings
-- [Import stories in other tests](./importing-stories-in-tests.md) for other tools
+- [Import stories in other tests](./importing-stories-in-tests.md) for other tools