update documentation to use Typescript

Author: yannbf

MIGRATION.test-runner.md

@@ -9,7 +9,7 @@
   - [Storyshots x Test Runner Comparison table](#storyshots-x-test-runner-comparison-table)
   - [Migration Steps](#migration-steps)
     - [Replacing `@storybook/addon-storyshots` with `@storybook/test-runner`:](#replacing-storybookaddon-storyshots-with-storybooktest-runner)
-    - [Migrating storyshots features](#migrating-storyshots-features)
+    - [Migrating Storyshots features](#migrating-storyshots-features)
       - [Smoke testing](#smoke-testing)
       - [Accessibility testing](#accessibility-testing)
       - [Image snapshot testing](#image-snapshot-testing)
@@ -135,7 +135,7 @@ import { getJestConfig } from '@storybook/test-runner';
 const defaultConfig = getJestConfig();
 
 const config = {
-  // The default configuration comes from @storybook/test-runner
+  // The default Jest configuration comes from @storybook/test-runner
   ...defaultConfig,
   snapshotResolver: './snapshot-resolver.js',
 };

README.md

@@ -204,7 +204,7 @@ const testRunnerConfig = getJestConfig();
  * @type {import('@jest/types').Config.InitialOptions}
  */
 module.exports = {
-  // The default configuration comes from @storybook/test-runner
+  // The default Jest configuration comes from @storybook/test-runner
   ...testRunnerConfig,
   /** Add your own overrides below
    * @see https://jestjs.io/docs/configuration
@@ -299,10 +299,13 @@ If your Storybook does not have a `stories.json` file, you can generate one, pro
 
 To enable `stories.json` in your Storybook, set the `buildStoriesJson` feature flag in `.storybook/main.js`:
 
-```js
-module.exports = {
+```ts
+// .storybook/main.ts
+const config = {
+  // ... rest of the config
   features: { buildStoriesJson: true },
 };
+export default config;
 ```
 
 Once you have a valid `stories.json` file, your Storybook will be compatible with the "index.json mode".
@@ -409,12 +412,13 @@ yarn add -D @storybook/addon-coverage
 
 And register it in your `.storybook/main.js` file:
 
-```js
-// .storybook/main.js
-module.exports = {
+```ts
+// .storybook/main.ts
+const config = {
   // ...rest of your code here
   addons: ['@storybook/addon-coverage'],
 };
+export default config;
 ```
 
 The addon has default options that might suffice for your project, and it accepts an [options object for project-specific configuration](https://github.com/storybookjs/addon-coverage#configuring-the-addon).
@@ -555,13 +559,16 @@ All three functions can be set up in the configuration file `.storybook/test-run
 
 Async function that executes once before all the tests run. Useful for setting node-related configuration, such as extending Jest global `expect` for accessibility matchers.
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   async setup() {
     // execute whatever you like, in Node, once before all tests run
   },
 };
+export default config;
 ```
 
 #### preRender (deprecated)
@@ -574,13 +581,16 @@ module.exports = {
 Async function that receives a [Playwright Page](https://playwright.dev/docs/pages) and a context object with the current story's `id`, `title`, and `name`.
 Executes within a test before the story is rendered. Useful for configuring the Page before the story renders, such as setting up the viewport size.
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   async preVisit(page, context) {
     // execute whatever you like, before the story renders
   },
 };
+export default config;
 ```
 
 #### postRender (deprecated)
@@ -593,13 +603,16 @@ module.exports = {
 Async function that receives a [Playwright Page](https://playwright.dev/docs/pages) and a context object with the current story's `id`, `title`, and `name`.
 Executes within a test after a story is rendered. Useful for asserting things after the story is rendered, such as DOM and image snapshotting.
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   async postVisit(page, context) {
     // execute whatever you like, after the story renders
   },
 };
+export default config;
 ```
 
 > **Note**
@@ -609,7 +622,7 @@ module.exports = {
 
 To visualize the test lifecycle with these hooks, consider a simplified version of the test code automatically generated for each story in your Storybook:
 
-```js
+```ts
 // executed once, before the tests
 await setup();
 
@@ -620,13 +633,13 @@ it('button--basic', async () => {
   // playwright page https://playwright.dev/docs/pages
   await page.goto(STORYBOOK_URL);
 
-  // pre-render hook
+  // pre-visit hook
   if (preVisit) await preVisit(page, context);
 
-  // render the story and run its play function (if applicable)
+  // render the story and watch its play function (if applicable)
   await page.execute('render', context);
 
-  // post-render hook
+  // post-visit hook
   if (postVisit) await postVisit(page, context);
 });
 ```
@@ -654,31 +667,37 @@ For reference, please use the [default `prepare`](https://github.com/storybookjs
 
 The test-runner makes a few `fetch` calls to check the status of a Storybook instance, and to get the index of the Storybook's stories. Additionally, it visits a page using Playwright. In all of these scenarios, it's possible, depending on where your Storybook is hosted, that you might need to set some HTTP headers. For example, if your Storybook is hosted behind a basic authentication, you might need to set the `Authorization` header. You can do so by passing a `getHttpHeaders` function to your test-runner config. That function receives the `url` of the fetch calls and page visits, and should return an object with the headers to be set.
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   getHttpHeaders: async (url) => {
     const token = url.includes('prod') ? 'XYZ' : 'ABC';
     return {
       Authorization: `Bearer ${token}`,
     };
   },
 };
+export default config;
 ```
 
 #### tags
 
 The `tags` property contains three options: `include | exclude | skip`, each accepting an array of strings:
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   tags: {
     include: [], // string array, e.g. ['test-only']
     exclude: [], // string array, e.g. ['design', 'docs-only']
     skip: [], // string array, e.g. ['design']
   },
 };
+export default config;
 ```
 
 `tags` are used for filtering your tests. Learn more [here](#filtering-tests-experimental).
@@ -693,7 +712,7 @@ While running tests using the hooks, you might want to get information from a st
 
 Suppose your story looks like this:
 
-```js
+```ts
 // ./Button.stories.ts
 
 export const Primary = {
@@ -705,12 +724,12 @@ export const Primary = {
 
 You can access its context in a test hook like so:
 
-```js
-// .storybook/test-runner.js
-const { getStoryContext } = require('@storybook/test-runner');
+```ts
+// .storybook/test-runner.ts
+import { TestRunnerConfig, getStoryContext } from '@storybook/test-runner';
 
-module.exports = {
-  async postVisit(page, context) {
+const config: TestRunnerConfig = {
+  async postRender(page, context) {
     // Get entire context of a story, including parameters, args, argTypes, etc.
     const storyContext = await getStoryContext(page, context);
     if (storyContext.parameters.theme === 'dark') {
@@ -720,6 +739,7 @@ module.exports = {
     }
   },
 };
+export default config;
 ```
 
 It's useful for skipping or enhancing use cases like [image snapshot testing](#image-snapshot), [accessibility testing](#accessibility-testing) and more.
@@ -728,25 +748,26 @@ It's useful for skipping or enhancing use cases like [image snapshot testing](#i
 
 The `waitForPageReady` utility is useful when you're executing [image snapshot testing](#image-snapshot) with the test-runner. It encapsulates a few assertions to make sure the browser has finished downloading assets.
 
-```js
-// .storybook/test-runner.js
-const { waitForPageReady } = require('@storybook/test-runner');
+```ts
+// .storybook/test-runner.ts
+import { TestRunnerConfig, waitForPageReady } from '@storybook/test-runner';
 
-module.exports = {
-  async postVisit(page, context) {
+const config: TestRunnerConfig = {
+  async postRender(page, context) {
     // use the test-runner utility to wait for fonts to load, etc.
     await waitForPageReady(page);
 
     // by now, we know that the page is fully loaded
   },
 };
+export default config;
 ```
 
 #### StorybookTestRunner user agent
 
 The test-runner adds a `StorybookTestRunner` entry to the browser's user agent. You can use it to determine if a story is rendering in the context of the test runner. This might be useful if you want to disable certain features in your stories when running in the test runner, though it's likely an edge case.
 
-```js
+```ts
 // At the render level, useful for dynamically rendering something based on the test-runner
 export const MyStory = {
   render: () => {
@@ -776,14 +797,14 @@ Below you will find recipes that use both the hooks and the utility functions to
 
 You can use [Playwright's Page viewport utility](https://playwright.dev/docs/api/class-page#page-set-viewport-size) to programatically change the viewport size of your test. If you use [@storybook/addon-viewports](https://storybook.js.org/addons/@storybook/addon-viewport), you can reuse its parameters and make sure that the tests match in configuration.
 
-```js
-// .storybook/test-runner.js
-const { getStoryContext } = require('@storybook/test-runner');
-const { MINIMAL_VIEWPORTS } = require('@storybook/addon-viewport');
+```ts
+// .storybook/test-runner.ts
+import { TestRunnerConfig, getStoryContext } from '@storybook/test-runner';
+import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 const DEFAULT_VIEWPORT_SIZE = { width: 1280, height: 720 };
 
-module.exports = {
+const config: TestRunnerConfig = {
   async preVisit(page, story) {
     const context = await getStoryContext(page, story);
     const viewportName = context.parameters?.viewport?.defaultViewport;
@@ -805,19 +826,20 @@ module.exports = {
     }
   },
 };
+export default config;
 ```
 
 ### Accessibility testing
 
 You can install `axe-playwright` and use it in tandem with the test-runner to test the accessibility of your components.
 If you use [`@storybook/addon-a11y`](https://storybook.js.org/addons/@storybook/addon-a11y), you can reuse its parameters and make sure that the tests match in configuration, both in the accessibility addon panel and the test-runner.
 
-```js
-// .storybook/test-runner.js
-const { getStoryContext } = require('@storybook/test-runner');
-const { injectAxe, checkA11y, configureAxe } = require('axe-playwright');
+```ts
+// .storybook/test-runner.ts
+import { TestRunnerConfig, getStoryContext } from '@storybook/test-runner';
+import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
 
-module.exports = {
+const config: TestRunnerConfig = {
   async preVisit(page, context) {
     // Inject Axe utilities in the page before the story renders
     await injectAxe(page);
@@ -847,27 +869,31 @@ module.exports = {
     });
   },
 };
+export default config;
 ```
 
 ### DOM snapshot (HTML)
 
 You can use [Playwright's built in APIs](https://playwright.dev/docs/test-snapshots) for DOM snapshot testing:
 
-```js
-// .storybook/test-runner.js
-module.exports = {
+```ts
+// .storybook/test-runner.ts
+import type { TestRunnerConfig } from '@storybook/test-runner';
+
+const config: TestRunnerConfig = {
   async postVisit(page, context) {
     // the #storybook-root element wraps the story. In Storybook 6.x, the selector is #root
     const elementHandler = await page.$('#storybook-root');
     const innerHTML = await elementHandler.innerHTML();
     expect(innerHTML).toMatchSnapshot();
   },
 };
+export default config;
 ```
 
 When running with `--stories-json`, tests get generated in a temporary folder and snapshots get stored alongside. You will need to `--eject` and configure a custom [`snapshotResolver`](https://jestjs.io/docs/configuration#snapshotresolver-string) to store them elsewhere, e.g. in your working directory:
 
-```js
+```ts
 // ./test-runner-jest.config.js
 const { getJestConfig } = require('@storybook/test-runner');
 
@@ -877,13 +903,13 @@ const testRunnerConfig = getJestConfig();
  * @type {import('@jest/types').Config.InitialOptions}
  */
 module.exports = {
-  // The default configuration comes from @storybook/test-runner
+  // The default Jest configuration comes from @storybook/test-runner
   ...testRunnerConfig,
   snapshotResolver: './snapshot-resolver.js',
 };
 ```
 
-```js
+```ts
 // ./snapshot-resolver.js
 const path = require('path');
 
@@ -904,14 +930,14 @@ module.exports = {
 
 Here's a slightly different recipe for image snapshot testing:
 
-```js
-// .storybook/test-runner.js
-const { waitForPageReady } = require('@storybook/test-runner');
-const { toMatchImageSnapshot } = require('jest-image-snapshot');
+```ts
+// .storybook/test-runner.ts
+import { TestRunnerConfig, waitForPageReady } from '@storybook/test-runner';
+import { toMatchImageSnapshot } from 'jest-image-snapshot';
 
 const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
 
-module.exports = {
+const config: TestRunnerConfig = {
   setup() {
     expect.extend({ toMatchImageSnapshot });
   },
@@ -928,10 +954,9 @@ module.exports = {
     });
   },
 };
+export default config;
 ```
 
-There is also an exported `TestRunnerConfig` type available for TypeScript users.
-
 ## Troubleshooting
 
 #### The error output in the CLI is too short

playwright/test-runner-jest.config.js

@@ -1,6 +1,6 @@
 const { getJestConfig } = require('@storybook/test-runner');
 
-// The default configuration comes from @storybook/test-runner
+// The default Jest configuration comes from @storybook/test-runner
 const testRunnerConfig = getJestConfig();
 
 /**