Add isTestRunner utility

.storybook/preview.js

@@ -0,0 +1,11 @@
+import { isTestRunner } from '../dist/esm/is-test-runner';
+
+const withSkippableTests = (StoryFn, { parameters }) => {
+  if (parameters.test?.skip && isTestRunner()) {
+    return () => {};
+  }
+
+  return StoryFn();
+};
+
+export const decorators = [withSkippableTests];

README.md

@@ -27,7 +27,9 @@ Storybook test runner turns all of your stories into executable tests.
   - [DOM snapshot recipe](#dom-snapshot-recipe)
   - [Image snapshot recipe](#image-snapshot-recipe)
   - [Render lifecycle](#render-lifecycle)
-  - [Global utility functions](#global-utility-functions)
+  - [Utility functions](#utility-functions)
+    - [getStoryContext](#getstorycontext)
+    - [isTestRunner](#istestrunner)
 - [Troubleshooting](#troubleshooting)
   - [The error output in the CLI is too short](#the-error-output-in-the-cli-is-too-short)
   - [The test runner seems flaky and keeps timing out](#the-test-runner-seems-flaky-and-keeps-timing-out)
@@ -475,7 +477,11 @@ it('button--basic', async () => {
 });
 ```
 
-### Global utility functions
+### Utility functions
+
+For more specific use cases, the test runner provides utility functions that could be useful to you.
+
+#### getStoryContext
 
 While running tests using the hooks, you might want to get information from a story, such as the parameters passed to it, or its args. The test runner now provides a `getStoryContext` utility function that fetches the story context for the current story:
 
@@ -506,7 +512,7 @@ module.exports = {
     // Apply story-level a11y rules
     await configureAxe(page, {
       rules: storyContext.parameters?.a11y?.config?.rules,
-    })
+    });
 
     // from Storybook 7.0 onwards, the selector should be #storybook-root
     await checkA11y(page, '#root', {
@@ -521,6 +527,25 @@ module.exports = {
 };
 ```
 
+#### isTestRunner
+
+The `isTestRunner` function can be used to determine if a story is rendering in the context of the test runner.
+
+```js
+import { isTestRunner } from '@storybook/test-runner/is-test-runner';
+export const MyStory = () => (
+  <div>
+    <p>Is this story running in the test runner?</p>
+    <p>{isTestRunner() ? 'Yes' : 'No'}</p>
+  </div>
+);
+```
+
+The result of `isTestRunner()` will be true in the following scenarios:
+
+1. In the browser, when the story is rendered while running the test runner
+2. In node, if you prepend your Storybook script with `STORYBOOK_TEST_RUNNER=true`
+
 ## Troubleshooting
 
 #### The error output in the CLI is too short

bin/test-storybook.js

@@ -9,13 +9,13 @@ const fs = require('fs');
 const dedent = require('ts-dedent').default;
 const path = require('path');
 const tempy = require('tempy');
-const semver = require('semver');
 const { getCliOptions, getStorybookMetadata } = require('../dist/cjs/util');
 const { transformPlaywrightJson } = require('../dist/cjs/playwright/transformPlaywrightJson');
 
 // Do this as the first thing so that any code reading it knows the right env.
 process.env.BABEL_ENV = 'test';
 process.env.NODE_ENV = 'test';
+process.env.STORYBOOK_TEST_RUNNER = 'true';
 process.env.PUBLIC_URL = '';
 
 // Makes the script crash on unhandled rejections instead of silently

package.json

@@ -18,7 +18,21 @@
   "license": "MIT",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
-  "types": "dist/ts/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/ts/index.d.ts"
+    },
+    "./is-test-runner": {
+      "import": "./dist/esm/is-test-runner.mjs",
+      "require": "./dist/cjs/is-test-runner.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "test-storybook": "./bin/test-storybook.js"
+  },
   "files": [
     "bin",
     "dist/**/*",
@@ -30,8 +44,8 @@
   "scripts": {
     "clean": "rimraf ./dist",
     "buildBabel": "concurrently \"yarn buildBabel:cjs\" \"yarn buildBabel:esm\"",
-    "buildBabel:cjs": "babel ./src -d ./dist/cjs --extensions \".js,.jsx,.ts,.tsx\"",
-    "buildBabel:esm": "babel ./src -d ./dist/esm --env-name esm --extensions \".js,.jsx,.ts,.tsx\"",
+    "buildBabel:cjs": "babel ./src -d ./dist/cjs --extensions \".js,.jsx,.ts,.tsx,.cjs,.mjs\"",
+    "buildBabel:esm": "babel ./src -d ./dist/esm --env-name esm --extensions \".js,.jsx,.ts,.tsx,.cjs,.mjs\"",
     "buildTsc": "tsc --declaration --emitDeclarationOnly --outDir ./dist/ts",
     "prebuild": "yarn clean",
     "build": "concurrently \"yarn buildBabel\" \"yarn buildTsc\"",
@@ -52,9 +66,6 @@
     "generate-dynamic-stories": "node scripts/generate-dynamic-stories.js",
     "prepare": "husky install"
   },
-  "bin": {
-    "test-storybook": "./bin/test-storybook.js"
-  },
   "devDependencies": {
     "@auto-it/released": "^10.37.1",
     "@babel/cli": "^7.12.1",
@@ -125,6 +136,7 @@
     "jest-watch-typeahead": "^2.0.0",
     "node-fetch": "^2",
     "playwright": "^1.14.0",
+    "read-pkg-up": "^7.0.1",
     "regenerator-runtime": "^0.13.9",
     "semver": "^7.3.7",
     "tempy": "^1.0.1",

src/is-test-runner/is-test-runner.cjs

@@ -0,0 +1,8 @@
+/**
+ * Returns whether the story is rendering inside of the Storybook test runner.
+ */
+module.exports = {
+  isTestRunner: function () {
+    return process?.env?.STORYBOOK_TEST_RUNNER === 'true';
+  }
+}

src/is-test-runner/is-test-runner.mjs

@@ -0,0 +1,10 @@
+/**
+ * Returns whether the story is rendering inside of the Storybook test runner.
+ */
+export function isTestRunner() {
+  return!!(
+    typeof window !== 'undefined' &&
+    window &&
+    window.navigator.userAgent.match(/StorybookTestRunner/)
+  );
+}

src/setup-page.ts

@@ -1,5 +1,5 @@
 import type { Page } from 'playwright';
-import dedent from 'ts-dedent';
+import readPackageUp from 'read-pkg-up';
 
 const sanitizeURL = (url: string) => {
   let finalURL = url;
@@ -25,8 +25,9 @@ const sanitizeURL = (url: string) => {
 export const setupPage = async (page: Page) => {
   const targetURL = new URL('iframe.html', process.env.TARGET_URL).toString();
   const viewMode = process.env.VIEW_MODE || 'story';
-  const isCoverageMode = process.env.STORYBOOK_COLLECT_COVERAGE === 'true';
   const renderedEvent = viewMode === 'docs' ? 'docsRendered' : 'storyRendered';
+  const { packageJson } = await readPackageUp();
+  const { version: testRunnerVersion } = packageJson;
 
   const referenceURL = process.env.REFERENCE_URL && sanitizeURL(process.env.REFERENCE_URL);
   const debugPrintLimit = process.env.DEBUG_PRINT_LIMIT
@@ -102,6 +103,17 @@ export const setupPage = async (page: Page) => {
         return input;
       }
 
+      function addToUserAgent(extra) {
+        const originalUserAgent = globalThis.navigator.userAgent;
+        if (!originalUserAgent.includes(extra)) {
+          Object.defineProperty(globalThis.navigator, 'userAgent', {
+            get: function () {
+              return [originalUserAgent, extra].join(' ');
+            },
+          });
+        }
+      };
+
       class StorybookTestRunnerError extends Error {
         constructor(storyId, errorMessage, logs) {
           super(errorMessage);
@@ -166,6 +178,8 @@ export const setupPage = async (page: Page) => {
           );
         }
 
+        addToUserAgent(\`(StorybookTestRunner@${testRunnerVersion})\`);
+
         // collect logs to show upon test error
         let logs = [];
 

stories/atoms/Button.stories.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import { expect } from '@storybook/jest';
+import { isTestRunner } from '../../dist/esm/is-test-runner';
 import { within, waitFor, userEvent, waitForElementToBeRemoved } from '@storybook/testing-library';
 
 import { Button } from './Button';
@@ -109,3 +110,25 @@ WithLoaders.play = async ({ args, canvasElement }) => {
   await userEvent.click(todoItem);
   await expect(args.onSubmit).toHaveBeenCalledWith('delectus aut autem');
 };
+
+export const UserAgent = () => (
+  <div>
+    <p>
+      <strong>isTestRunner:</strong> {isTestRunner().toString()}
+    </p>
+    <p>
+      <strong>User agent:</strong> {window.navigator.userAgent}
+    </p>
+  </div>
+);
+UserAgent.play = async () => {
+  if (isTestRunner()) {
+    await expect(window.navigator.userAgent).toContain('StorybookTestRunner');
+  }
+};
+UserAgent.parameters = {
+  tests: {
+    skip: true,
+    disableSnapshots: true,
+  },
+};