From f9b724c2983a36477390c410f2efea4e02cfa475 Mon Sep 17 00:00:00 2001
From: jonniebigodes <joaocontadesenvolvimento@gmail.com>
Date: Tue, 31 Oct 2023 23:41:33 +0000
Subject: [PATCH 1/4] Docs: Test runner minor fixes

---
 .../snippets/common/test-runner-a11y-config.js.mdx |  2 +-
 .../snippets/common/test-runner-a11y-config.ts.mdx |  5 ++---
 .../common/test-runner-a11y-configure.js.mdx       |  2 +-
 .../common/test-runner-a11y-configure.ts.mdx       |  7 +++----
 .../common/test-runner-a11y-disable.js.mdx         |  5 ++---
 .../common/test-runner-a11y-disable.ts.mdx         |  7 +++----
 .../common/test-runner-helper-function.js.mdx      |  5 ++++-
 .../common/test-runner-helper-function.ts.mdx      |  6 ++++--
 docs/writing-tests/accessibility-testing.md        |  8 ++++----
 docs/writing-tests/test-runner.md                  | 14 +++++++-------
 10 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/docs/snippets/common/test-runner-a11y-config.js.mdx b/docs/snippets/common/test-runner-a11y-config.js.mdx
index d7afb9b77456..bf5f2b954fb3 100644
--- a/docs/snippets/common/test-runner-a11y-config.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-config.js.mdx
@@ -4,7 +4,7 @@
 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 = {
diff --git a/docs/snippets/common/test-runner-a11y-config.ts.mdx b/docs/snippets/common/test-runner-a11y-config.ts.mdx
index 9339eb7e2ae0..a317cb46ad18 100644
--- a/docs/snippets/common/test-runner-a11y-config.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-config.ts.mdx
@@ -1,12 +1,11 @@
 ```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 = {
diff --git a/docs/snippets/common/test-runner-a11y-configure.js.mdx b/docs/snippets/common/test-runner-a11y-configure.js.mdx
index e7ddb352d5ea..23333177d9a3 100644
--- a/docs/snippets/common/test-runner-a11y-configure.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-configure.js.mdx
@@ -6,7 +6,7 @@ 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 = {
diff --git a/docs/snippets/common/test-runner-a11y-configure.ts.mdx b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
index 8b1f4d31037e..8828a71bba0d 100644
--- a/docs/snippets/common/test-runner-a11y-configure.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
@@ -1,14 +1,13 @@
 ```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 = {
diff --git a/docs/snippets/common/test-runner-a11y-disable.js.mdx b/docs/snippets/common/test-runner-a11y-disable.js.mdx
index edb12dab0bfa..02a13b3efca9 100644
--- a/docs/snippets/common/test-runner-a11y-disable.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-disable.js.mdx
@@ -1,12 +1,11 @@
 ```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 = {
diff --git a/docs/snippets/common/test-runner-a11y-disable.ts.mdx b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
index 3297e8ea0b7b..986b8c09eaff 100644
--- a/docs/snippets/common/test-runner-a11y-disable.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
@@ -1,14 +1,13 @@
 ```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 = {
diff --git a/docs/snippets/common/test-runner-helper-function.js.mdx b/docs/snippets/common/test-runner-helper-function.js.mdx
index 6ce0e1bf4123..739f0034b59e 100644
--- a/docs/snippets/common/test-runner-helper-function.js.mdx
+++ b/docs/snippets/common/test-runner-helper-function.js.mdx
@@ -1,7 +1,7 @@
 ```js
 // .storybook/test-runner.js
 
-const { getStoryContext } = require('@storybook/test-runner');
+const { getStoryContext, waitForPageReady } = require('@storybook/test-runner');
 
 module.exports = {
   // Hook that is executed before the test runner starts running tests
@@ -23,6 +23,9 @@ module.exports = {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
+    // This utility function is designed for image snapshot testing. It will wait for the page to be fully loaded, including all the async items (e.g., images, fonts, etc.).
+    await waitForPageReady(page);
+
     // Add your configuration here.
   },
 };
diff --git a/docs/snippets/common/test-runner-helper-function.ts.mdx b/docs/snippets/common/test-runner-helper-function.ts.mdx
index 94a9824a68a0..eea475d13f24 100644
--- a/docs/snippets/common/test-runner-helper-function.ts.mdx
+++ b/docs/snippets/common/test-runner-helper-function.ts.mdx
@@ -2,8 +2,7 @@
 // .storybook/test-runner.ts
 
 import type { TestRunnerConfig } from '@storybook/test-runner';
-
-import { getStoryContext } from '@storybook/test-runner';
+import { getStoryContext, waitForPageReady } from '@storybook/test-runner';
 
 const config: TestRunnerConfig = {
   // Hook that is executed before the test runner starts running tests
@@ -25,6 +24,9 @@ const config: TestRunnerConfig = {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
+    // This utility function is designed for image snapshot testing. It will wait for the page to be fully loaded, including all the async items (e.g., images, fonts, etc.).
+    await waitForPageReady(page);
+
     // Add your configuration here.
   },
 };
diff --git a/docs/writing-tests/accessibility-testing.md b/docs/writing-tests/accessibility-testing.md
index d6dbba00d27a..4773ec8594b0 100644
--- a/docs/writing-tests/accessibility-testing.md
+++ b/docs/writing-tests/accessibility-testing.md
@@ -89,7 +89,7 @@ Out of the box, Storybook's accessibility addon includes a set of accessibility
 
 #### Global a11y configuration
 
-If you need to dismiss an accessibility rule or modify its settings across all stories, you can add the following to your [storybook/preview.js](../configure/overview.md#configure-story-rendering):
+If you need to dismiss an accessibility rule or modify its settings across all stories, you can add the following to your [`storybook/preview.js|ts`](../configure/overview.md#configure-story-rendering):
 
 <!-- prettier-ignore-start -->
 
@@ -170,7 +170,7 @@ Disable accessibility testing for stories or components by adding the following
 
 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.
 
-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).
+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) and [axe-playwright](https://github.com/abhinaba-ghosh/axe-playwright).
 
 ### Setup
 
@@ -190,7 +190,7 @@ Run the following command to install the required dependencies.
 
 <!-- prettier-ignore-end -->
 
-Add a new [configuration file](./test-runner.md#test-hook-api-experimental) inside your Storybook directory with the following inside:
+Add a new [configuration file](./test-runner.md#test-hook-api) inside your Storybook directory with the following inside:
 
 <!-- prettier-ignore-start -->
 
@@ -205,7 +205,7 @@ Add a new [configuration file](./test-runner.md#test-hook-api-experimental) insi
 
 <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).
+💡 `preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api).
 
 </div>
 
diff --git a/docs/writing-tests/test-runner.md b/docs/writing-tests/test-runner.md
index e75bee68c549..ebecf03198d3 100644
--- a/docs/writing-tests/test-runner.md
+++ b/docs/writing-tests/test-runner.md
@@ -190,19 +190,19 @@ However, you might want to pair the test runner and Chromatic in some cases.
 
 ## Advanced configuration
 
-### Test hook API (experimental)
+### Test hook API
 
 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                                                                                        |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| `prepare`    | Prepares the browser for tests<br/>`async prepare({ page, browserContext, testRunnerConfig }) {}`  |
-| `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) {}`                      |
+| Hook         | Description                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------------------- |
+| `prepare`    | Prepares the browser for tests<br/>`async prepare({ page, browserContext, testRunnerConfig }) {}` |
+| `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">
 

From 8efaead946b95339681ddb6af9278f1635bc8e72 Mon Sep 17 00:00:00 2001
From: jonniebigodes <joaocontadesenvolvimento@gmail.com>
Date: Fri, 17 Nov 2023 10:48:14 +0000
Subject: [PATCH 2/4] Minor polish and added filtering tests

---
 .../my-component-exclude-tags.story.js.mdx    |  14 ++
 .../my-component-exclude-tags.story.ts.mdx    |  20 ++
 .../my-component-include-tags.story.js.mdx    |  14 ++
 .../my-component-include-tags.story.ts.mdx    |  20 ++
 .../my-component-skip-tags.story.js.mdx       |  14 ++
 .../my-component-skip-tags.story.ts.mdx       |  20 ++
 .../common/test-runner-a11y-config.ts.mdx     |   2 +-
 .../common/test-runner-a11y-configure.ts.mdx  |   2 +-
 .../common/test-runner-a11y-disable.ts.mdx    |   2 +-
 docs/snippets/common/test-runner-auth.js.mdx  |  12 +
 docs/snippets/common/test-runner-auth.ts.mdx  |  16 ++
 .../test-runner-custom-page-viewport.js.mdx   |  32 +++
 .../test-runner-custom-page-viewport.ts.mdx   |  36 +++
 .../common/test-runner-helper-function.ts.mdx |   2 +-
 .../common/test-runner-hooks-example.ts.mdx   |   2 +-
 .../common/test-runner-tags-config.js.mdx     |  11 +
 .../common/test-runner-tags-config.ts.mdx     |  15 ++
 .../test-runner-tags-exclude.config.js.mdx    |   9 +
 .../test-runner-tags-exclude.config.ts.mdx    |  13 +
 .../test-runner-tags-include.config.js.mdx    |   9 +
 .../test-runner-tags-include.config.ts.mdx    |  13 +
 .../test-runner-tags-skip.config.js.mdx       |   9 +
 .../test-runner-tags-skip.config.ts.mdx       |  13 +
 .../common/test-runner-waitpageready.js.mdx   |  25 ++
 .../common/test-runner-waitpageready.ts.mdx   |  29 +++
 docs/writing-tests/accessibility-testing.md   |   6 +-
 docs/writing-tests/test-runner.md             | 222 ++++++++++++++----
 27 files changed, 529 insertions(+), 53 deletions(-)
 create mode 100644 docs/snippets/common/my-component-exclude-tags.story.js.mdx
 create mode 100644 docs/snippets/common/my-component-exclude-tags.story.ts.mdx
 create mode 100644 docs/snippets/common/my-component-include-tags.story.js.mdx
 create mode 100644 docs/snippets/common/my-component-include-tags.story.ts.mdx
 create mode 100644 docs/snippets/common/my-component-skip-tags.story.js.mdx
 create mode 100644 docs/snippets/common/my-component-skip-tags.story.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-auth.js.mdx
 create mode 100644 docs/snippets/common/test-runner-auth.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-custom-page-viewport.js.mdx
 create mode 100644 docs/snippets/common/test-runner-custom-page-viewport.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-config.js.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-config.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-exclude.config.js.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-exclude.config.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-include.config.js.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-include.config.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-skip.config.js.mdx
 create mode 100644 docs/snippets/common/test-runner-tags-skip.config.ts.mdx
 create mode 100644 docs/snippets/common/test-runner-waitpageready.js.mdx
 create mode 100644 docs/snippets/common/test-runner-waitpageready.ts.mdx

diff --git a/docs/snippets/common/my-component-exclude-tags.story.js.mdx b/docs/snippets/common/my-component-exclude-tags.story.js.mdx
new file mode 100644
index 000000000000..e0b35b71986c
--- /dev/null
+++ b/docs/snippets/common/my-component-exclude-tags.story.js.mdx
@@ -0,0 +1,14 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['no-tests'], // 👈 Excludes all stories from being tested with the test-runner
+};
+
+export const ExcludeStory = {
+  tags: ['no-tests'], // 👈 Configures the story to be excluded from testing via the `no-tests` tag
+};
+```
diff --git a/docs/snippets/common/my-component-exclude-tags.story.ts.mdx b/docs/snippets/common/my-component-exclude-tags.story.ts.mdx
new file mode 100644
index 000000000000..6fee748fadc3
--- /dev/null
+++ b/docs/snippets/common/my-component-exclude-tags.story.ts.mdx
@@ -0,0 +1,20 @@
+```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'], // 👈 Excludes all stories from being tested with the test-runner
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const ExcludeStory: Story = {
+  tags: ['no-tests'], // 👈 Configures the story to be excluded from testing via the `no-tests` tag
+};
+```
diff --git a/docs/snippets/common/my-component-include-tags.story.js.mdx b/docs/snippets/common/my-component-include-tags.story.js.mdx
new file mode 100644
index 000000000000..995f5285b1cc
--- /dev/null
+++ b/docs/snippets/common/my-component-include-tags.story.js.mdx
@@ -0,0 +1,14 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['test-only'], // 👈 Runs tests only for stories with this tag
+};
+
+export const IncludeStory = {
+  tags: ['test-only'], // 👈 Configures the story to be added to the test suite with the test-runner
+};
+```
diff --git a/docs/snippets/common/my-component-include-tags.story.ts.mdx b/docs/snippets/common/my-component-include-tags.story.ts.mdx
new file mode 100644
index 000000000000..5e47651618b6
--- /dev/null
+++ b/docs/snippets/common/my-component-include-tags.story.ts.mdx
@@ -0,0 +1,20 @@
+```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'], // 👈 Runs tests only for stories with this tag
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const IncludeStory: Story = {
+  tags: ['test-only'], // 👈 Configures the story to be added to the test suite with the test-runner
+};
+```
diff --git a/docs/snippets/common/my-component-skip-tags.story.js.mdx b/docs/snippets/common/my-component-skip-tags.story.js.mdx
new file mode 100644
index 000000000000..bf3737cb2ef6
--- /dev/null
+++ b/docs/snippets/common/my-component-skip-tags.story.js.mdx
@@ -0,0 +1,14 @@
+```js
+// MyComponent.stories.js|jsx
+
+import { MyComponent } from './MyComponent';
+
+export default {
+  component: MyComponent,
+  tags: ['skip-test'], // 👈 Skips running tests on this story
+};
+
+export const SkipStory = {
+  tags: ['skip-test'], // 👈 Configures the story to be skipped when running tests with the test-runner
+};
+```
diff --git a/docs/snippets/common/my-component-skip-tags.story.ts.mdx b/docs/snippets/common/my-component-skip-tags.story.ts.mdx
new file mode 100644
index 000000000000..62c0d1dfbabf
--- /dev/null
+++ b/docs/snippets/common/my-component-skip-tags.story.ts.mdx
@@ -0,0 +1,20 @@
+```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'], // 👈 Skips running tests on this story
+};
+
+export default meta;
+type Story = StoryObj<typeof MyComponent>;
+
+export const SkipStory: Story = {
+  tags: ['skip-test'], // 👈 Configures the story to be skipped when running tests with the test-runner
+};
+```
diff --git a/docs/snippets/common/test-runner-a11y-config.ts.mdx b/docs/snippets/common/test-runner-a11y-config.ts.mdx
index a317cb46ad18..c007a62c1244 100644
--- a/docs/snippets/common/test-runner-a11y-config.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-config.ts.mdx
@@ -22,5 +22,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-module.exports = a11yConfig;
+export default a11yConfig;
 ```
diff --git a/docs/snippets/common/test-runner-a11y-configure.ts.mdx b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
index 8828a71bba0d..5a9adea12c86 100644
--- a/docs/snippets/common/test-runner-a11y-configure.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
@@ -32,5 +32,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-module.exports = a11yConfig;
+export default a11yConfig;
 ```
diff --git a/docs/snippets/common/test-runner-a11y-disable.ts.mdx b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
index 986b8c09eaff..97d8cd06f0fa 100644
--- a/docs/snippets/common/test-runner-a11y-disable.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
@@ -31,5 +31,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-module.exports = a11yConfig;
+export default a11yConfig;
 ```
diff --git a/docs/snippets/common/test-runner-auth.js.mdx b/docs/snippets/common/test-runner-auth.js.mdx
new file mode 100644
index 000000000000..d4858de23165
--- /dev/null
+++ b/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}`,
+    };
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-auth.ts.mdx b/docs/snippets/common/test-runner-auth.ts.mdx
new file mode 100644
index 000000000000..c4fd82d8726e
--- /dev/null
+++ b/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;
+```
diff --git a/docs/snippets/common/test-runner-custom-page-viewport.js.mdx b/docs/snippets/common/test-runner-custom-page-viewport.js.mdx
new file mode 100644
index 000000000000..a4d5d0cc57f1
--- /dev/null
+++ b/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 preRender(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);
+    }
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx b/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx
new file mode 100644
index 000000000000..351b9e8bd0ec
--- /dev/null
+++ b/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 preRender(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;
+```
diff --git a/docs/snippets/common/test-runner-helper-function.ts.mdx b/docs/snippets/common/test-runner-helper-function.ts.mdx
index eea475d13f24..57a04bd7c465 100644
--- a/docs/snippets/common/test-runner-helper-function.ts.mdx
+++ b/docs/snippets/common/test-runner-helper-function.ts.mdx
@@ -31,5 +31,5 @@ const config: TestRunnerConfig = {
   },
 };
 
-module.exports = config;
+export default config;
 ```
diff --git a/docs/snippets/common/test-runner-hooks-example.ts.mdx b/docs/snippets/common/test-runner-hooks-example.ts.mdx
index d05ddb64801c..86398c9aeb45 100644
--- a/docs/snippets/common/test-runner-hooks-example.ts.mdx
+++ b/docs/snippets/common/test-runner-hooks-example.ts.mdx
@@ -24,5 +24,5 @@ const config: TestRunnerConfig = {
   },
 };
 
-module.exports = config;
+export default config;
 ```
diff --git a/docs/snippets/common/test-runner-tags-config.js.mdx b/docs/snippets/common/test-runner-tags-config.js.mdx
new file mode 100644
index 000000000000..6ebfbb6c9fb4
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-config.js.mdx
@@ -0,0 +1,11 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  tags: {
+    include: ['test-only', 'pages'],
+    exclude: ['no-tests', 'tokens'],
+    skip: ['skip-test', 'layout'],
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-tags-config.ts.mdx b/docs/snippets/common/test-runner-tags-config.ts.mdx
new file mode 100644
index 000000000000..023b13e77cc9
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-config.ts.mdx
@@ -0,0 +1,15 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  tags: {
+    include: ['test-only', 'pages'],
+    exclude: ['no-tests', 'tokens'],
+    skip: ['skip-test', 'layout'],
+  },
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/test-runner-tags-exclude.config.js.mdx b/docs/snippets/common/test-runner-tags-exclude.config.js.mdx
new file mode 100644
index 000000000000..5b73bb9bdf60
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-exclude.config.js.mdx
@@ -0,0 +1,9 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  tags: {
+    exclude: ['no-tests'],
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-tags-exclude.config.ts.mdx b/docs/snippets/common/test-runner-tags-exclude.config.ts.mdx
new file mode 100644
index 000000000000..9712292fe33c
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-exclude.config.ts.mdx
@@ -0,0 +1,13 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  tags: {
+    exclude: ['no-tests'],
+  },
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/test-runner-tags-include.config.js.mdx b/docs/snippets/common/test-runner-tags-include.config.js.mdx
new file mode 100644
index 000000000000..2b51222fed40
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-include.config.js.mdx
@@ -0,0 +1,9 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  tags: {
+    include: ['test-only'],
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-tags-include.config.ts.mdx b/docs/snippets/common/test-runner-tags-include.config.ts.mdx
new file mode 100644
index 000000000000..b69e402aff92
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-include.config.ts.mdx
@@ -0,0 +1,13 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  tags: {
+    include: ['test-only'],
+  },
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/test-runner-tags-skip.config.js.mdx b/docs/snippets/common/test-runner-tags-skip.config.js.mdx
new file mode 100644
index 000000000000..bc82ef46d752
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-skip.config.js.mdx
@@ -0,0 +1,9 @@
+```js
+// .storybook/test-runner.js
+
+module.exports = {
+  tags: {
+    skip: ['skip-test'],
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-tags-skip.config.ts.mdx b/docs/snippets/common/test-runner-tags-skip.config.ts.mdx
new file mode 100644
index 000000000000..37a03bf7b1c4
--- /dev/null
+++ b/docs/snippets/common/test-runner-tags-skip.config.ts.mdx
@@ -0,0 +1,13 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
+  tags: {
+    skip: ['skip-test'],
+  },
+};
+
+export default config;
+```
diff --git a/docs/snippets/common/test-runner-waitpageready.js.mdx b/docs/snippets/common/test-runner-waitpageready.js.mdx
new file mode 100644
index 000000000000..0dfb8aecb22a
--- /dev/null
+++ b/docs/snippets/common/test-runner-waitpageready.js.mdx
@@ -0,0 +1,25 @@
+```js
+// .storybook/test-runner.js
+
+const { waitForPageReady } = require('@storybook/test-runner');
+const { toMatchImageSnapshot } = require('jest-image-snapshot');
+
+const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
+
+module.exports = {
+  setup() {
+    expect.extend({ toMatchImageSnapshot });
+  },
+  async postRender(page, context) {
+    // Awaits for the page to be loaded and available including assets (e.g., fonts)
+    await waitForPageReady(page);
+
+    // Generates a snapshot file based on the story identifier
+    const image = await page.screenshot();
+    expect(image).toMatchImageSnapshot({
+      customSnapshotsDir,
+      customSnapshotIdentifier: context.id,
+    });
+  },
+};
+```
diff --git a/docs/snippets/common/test-runner-waitpageready.ts.mdx b/docs/snippets/common/test-runner-waitpageready.ts.mdx
new file mode 100644
index 000000000000..7a3c1ae88d8e
--- /dev/null
+++ b/docs/snippets/common/test-runner-waitpageready.ts.mdx
@@ -0,0 +1,29 @@
+```ts
+// .storybook/test-runner.ts
+
+import type { TestRunnerConfig } from '@storybook/test-runner';
+import { waitForPageReady } from '@storybook/test-runner';
+
+import { toMatchImageSnapshot } from 'jest-image-snapshot';
+
+const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
+
+const config: TestRunnerConfig = {
+  setup() {
+    expect.extend({ toMatchImageSnapshot });
+  },
+  async postRender(page, context) {
+    // Awaits for the page to be loaded and available including assets (e.g., fonts)
+    await waitForPageReady(page);
+
+    // Generates a snapshot file based on the story identifier
+    const image = await page.screenshot();
+    expect(image).toMatchImageSnapshot({
+      customSnapshotsDir,
+      customSnapshotIdentifier: context.id,
+    });
+  },
+};
+
+export default config;
+```
diff --git a/docs/writing-tests/accessibility-testing.md b/docs/writing-tests/accessibility-testing.md
index 4773ec8594b0..cbc39f9cdf1c 100644
--- a/docs/writing-tests/accessibility-testing.md
+++ b/docs/writing-tests/accessibility-testing.md
@@ -203,11 +203,11 @@ Add a new [configuration file](./test-runner.md#test-hook-api) inside your Story
 
 <!-- prettier-ignore-end -->
 
-<div class="aside">
+<Callout variant="info" icon="💡">
 
-💡 `preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api).
+`preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api).
 
-</div>
+</Callout>
 
 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.
 
diff --git a/docs/writing-tests/test-runner.md b/docs/writing-tests/test-runner.md
index ebecf03198d3..fc34bbd9caea 100644
--- a/docs/writing-tests/test-runner.md
+++ b/docs/writing-tests/test-runner.md
@@ -52,9 +52,11 @@ Start your Storybook with:
 
 <!-- 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>
+<Callout variant="info" icon="💡">
+
+Storybook's test runner requires either a locally running Storybook instance or a published Storybook to run all the existing tests.
+
+</Callout>
 
 Finally, open a new terminal window and run the test-runner with:
 
@@ -79,30 +81,33 @@ Test runner offers zero-config support for Storybook. However, you can run `test
 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`, `--index-json`            | Run in index json mode. Automatically detected (requires a compatible Storybook) <br/>`test-storybook --index-json`                                                           |
-| `--no-index-json`               | Disables index json mode <br/>`test-storybook --no-index-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`                                                                                                                               |
-| `--watchAll`                    | Watch files for changes and rerun all tests when something changes.<br/>`test-storybook --watchAll`                                                                           |
-| `--coverage`                    | Runs [coverage tests](./test-coverage.md) on your stories and components <br/> `test-storybook --coverage`                                                                    |
-| `--coverageDirectory`           | Directory where to write coverage report output <br/>`test-storybook --coverage --coverageDirectory coverage/ui/storybook`                                                    |
-| `--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`                                                                      |
-| `--json`                        | Prints the test results in JSON. This mode will send all other test output and user messages to stderr. <br/>`test-storybook --json`                                          |
-| `--outputFile`                  | Write test results to a file when the --json option is also specified. <br/>`test-storybook --json --outputFile results.json`                                                 |
-| `--junit`                       | Indicates that test information should be reported in a junit file. <br/>`test-storybook --**junit**`                                                                         |
-| `--ci`                          | Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest to be run with `--updateSnapshot`. <br/>`test-storybook --ci` |
-| `--shard [index/count]`         | Requires CI. Splits the test suite execution into multiple machines <br/> `test-storybook --shard=1/8`                                                                        |
-| `--failOnConsole`               | Makes tests fail on browser console errors<br/>`test-storybook --failOnConsole`                                                                                               |
+| Options                         | Description                                                                                                                                                                                             |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--help`                        | Output usage information <br/>`test-storybook --help`                                                                                                                                                   |
+| `-s`, `--index-json`            | Run in index json mode. Automatically detected (requires a compatible Storybook) <br/>`test-storybook --index-json`                                                                                     |
+| `--no-index-json`               | Disables index json mode <br/>`test-storybook --no-index-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`                                                                                                                                                         |
+| `--watchAll`                    | Watch files for changes and rerun all tests when something changes.<br/>`test-storybook --watchAll`                                                                                                     |
+| `--coverage`                    | Runs [coverage tests](./test-coverage.md) on your stories and components <br/> `test-storybook --coverage`                                                                                              |
+| `--coverageDirectory`           | Directory where to write coverage report output <br/>`test-storybook --coverage --coverageDirectory coverage/ui/storybook`                                                                              |
+| `--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`                                                                                                |
+| `--json`                        | Prints the test results in JSON. This mode will send all other test output and user messages to stderr. <br/>`test-storybook --json`                                                                    |
+| `--outputFile`                  | Write test results to a file when the --json option is also specified. <br/>`test-storybook --json --outputFile results.json`                                                                           |
+| `--junit`                       | Indicates that test information should be reported in a junit file. <br/>`test-storybook --**junit**`                                                                                                   |
+| `--ci`                          | Instead of the regular behavior of storing a new snapshot automatically, it will fail the test and require Jest to be run with `--updateSnapshot`. <br/>`test-storybook --ci`                           |
+| `--shard [index/count]`         | Requires CI. Splits the test suite execution into multiple machines <br/> `test-storybook --shard=1/8`                                                                                                  |
+| `--failOnConsole`               | Makes tests fail on browser console errors<br/>`test-storybook --failOnConsole`                                                                                                                         |
+| `--includeTags`                 | Experimental feature <br/>Defines a subset of stories to be tested if they match the enabled [tags](#experimental-filter-tests). <br/>`test-storybook --includeTags="test-only, pages"`                 |
+| `--excludeTags`                 | Experimental feature <br/>Prevents stories from being tested if they match the provided [tags](#experimental-filter-tests). <br/>`test-storybook --skipTags="no-tests, tokens"`                         |
+| `--skipTags`                    | Experimental feature <br/>Configures the test runner to skip running tests for stories that match the provided [tags](#experimental-filter-tests). <br/>`test-storybook --skipTags="skip-test, layout"` |
 
 <!-- prettier-ignore-start -->
 
@@ -151,11 +156,11 @@ If you're publishing your Storybook with services such as [Vercel](https://verce
 
 <!-- prettier-ignore-end -->
 
-<div class="aside">
+<Callout variant="info" icon="💡">
 
-💡 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.
+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>
+</Callout>
 
 ### Run against non-deployed Storybooks
 
@@ -171,11 +176,11 @@ You can use your CI provider (for example, [GitHub Actions](https://github.com/f
 
 <!-- prettier-ignore-end -->
 
-<div class="aside">
+<Callout variant="info" icon="💡">
 
-💡 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.
+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>
+</Callout>
 
 ### What's the difference between Chromatic and Test runner?
 
@@ -204,12 +209,6 @@ Listed below are the available hooks and an overview of how to use them.
 | `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 -->
@@ -223,11 +222,11 @@ To enable the hooks API, you'll need to add a new configuration file inside your
 
 <!-- prettier-ignore-end -->
 
-<div class="aside">
+<Callout variant="info" icon="💡">
 
-💡 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.
+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>
+</Callout>
 
 When the test-runner executes, your existing tests will go through the following lifecycle:
 
@@ -238,6 +237,105 @@ When the test-runner executes, your existing tests will go through the following
 - The story is rendered, and any existing `play` functions are executed.
 - The `postRender` function is executed.
 
+### (Experimental) Filter tests
+
+When you run the test-runner on Storybook, it tests every story by default. However, if you want to filter the tests, you can use the `tags` configuration option. Storybook originally introduced this feature to generate [automatic documentation](../writing-docs/autodocs.md) for stories. But it can be further extended to configure the test-runner to run tests according to the provided tags using a similar configuration option or via CLI flags (e.g., `--includeTags`, `--excludeTags`, `--skipTags`). Listed below are the available options and an overview of how to use them.
+
+| Option    | Description                                                                   |
+| --------- | ----------------------------------------------------------------------------- |
+| `exclude` | Prevents stories if they match the provided tags from being tested.           |
+| `include` | Defines a subset of stories only to be tested if they match the enabled tags. |
+| `skip`    | Skips testing on stories if they match the provided tags.                     |
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/test-runner-tags-config.js.mdx',
+    'common/test-runner-tags-config.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<Callout variant="info" icon="ℹ️">
+
+Running tests with the CLI flags takes precedence over the options provided in the configuration file and will override the available options in the configuration file.
+
+</Callout>
+
+#### Disabling tests
+
+If you want to prevent specific stories from being tested by the test-runner, you can configure your story with a custom tag, enable it to the test-runner configuration file or run the test-runner with the `--excludeTags` [CLI](#cli-options) flag and exclude them from testing. This is helpful when you want to exclude stories that are not yet ready for testing or are irrelevant to your tests. For example:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/my-component-exclude-tags.story.js.mdx',
+    'common/my-component-exclude-tags.story.ts.mdx',
+    'common/test-runner-tags-exclude.config.js.mdx',
+    'common/test-runner-tags-exclude.config.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+#### Run tests for a subset of stories
+
+To allow the test-runner only to run tests on a specific story or subset of stories, you can configure the story with a custom tag, enable it in the test-runner configuration file or run the test-runner with the `--includeTags` [CLI](#cli-options) flag and include them in your tests. For example, if you wanted to run tests based on the `test-only` tag, you can adjust your configuration as follows:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/my-component-include-tags.story.js.mdx',
+    'common/my-component-include-tags.story.ts.mdx',
+    'common/test-runner-tags-include.config.js.mdx',
+    'common/test-runner-tags-include.config.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<Callout variant="info" icon="ℹ️">
+
+Applying tags for the component's stories should either be done at the component level (using `meta`) or at the story level. Importing tags across stories is not supported in Storybook and won't work as intended.
+
+</Callout>
+
+#### Skip tests
+
+If you want to skip running tests on a particular story or subset of stories, you can configure your story with a custom tag, enable it in the test-runner configuration file, or run the test-runner with the `--skipTags` [CLI](#cli-options) flag. Running tests with this option will cause the test-runner to skip over the story and flag them accordingly in the test results. For example:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/my-component-skip-tags.story.js.mdx',
+    'common/my-component-skip-tags.story.ts.mdx',
+    'common/test-runner-tags-skip.config.js.mdx',
+    'common/test-runner-tags-skip.config.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+### Authentication for deployed Storybooks
+
+If you use a secure hosting provider that requires authentication to host your Storybook, you may need to set HTTP headers. This is mainly because of how the test runner checks the status of the instance and the index of its stories through fetch requests and Playwright. To do this, you can modify the test-runner configuration file to include the `getHttpHeaders` function. This function takes the URL of the fetch calls and page visits as input and returns an object containing the headers that need to be set.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/test-runner-auth.js.mdx',
+    'common/test-runner-auth.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
 ### Helpers
 
 The test-runner exports a few helpers that can be used to make your tests more readable and maintainable by accessing Storybook's internals (e.g., `args`, `parameters`). Listed below are the available helpers and an overview of how to use them.
@@ -253,6 +351,36 @@ The test-runner exports a few helpers that can be used to make your tests more r
 
 <!-- prettier-ignore-end -->
 
+#### Accessing story information with the test-runner
+
+If you need to access information about the story, such as its parameters, the test-runner includes a helper function named `getStoryContext` that you can use to retrieve it. You can then use it to customize your tests further as needed. For example, if you need to configure Playwright's page [viewport size](https://playwright.dev/docs/api/class-page#page-set-viewport-size) to use the viewport size defined in the story's parameters, you can do so as follows:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/test-runner-custom-page-viewport.js.mdx',
+    'common/test-runner-custom-page-viewport.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+#### Working with assets
+
+If you're running a specific set of tests (e.g., image snapshot testing), the test-runner provides a helper function named `waitForPageReady` that you can use to ensure the page is fully loaded and ready before running the test. For example:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/test-runner-waitpageready.js.mdx',
+    'common/test-runner-waitpageready.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
 ### Index.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 [index.json](../configure/overview.md#feature-flags) (formerly `stories.json`) file (a static index of all the stories) to run the tests.
@@ -273,11 +401,11 @@ Suppose you run into a situation where the local and remote Storybooks appear ou
 
 <!-- prettier-ignore-end -->
 
-<div class="aside">
+<Callout variant="info" icon="💡">
 
-💡 The `index.json` mode is not compatible with watch mode.
+The `index.json` mode is not compatible with the watch mode.
 
-</div>
+</Callout>
 
 If you need to disable it, use the `--no-index-json` flag:
 
@@ -327,6 +455,10 @@ By default, the test runner truncates error outputs at 1000 characters, and you
 
 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.
 
+### Tests filtered by tags are incorrectly executed
+
+If you've enabled filtering tests with tags and provided similar tags to the `include` and `exclude` lists, the test-runner will execute the tests based on the `exclude` list and ignore the `include` list. To avoid this, make sure the tags provided to the `include` and `exclude` lists differ.
+
 #### Learn about other UI tests
 
 - Test runner to automate test execution

From 42ce9647f1b1cb8e9bc0fbc17b2126f2013828e3 Mon Sep 17 00:00:00 2001
From: jonniebigodes <joaocontadesenvolvimento@gmail.com>
Date: Fri, 17 Nov 2023 22:07:44 +0000
Subject: [PATCH 3/4] Hooks updates

---
 .../my-component-exclude-tags.story.js.mdx    |  5 +++--
 .../my-component-exclude-tags.story.ts.mdx    |  5 +++--
 .../my-component-include-tags.story.js.mdx    |  5 +++--
 .../my-component-include-tags.story.ts.mdx    |  5 +++--
 .../my-component-skip-tags.story.js.mdx       |  5 +++--
 .../my-component-skip-tags.story.ts.mdx       |  5 +++--
 .../common/test-runner-a11y-config.js.mdx     |  4 ++--
 .../common/test-runner-a11y-config.ts.mdx     |  8 ++++----
 .../common/test-runner-a11y-configure.js.mdx  |  4 ++--
 .../common/test-runner-a11y-configure.ts.mdx  |  8 ++++----
 .../common/test-runner-a11y-disable.js.mdx    |  4 ++--
 .../common/test-runner-a11y-disable.ts.mdx    |  8 ++++----
 .../test-runner-custom-page-viewport.js.mdx   |  2 +-
 .../test-runner-custom-page-viewport.ts.mdx   |  2 +-
 .../common/test-runner-helper-function.js.mdx |  8 ++++----
 .../common/test-runner-helper-function.ts.mdx |  8 ++++----
 .../common/test-runner-hooks-example.js.mdx   |  8 ++++----
 .../common/test-runner-hooks-example.ts.mdx   |  8 ++++----
 .../common/test-runner-waitpageready.js.mdx   |  2 +-
 .../common/test-runner-waitpageready.ts.mdx   |  2 +-
 docs/writing-tests/accessibility-testing.md   |  2 +-
 docs/writing-tests/test-runner.md             | 20 +++++++++----------
 22 files changed, 67 insertions(+), 61 deletions(-)

diff --git a/docs/snippets/common/my-component-exclude-tags.story.js.mdx b/docs/snippets/common/my-component-exclude-tags.story.js.mdx
index e0b35b71986c..32eebb42518d 100644
--- a/docs/snippets/common/my-component-exclude-tags.story.js.mdx
+++ b/docs/snippets/common/my-component-exclude-tags.story.js.mdx
@@ -5,10 +5,11 @@ import { MyComponent } from './MyComponent';
 
 export default {
   component: MyComponent,
-  tags: ['no-tests'], // 👈 Excludes all stories from being tested with the test-runner
+  tags: ['no-tests'], // 👈 Provides the `no-tests` tag to all stories in this file
 };
 
 export const ExcludeStory = {
-  tags: ['no-tests'], // 👈 Configures the story to be excluded from testing via the `no-tests` tag
+  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
+  tags: ['no-tests'],
 };
 ```
diff --git a/docs/snippets/common/my-component-exclude-tags.story.ts.mdx b/docs/snippets/common/my-component-exclude-tags.story.ts.mdx
index 6fee748fadc3..79a62510ad3b 100644
--- a/docs/snippets/common/my-component-exclude-tags.story.ts.mdx
+++ b/docs/snippets/common/my-component-exclude-tags.story.ts.mdx
@@ -8,13 +8,14 @@ import { MyComponent } from './MyComponent';
 
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
-  tags: ['no-tests'], // 👈 Excludes all stories from being tested with the test-runner
+  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 = {
-  tags: ['no-tests'], // 👈 Configures the story to be excluded from testing via the `no-tests` tag
+  //👇 Adds the `no-tests` tag to this story to exclude it from the tests when enabled in the test-runner configuration
+  tags: ['no-tests'],
 };
 ```
diff --git a/docs/snippets/common/my-component-include-tags.story.js.mdx b/docs/snippets/common/my-component-include-tags.story.js.mdx
index 995f5285b1cc..1e667e43c716 100644
--- a/docs/snippets/common/my-component-include-tags.story.js.mdx
+++ b/docs/snippets/common/my-component-include-tags.story.js.mdx
@@ -5,10 +5,11 @@ import { MyComponent } from './MyComponent';
 
 export default {
   component: MyComponent,
-  tags: ['test-only'], // 👈 Runs tests only for stories with this tag
+  tags: ['test-only'], // 👈 Provides the `test-only` tag to all stories in this file
 };
 
 export const IncludeStory = {
-  tags: ['test-only'], // 👈 Configures the story to be added to the test suite with the test-runner
+  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
+  tags: ['test-only'],
 };
 ```
diff --git a/docs/snippets/common/my-component-include-tags.story.ts.mdx b/docs/snippets/common/my-component-include-tags.story.ts.mdx
index 5e47651618b6..6b3f71446d8f 100644
--- a/docs/snippets/common/my-component-include-tags.story.ts.mdx
+++ b/docs/snippets/common/my-component-include-tags.story.ts.mdx
@@ -8,13 +8,14 @@ import { MyComponent } from './MyComponent';
 
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
-  tags: ['test-only'], // 👈 Runs tests only for stories with this tag
+  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 = {
-  tags: ['test-only'], // 👈 Configures the story to be added to the test suite with the test-runner
+  //👇 Adds the `test-only` tag to this story to be included in the tests when enabled in the test-runner configuration
+  tags: ['test-only'],
 };
 ```
diff --git a/docs/snippets/common/my-component-skip-tags.story.js.mdx b/docs/snippets/common/my-component-skip-tags.story.js.mdx
index bf3737cb2ef6..c59991aace99 100644
--- a/docs/snippets/common/my-component-skip-tags.story.js.mdx
+++ b/docs/snippets/common/my-component-skip-tags.story.js.mdx
@@ -5,10 +5,11 @@ import { MyComponent } from './MyComponent';
 
 export default {
   component: MyComponent,
-  tags: ['skip-test'], // 👈 Skips running tests on this story
+  tags: ['skip-test'], // 👈 Provides the `skip-test` tag to all stories in this file
 };
 
 export const SkipStory = {
-  tags: ['skip-test'], // 👈 Configures the story to be skipped when running tests with the test-runner
+  //👇 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'],
 };
 ```
diff --git a/docs/snippets/common/my-component-skip-tags.story.ts.mdx b/docs/snippets/common/my-component-skip-tags.story.ts.mdx
index 62c0d1dfbabf..3513e3d33c43 100644
--- a/docs/snippets/common/my-component-skip-tags.story.ts.mdx
+++ b/docs/snippets/common/my-component-skip-tags.story.ts.mdx
@@ -8,13 +8,14 @@ import { MyComponent } from './MyComponent';
 
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
-  tags: ['skip-test'], // 👈 Skips running tests on this story
+  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 = {
-  tags: ['skip-test'], // 👈 Configures the story to be skipped when running tests with the test-runner
+  //👇 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'],
 };
 ```
diff --git a/docs/snippets/common/test-runner-a11y-config.js.mdx b/docs/snippets/common/test-runner-a11y-config.js.mdx
index bf5f2b954fb3..9ce64c1e3f09 100644
--- a/docs/snippets/common/test-runner-a11y-config.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-config.js.mdx
@@ -8,10 +8,10 @@ const { injectAxe, checkA11y } = require('axe-playwright');
  * 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: {
diff --git a/docs/snippets/common/test-runner-a11y-config.ts.mdx b/docs/snippets/common/test-runner-a11y-config.ts.mdx
index c007a62c1244..4bc91082506f 100644
--- a/docs/snippets/common/test-runner-a11y-config.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-config.ts.mdx
@@ -8,11 +8,11 @@ import { injectAxe, checkA11y } from 'axe-playwright';
  * 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: {
@@ -22,5 +22,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-export default a11yConfig;
+export default config;
 ```
diff --git a/docs/snippets/common/test-runner-a11y-configure.js.mdx b/docs/snippets/common/test-runner-a11y-configure.js.mdx
index 23333177d9a3..abd0a20b4089 100644
--- a/docs/snippets/common/test-runner-a11y-configure.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-configure.js.mdx
@@ -10,10 +10,10 @@ const { getStoryContext } = require('@storybook/test-runner');
  * 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);
 
diff --git a/docs/snippets/common/test-runner-a11y-configure.ts.mdx b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
index 5a9adea12c86..5af07ea7d760 100644
--- a/docs/snippets/common/test-runner-a11y-configure.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-configure.ts.mdx
@@ -10,11 +10,11 @@ import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
  * 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 +32,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-export default a11yConfig;
+export default config;
 ```
diff --git a/docs/snippets/common/test-runner-a11y-disable.js.mdx b/docs/snippets/common/test-runner-a11y-disable.js.mdx
index 02a13b3efca9..d6177c9ce38f 100644
--- a/docs/snippets/common/test-runner-a11y-disable.js.mdx
+++ b/docs/snippets/common/test-runner-a11y-disable.js.mdx
@@ -9,10 +9,10 @@ const { injectAxe, checkA11y } = require('axe-playwright');
  * 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);
 
diff --git a/docs/snippets/common/test-runner-a11y-disable.ts.mdx b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
index 97d8cd06f0fa..1be273fee210 100644
--- a/docs/snippets/common/test-runner-a11y-disable.ts.mdx
+++ b/docs/snippets/common/test-runner-a11y-disable.ts.mdx
@@ -10,11 +10,11 @@ import { injectAxe, checkA11y } from 'axe-playwright';
  * 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);
 
@@ -31,5 +31,5 @@ const a11yConfig: TestRunnerConfig = {
   },
 };
 
-export default a11yConfig;
+export default config;
 ```
diff --git a/docs/snippets/common/test-runner-custom-page-viewport.js.mdx b/docs/snippets/common/test-runner-custom-page-viewport.js.mdx
index a4d5d0cc57f1..b334755d1f74 100644
--- a/docs/snippets/common/test-runner-custom-page-viewport.js.mdx
+++ b/docs/snippets/common/test-runner-custom-page-viewport.js.mdx
@@ -7,7 +7,7 @@ const { MINIMAL_VIEWPORTS } = require('@storybook/addon-viewport');
 const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
 
 module.exports = {
-  async preRender(page, story) {
+  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;
diff --git a/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx b/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx
index 351b9e8bd0ec..5db491a51335 100644
--- a/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx
+++ b/docs/snippets/common/test-runner-custom-page-viewport.ts.mdx
@@ -9,7 +9,7 @@ const { MINIMAL_VIEWPORTS } = require('@storybook/addon-viewport');
 const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
 
 const config: TestRunnerConfig = {
-  async preRender(page, story) {
+  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;
diff --git a/docs/snippets/common/test-runner-helper-function.js.mdx b/docs/snippets/common/test-runner-helper-function.js.mdx
index 739f0034b59e..9e7827f029ab 100644
--- a/docs/snippets/common/test-runner-helper-function.js.mdx
+++ b/docs/snippets/common/test-runner-helper-function.js.mdx
@@ -8,18 +8,18 @@ module.exports = {
   setup() {
     // Add your configuration here.
   },
-  /* Hook to execute before a story is rendered.
+  /* Hook to execute before a story is initially visited before being rendered in the browser.
    * 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) {
+  async preVisit(page, context) {
     // Add your configuration here.
   },
-  /* Hook to execute after a story is rendered.
+  /* Hook to execute after a story is visited and fully 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) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
diff --git a/docs/snippets/common/test-runner-helper-function.ts.mdx b/docs/snippets/common/test-runner-helper-function.ts.mdx
index 57a04bd7c465..af40e58b2dee 100644
--- a/docs/snippets/common/test-runner-helper-function.ts.mdx
+++ b/docs/snippets/common/test-runner-helper-function.ts.mdx
@@ -9,18 +9,18 @@ const config: TestRunnerConfig = {
   setup() {
     // Add your configuration here.
   },
-  /* Hook to execute before a story is rendered.
+  /* Hook to execute before a story is initially visited before being rendered in the browser.
    * 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) {
+  async preVisit(page, context) {
     // Add your configuration here.
   },
-  /* Hook to execute after a story is rendered.
+  /* Hook to execute after a story is visited and fully 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) {
+  async postVisit(page, context) {
     // Get the entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
 
diff --git a/docs/snippets/common/test-runner-hooks-example.js.mdx b/docs/snippets/common/test-runner-hooks-example.js.mdx
index e3d52b738645..18876266bf31 100644
--- a/docs/snippets/common/test-runner-hooks-example.js.mdx
+++ b/docs/snippets/common/test-runner-hooks-example.js.mdx
@@ -6,18 +6,18 @@ module.exports = {
   setup() {
     // Add your configuration here.
   },
-  /* Hook to execute before a story is rendered.
+  /* Hook to execute before a story is initially visited before being rendered in the browser.
    * 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) {
+  async preVisit(page, context) {
     // Add your configuration here.
   },
-  /* Hook to execute after a story is rendered.
+  /* Hook to execute after a story is visited and fully 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) {
+  async postVisit(page, context) {
     // Add your configuration here.
   },
 };
diff --git a/docs/snippets/common/test-runner-hooks-example.ts.mdx b/docs/snippets/common/test-runner-hooks-example.ts.mdx
index 86398c9aeb45..f06d4c71b063 100644
--- a/docs/snippets/common/test-runner-hooks-example.ts.mdx
+++ b/docs/snippets/common/test-runner-hooks-example.ts.mdx
@@ -8,18 +8,18 @@ const config: TestRunnerConfig = {
   setup() {
     // Add your configuration here.
   },
-  /* Hook to execute before a story is rendered.
+  /* Hook to execute before a story is initially visited before being rendered in the browser.
    * 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) {
+  async preVisit(page, context) {
     // Add your configuration here.
   },
-  /* Hook to execute after a story is rendered.
+  /* Hook to execute after a story is visited and fully 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) {
+  async postVisit(page, context) {
     // Add your configuration here.
   },
 };
diff --git a/docs/snippets/common/test-runner-waitpageready.js.mdx b/docs/snippets/common/test-runner-waitpageready.js.mdx
index 0dfb8aecb22a..1bb3df563c00 100644
--- a/docs/snippets/common/test-runner-waitpageready.js.mdx
+++ b/docs/snippets/common/test-runner-waitpageready.js.mdx
@@ -10,7 +10,7 @@ module.exports = {
   setup() {
     expect.extend({ toMatchImageSnapshot });
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Awaits for the page to be loaded and available including assets (e.g., fonts)
     await waitForPageReady(page);
 
diff --git a/docs/snippets/common/test-runner-waitpageready.ts.mdx b/docs/snippets/common/test-runner-waitpageready.ts.mdx
index 7a3c1ae88d8e..2da14b2c7185 100644
--- a/docs/snippets/common/test-runner-waitpageready.ts.mdx
+++ b/docs/snippets/common/test-runner-waitpageready.ts.mdx
@@ -12,7 +12,7 @@ const config: TestRunnerConfig = {
   setup() {
     expect.extend({ toMatchImageSnapshot });
   },
-  async postRender(page, context) {
+  async postVisit(page, context) {
     // Awaits for the page to be loaded and available including assets (e.g., fonts)
     await waitForPageReady(page);
 
diff --git a/docs/writing-tests/accessibility-testing.md b/docs/writing-tests/accessibility-testing.md
index cbc39f9cdf1c..36c17f89860c 100644
--- a/docs/writing-tests/accessibility-testing.md
+++ b/docs/writing-tests/accessibility-testing.md
@@ -205,7 +205,7 @@ Add a new [configuration file](./test-runner.md#test-hook-api) inside your Story
 
 <Callout variant="info" icon="💡">
 
-`preRender` and `postRender` are convenient hooks that allow you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api).
+`preVisit` and `postVisit` are convenient hooks that allow you to extend the test runner's default configuration. Read more about them [here](./test-runner.md#test-hook-api).
 
 </Callout>
 
diff --git a/docs/writing-tests/test-runner.md b/docs/writing-tests/test-runner.md
index fc34bbd9caea..90eef2dcaa89 100644
--- a/docs/writing-tests/test-runner.md
+++ b/docs/writing-tests/test-runner.md
@@ -202,12 +202,12 @@ The test-runner renders a story and executes its [play function](../writing-stor
 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                                                                                       |
-| ------------ | ------------------------------------------------------------------------------------------------- |
-| `prepare`    | Prepares the browser for tests<br/>`async prepare({ page, browserContext, testRunnerConfig }) {}` |
-| `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) {}`                     |
+| Hook        | Description                                                                                                     |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `prepare`   | Prepares the browser for tests<br/>`async prepare({ page, browserContext, testRunnerConfig }) {}`               |
+| `setup`     | Executes once before all the tests run<br/>`setup() {}`                                                         |
+| `preVisit`  | Executes before a story is initially visited and rendered in the browser<br/>`async preVisit(page, context) {}` |
+| `postVisit` | Executes after the story is is visited and fully rendered<br/>`async postVisit(page, context) {}`               |
 
 To enable the hooks API, you'll need to add a new configuration file inside your Storybook directory and set them up as follows:
 
@@ -224,7 +224,7 @@ To enable the hooks API, you'll need to add a new configuration file inside your
 
 <Callout variant="info" icon="💡">
 
-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.
+Except for the `setup` function, all other functions run asynchronously. Both `preVisit` and `postVisit` 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.
 
 </Callout>
 
@@ -233,9 +233,9 @@ When the test-runner executes, your existing tests will go through the following
 - 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 `preVisit` function is executed.
 - The story is rendered, and any existing `play` functions are executed.
-- The `postRender` function is executed.
+- The `postVisit` function is executed.
 
 ### (Experimental) Filter tests
 
@@ -306,7 +306,7 @@ Applying tags for the component's stories should either be done at the component
 
 #### Skip tests
 
-If you want to skip running tests on a particular story or subset of stories, you can configure your story with a custom tag, enable it in the test-runner configuration file, or run the test-runner with the `--skipTags` [CLI](#cli-options) flag. Running tests with this option will cause the test-runner to skip over the story and flag them accordingly in the test results. For example:
+If you want to skip running tests on a particular story or subset of stories, you can configure your story with a custom tag, enable it in the test-runner configuration file, or run the test-runner with the `--skipTags` [CLI](#cli-options) flag. Running tests with this option will cause the test-runner to ignore and flag them accordingly in the test results, indicating that the tests are temporarily disabled. For example:
 
 <!-- prettier-ignore-start -->
 

From e2c41a8b834d8ed189d962f9b12179ddf5e5ea76 Mon Sep 17 00:00:00 2001
From: jonniebigodes <joaocontadesenvolvimento@gmail.com>
Date: Sat, 18 Nov 2023 21:01:46 +0000
Subject: [PATCH 4/4] tag fix and minor polish to the intro

---
 docs/writing-tests/test-runner.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/writing-tests/test-runner.md b/docs/writing-tests/test-runner.md
index 90eef2dcaa89..fc4daeb130f1 100644
--- a/docs/writing-tests/test-runner.md
+++ b/docs/writing-tests/test-runner.md
@@ -106,7 +106,7 @@ If you're already using any of those flags in your project, you should be able t
 | `--shard [index/count]`         | Requires CI. Splits the test suite execution into multiple machines <br/> `test-storybook --shard=1/8`                                                                                                  |
 | `--failOnConsole`               | Makes tests fail on browser console errors<br/>`test-storybook --failOnConsole`                                                                                                                         |
 | `--includeTags`                 | Experimental feature <br/>Defines a subset of stories to be tested if they match the enabled [tags](#experimental-filter-tests). <br/>`test-storybook --includeTags="test-only, pages"`                 |
-| `--excludeTags`                 | Experimental feature <br/>Prevents stories from being tested if they match the provided [tags](#experimental-filter-tests). <br/>`test-storybook --skipTags="no-tests, tokens"`                         |
+| `--excludeTags`                 | Experimental feature <br/>Prevents stories from being tested if they match the provided [tags](#experimental-filter-tests). <br/>`test-storybook --excludeTags="no-tests, tokens"`                      |
 | `--skipTags`                    | Experimental feature <br/>Configures the test runner to skip running tests for stories that match the provided [tags](#experimental-filter-tests). <br/>`test-storybook --skipTags="skip-test, layout"` |
 
 <!-- prettier-ignore-start -->
@@ -239,7 +239,7 @@ When the test-runner executes, your existing tests will go through the following
 
 ### (Experimental) Filter tests
 
-When you run the test-runner on Storybook, it tests every story by default. However, if you want to filter the tests, you can use the `tags` configuration option. Storybook originally introduced this feature to generate [automatic documentation](../writing-docs/autodocs.md) for stories. But it can be further extended to configure the test-runner to run tests according to the provided tags using a similar configuration option or via CLI flags (e.g., `--includeTags`, `--excludeTags`, `--skipTags`). Listed below are the available options and an overview of how to use them.
+When you run the test-runner on Storybook, it tests every story by default. However, if you want to filter the tests, you can use the `tags` configuration option. Storybook originally introduced this feature to generate [automatic documentation](../writing-docs/autodocs.md) for stories. But it can be further extended to configure the test-runner to run tests according to the provided tags using a similar configuration option or via CLI flags (e.g., `--includeTags`, `--excludeTags`, `--skipTags`), only available with the latest stable release (`0.15` or higher). Listed below are the available options and an overview of how to use them.
 
 | Option    | Description                                                                   |
 | --------- | ----------------------------------------------------------------------------- |