Test-runner file for hook configuration

.storybook/test-runner.ts

@@ -0,0 +1,21 @@
+import { toMatchImageSnapshot } from 'jest-image-snapshot';
+import type { TestRunnerConfig } from '../dist/ts';
+
+const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
+
+const config: TestRunnerConfig = {
+  setup() {
+    expect.extend({ toMatchImageSnapshot });
+  },
+  async postRender(page, context) {
+    const image = await page.screenshot();
+    expect(image).toMatchImageSnapshot({
+      customSnapshotsDir,
+      customSnapshotIdentifier: context.id,
+      failureThreshold: 0.03,
+      failureThresholdType: 'percent',
+    });
+  },
+};
+
+export default config;

README.md

@@ -17,9 +17,10 @@ Storybook test runner turns all of your stories into executable tests.
     - [2. Running against locally built Storybooks in CI](#2-running-against-locally-built-storybooks-in-ci)
   - [Experimental test hook API](#experimental-test-hook-api)
     - [Image snapshot recipe](#image-snapshot-recipe)
+    - [Render lifecycle](#render-lifecycle)
   - [Troubleshooting](#troubleshooting)
-    - [The test runner seems flaky and keeps timing out](#the-test-runner-seems-flaky-and-keeps-timing-out)
-    - [Adding the test runner to other CI environments](#adding-the-test-runner-to-other-ci-environments)
+      - [The test runner seems flaky and keeps timing out](#the-test-runner-seems-flaky-and-keeps-timing-out)
+      - [Adding the test runner to other CI environments](#adding-the-test-runner-to-other-ci-environments)
   - [Future work](#future-work)
 
 ## Features
@@ -255,10 +256,40 @@ The test runner renders a story and executes its [play function](https://storybo
 
 To enable use cases like visual or DOM snapshots, the test runner exports test hooks that can be overridden globally. These hooks give you access to the test lifecycle before and after the story is rendered.
 
-The hooks, `preRender` and `postRender`, are functions that take a [Playwright Page](https://playwright.dev/docs/pages) and a context object with the current story `id`, `title`, and `name`. They are globally settable by `@storybook/test-runner`'s `setPreRender` and `setPostRender` APIs.
+There are three hooks: `setup`, `preRender`, and `postRender`. `setup` executes once before all the tests run. `preRender` and `postRender` execute within a test before and after a story is rendered.
+
+The render functions are async functions that receive a [Playwright Page](https://playwright.dev/docs/pages) and a context object with the current story `id`, `title`, and `name`. They are globally settable by `@storybook/test-runner`'s `setPreRender` and `setPostRender` APIs.
+
+All three functions can be set up in the configuration file `.storybook/test-runner.js` which can optionally export any of these functions.
 
 > **NOTE:** 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.
 
+### Image snapshot recipe
+
+Consider, for example, the following recipe to take image snapshots:
+
+```js
+// .storybook/test-runner.js
+const { toMatchImageSnapshot } = require('jest-image-snapshot');
+
+const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
+
+module.exports = {
+  setup() {
+    expect.extend({ toMatchImageSnapshot });
+  },
+  async postRender(page, context) {
+    const image = await page.screenshot();
+    expect(image).toMatchImageSnapshot({
+      customSnapshotsDir,
+      customSnapshotIdentifier: context.id,
+    });
+  },
+};
+```
+
+### Render lifecycle
+
 To visualize the test lifecycle, consider a simplified version of the test code automatically generated for each story in your Storybook:
 
 ```js
@@ -280,28 +311,6 @@ it('button--basic', async () => {
 });
 ```
 
-### Image snapshot recipe
-
-If you want to make the test runner take image snapshots, the following recipe uses test hooks in `jest-setup.js` to do it:
-
-```js
-const { toMatchImageSnapshot } = require('jest-image-snapshot');
-const { setPostRender } = require('@storybook/test-runner');
-
-expect.extend({ toMatchImageSnapshot });
-
-// use custom directory/id to align CSF and stories.json mode outputs
-const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
-
-setPostRender(async (page, context) => {
-  const image = await page.screenshot();
-  expect(image).toMatchImageSnapshot({
-    customSnapshotsDir,
-    customSnapshotIdentifier: context.id,
-  });
-});
-```
-
 ## Troubleshooting
 
 #### The test runner seems flaky and keeps timing out

playwright/jest-setup.js

@@ -0,0 +1,14 @@
+const { getTestRunnerConfig, setPreRender, setPostRender } = require('../dist/cjs');
+
+const testRunnerConfig = getTestRunnerConfig(process.env.STORYBOOK_CONFIG_DIR);
+if (testRunnerConfig) {
+  if (testRunnerConfig.setup) {
+    testRunnerConfig.setup();
+  }
+  if (testRunnerConfig.preRender) {
+    setPreRender(testRunnerConfig.preRender);
+  }
+  if (testRunnerConfig.postRender) {
+    setPostRender(testRunnerConfig.postRender);
+  }
+}

src/config/jest-playwright.ts

@@ -13,7 +13,7 @@ export const getJestConfig = () => {
     globalSetup: '@storybook/test-runner/playwright/global-setup.js',
     globalTeardown: '@storybook/test-runner/playwright/global-teardown.js',
     testEnvironment: '@storybook/test-runner/playwright/custom-environment.js',
-    // @TODO: setupFilesAfterEnv: ['@storybook/test-runner/setup']
+    setupFilesAfterEnv: ['@storybook/test-runner/playwright/jest-setup.js'],
   };
 
   if (TEST_MATCH) {

src/index.ts

@@ -1,2 +1,3 @@
 export * from './playwright/hooks';
 export * from './config/jest-playwright';
+export * from './util/getTestRunnerConfig';

src/playwright/hooks.ts

@@ -9,6 +9,12 @@ export type TestContext = {
 
 export type TestHook = (page: Page, context: TestContext) => Promise<void>;
 
+export interface TestRunnerConfig {
+  setup?: () => void;
+  preRender?: TestHook;
+  postRender?: TestHook;
+}
+
 export const setPreRender = (preRender: TestHook) => {
   global.__sbPreRender = preRender;
 };

src/util/getTestRunnerConfig.ts

@@ -0,0 +1,17 @@
+import { join, resolve } from 'path';
+import { serverRequire } from '@storybook/core-common';
+import { TestRunnerConfig } from '../playwright/hooks';
+
+let testRunnerConfig: TestRunnerConfig;
+let loaded = false;
+
+export const getTestRunnerConfig = (configDir: string): TestRunnerConfig | undefined => {
+  // testRunnerConfig can be undefined
+  if (loaded) {
+    return testRunnerConfig;
+  }
+
+  testRunnerConfig = serverRequire(join(resolve(configDir), 'test-runner'));
+  loaded = true;
+  return testRunnerConfig;
+};

src/util/index.ts

@@ -1,4 +1,5 @@
 export * from './getCliOptions';
+export * from './getTestRunnerConfig';
 export * from './getStorybookMain';
 export * from './getStorybookMetadata';
 export * from './getParsedCliOptions';

test-runner-jest.config.js

@@ -13,5 +13,5 @@ module.exports = {
   globalSetup: './playwright/global-setup.js',
   globalTeardown: './playwright/global-teardown.js',
   testEnvironment: './playwright/custom-environment.js',
-  setupFilesAfterEnv: ['<rootDir>/jest-setup.js'],
+  setupFilesAfterEnv: ['./playwright/jest-setup.js'],
 };