Merge pull request storybookjs#24645 from storybookjs/docs_test_runne…

…r_updates

Docs: Test runner minor fixes

docs/snippets/common/my-component-exclude-tags.story.js.mdx

@@ -0,0 +1,15 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['no-tests'], // 👈 Provides the `no-tests` tag to all stories in this file
+};
+
+export const ExcludeStory = {
+  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
+  tags: ['no-tests'],
+};
+```

docs/snippets/common/my-component-exclude-tags.story.ts.mdx

@@ -0,0 +1,21 @@
+```ts
+// MyComponent.stories.ts|tsx
+
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+  tags: ['no-tests'], // 👈 Provides the `no-tests` tag to all stories in this file
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const ExcludeStory: Story = {
+  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
+  tags: ['no-tests'],
+};
+```

docs/snippets/common/my-component-include-tags.story.js.mdx

@@ -0,0 +1,15 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['test-only'], // 👈 Provides the `test-only` tag to all stories in this file
+};
+
+export const IncludeStory = {
+  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
+  tags: ['test-only'],
+};
+```

docs/snippets/common/my-component-include-tags.story.ts.mdx

@@ -0,0 +1,21 @@
+```ts
+// MyComponent.stories.ts|tsx
+
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+  tags: ['test-only'], // 👈 Provides the `test-only` tag to all stories in this file
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const IncludeStory: Story = {
+  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
+  tags: ['test-only'],
+};
+```

docs/snippets/common/my-component-skip-tags.story.js.mdx

@@ -0,0 +1,15 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['skip-test'], // 👈 Provides the `skip-test` tag to all stories in this file
+};
+
+export const SkipStory = {
+  //👇 Adds the `skip-test` tag to this story to allow it to be skipped in the tests when enabled in the test-runner configuration
+  tags: ['skip-test'],
+};
+```

docs/snippets/common/my-component-skip-tags.story.ts.mdx

@@ -0,0 +1,21 @@
+```ts
+// MyComponent.stories.ts|tsx
+
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { MyComponent } from './MyComponent';
+
+const meta: Meta<typeof MyComponent> = {
+  component: MyComponent,
+  tags: ['skip-test'], // 👈 Provides the `skip-test` tag to all stories in this file
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const SkipStory: Story = {
+  //👇 Adds the `skip-test` tag to this story to allow it to be skipped in the tests when enabled in the test-runner configuration
+  tags: ['skip-test'],
+};
+```

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

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

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

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

docs/snippets/common/test-runner-a11y-configure.js.mdx

@@ -6,14 +6,14 @@ const { injectAxe, checkA11y, configureAxe } = require('axe-playwright');
 const { getStoryContext } = require('@storybook/test-runner');
 
 /*
- * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+ * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api
  * to learn more about the test-runner hooks API.
  */
 module.exports = {
-  async preRender(page) {
+  async preVisit(page) {
     await injectAxe(page);
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 

docs/snippets/common/test-runner-a11y-configure.ts.mdx

@@ -1,21 +1,20 @@
 ```ts
 // .storybook/test-runner.ts
 
-import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
-
+import type { TestRunnerConfig } from '@storybook/test-runner';
 import { getStoryContext } from '@storybook/test-runner';
 
-import type { TestRunnerConfig } from '@storybook/test-runner';
+import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
 
 /*
- * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+ * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api
  * to learn more about the test-runner hooks API.
  */
-const a11yConfig: TestRunnerConfig = {
-  async preRender(page) {
+const config: TestRunnerConfig = {
+  async preVisit(page) {
     await injectAxe(page);
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
@@ -33,5 +32,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-module.exports = a11yConfig;
+export default config;
 ```

docs/snippets/common/test-runner-a11y-disable.js.mdx

@@ -1,19 +1,18 @@
 ```js
 // .storybook/test-runner.js
 
-const { injectAxe, checkA11y } = require('axe-playwright');
-
 const { getStoryContext } = require('@storybook/test-runner');
 
+const { injectAxe, checkA11y } = require('axe-playwright');
 /*
- * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+ * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api
  * to learn more about the test-runner hooks API.
  */
 module.exports = {
-  async preRender(page) {
+  async preVisit(page) {
     await injectAxe(page);
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 

docs/snippets/common/test-runner-a11y-disable.ts.mdx

@@ -1,21 +1,20 @@
 ```ts
 // .storybook/test-runner.ts
 
-import { injectAxe, checkA11y } from 'axe-playwright';
-
+import type { TestRunnerConfig } from '@storybook/test-runner';
 import { getStoryContext } from '@storybook/test-runner';
 
-import type { TestRunnerConfig } from '@storybook/test-runner';
+import { injectAxe, checkA11y } from 'axe-playwright';
 
 /*
- * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api-experimental
+ * See https://storybook.js.org/docs/react/writing-tests/test-runner#test-hook-api
  * to learn more about the test-runner hooks API.
  */
-const a11yConfig: TestRunnerConfig = {
-  async preRender(page) {
+const config: TestRunnerConfig = {
+  async preVisit(page) {
     await injectAxe(page);
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
@@ -32,5 +31,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-module.exports = a11yConfig;
+export default config;
 ```

docs/snippets/common/test-runner-auth.js.mdx

@@ -0,0 +1,12 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  getHttpHeaders: async (url) => {
+    const token = url.includes('prod') ? 'XYZ' : 'ABC';
+    return {
+      Authorization: `Bearer ${token}`,
+    };
+  },
+};
+```

docs/snippets/common/test-runner-auth.ts.mdx

@@ -0,0 +1,16 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  getHttpHeaders: async (url) => {
+    const token = url.includes('prod') ? 'prod-token' : 'dev-token';
+    return {
+      Authorization: `Bearer ${token}`,
+    };
+  },
+};
+
+export default config;
+```

docs/snippets/common/test-runner-custom-page-viewport.js.mdx

@@ -0,0 +1,32 @@
+```js
+// .storybook/test-runner.js
+
+const { getStoryContext } = require('@storybook/test-runner');
+const { MINIMAL_VIEWPORTS } = require('@storybook/addon-viewport');
+
+const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
+
+module.exports = {
+  async preVisit(page, story) {
+    // Accesses the story's parameters and retrieves the viewport used to render it
+    const context = await getStoryContext(page, story);
+    const viewportName = context.parameters?.viewport?.defaultViewport;
+    const viewportParameter = MINIMAL_VIEWPORTS[viewportName];
+
+    if (viewportParameter) {
+      const viewportSize = Object.entries(viewportParameter.styles).reduce(
+        (acc, [screen, size]) => ({
+          ...acc,
+          // Converts the viewport size from percentages to numbers
+          [screen]: parseInt(size),
+        }),
+        {}
+      );
+      // Configures the Playwright page to use the viewport size
+      page.setViewportSize(viewportSize);
+    } else {
+      page.setViewportSize(DEFAULT_VIEWPORT_SIZE);
+    }
+  },
+};
+```

docs/snippets/common/test-runner-custom-page-viewport.ts.mdx

@@ -0,0 +1,36 @@
+```ts
+// .storybook/test-runner.js
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+import { getStoryContext } from '@storybook/test-runner';
+
+const { MINIMAL_VIEWPORTS } = require('@storybook/addon-viewport');
+
+const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
+
+const config: TestRunnerConfig = {
+  async preVisit(page, story) {
+    // Accesses the story's parameters and retrieves the viewport used to render it
+    const context = await getStoryContext(page, story);
+    const viewportName = context.parameters?.viewport?.defaultViewport;
+    const viewportParameter = MINIMAL_VIEWPORTS[viewportName];
+
+    if (viewportParameter) {
+      const viewportSize = Object.entries(viewportParameter.styles).reduce(
+        (acc, [screen, size]) => ({
+          ...acc,
+          // Converts the viewport size from percentages to numbers
+          [screen]: parseInt(size),
+        }),
+        {}
+      );
+      // Configures the Playwright page to use the viewport size
+      page.setViewportSize(viewportSize);
+    } else {
+      page.setViewportSize(DEFAULT_VIEWPORT_SIZE);
+    }
+  },
+};
+
+export default config;
+```