storyshots-puppeteer: introduce puppeteerTest and axeTest exports

addons/storyshots/storyshots-puppeteer/package.json

@@ -29,6 +29,7 @@
     "prepare": "node ../../../scripts/prepare.js"
   },
   "dependencies": {
+    "@hypnosphi/jest-puppeteer-axe": "^1.4.0",
     "@storybook/node-logger": "5.3.0-beta.5",
     "@storybook/router": "5.3.0-beta.5",
     "@types/jest-image-snapshot": "^2.8.0",

addons/storyshots/storyshots-puppeteer/src/axeTest.ts

@@ -0,0 +1,23 @@
+import '@hypnosphi/jest-puppeteer-axe';
+import { defaultCommonConfig, CommonConfig } from './config';
+import { puppeteerTest } from './puppeteerTest';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace,no-redeclare
+  namespace jest {
+    interface Matchers<R, T> {
+      toPassAxeTests(parameters: any): R;
+    }
+  }
+}
+
+export const axeTest = (customConfig: Partial<CommonConfig> = {}) =>
+  puppeteerTest({
+    ...defaultCommonConfig,
+    ...customConfig,
+    async testBody(page, options) {
+      const parameters = options.context.parameters.a11y;
+      const include = parameters?.element ?? '#root';
+      await expect(page).toPassAxeTests({ ...parameters, include });
+    },
+  });

addons/storyshots/storyshots-puppeteer/src/config.ts

@@ -0,0 +1,63 @@
+import { MatchImageSnapshotOptions } from 'jest-image-snapshot';
+import { Base64ScreenShotOptions, Browser, DirectNavigationOptions, Page } from 'puppeteer';
+
+export interface Context {
+  kind: string;
+  story: string;
+  parameters: {
+    [key: string]: any;
+  };
+}
+
+export interface CommonConfig {
+  storybookUrl: string;
+  chromeExecutablePath: string;
+  getGotoOptions: (options: { context: Context; url: string }) => DirectNavigationOptions;
+  customizePage: (page: Page) => Promise<void>;
+  getCustomBrowser: () => Promise<Browser>;
+  setupTimeout: number;
+  testTimeout: number;
+}
+
+export interface PuppeteerTestConfig extends CommonConfig {
+  testBody: (page: Page, options: { context: Context; url: string }) => void | Promise<void>;
+}
+
+export interface ImageSnapshotConfig extends CommonConfig {
+  getMatchOptions: (options: { context: Context; url: string }) => MatchImageSnapshotOptions;
+  getScreenshotOptions: (options: { context: Context; url: string }) => Base64ScreenShotOptions;
+  beforeScreenshot: (page: Page, options: { context: Context; url: string }) => void;
+}
+
+const noop: () => undefined = () => undefined;
+const asyncNoop: () => Promise<undefined> = async () => undefined;
+
+export const defaultCommonConfig: CommonConfig = {
+  storybookUrl: 'http://localhost:6006',
+  chromeExecutablePath: undefined,
+  getGotoOptions: noop,
+  customizePage: asyncNoop,
+  getCustomBrowser: undefined,
+  setupTimeout: 15000,
+  testTimeout: 15000,
+};
+
+export const defaultPuppeteerTestConfig: PuppeteerTestConfig = {
+  ...defaultCommonConfig,
+  testBody(page, options) {
+    const testBody = options.context.parameters.puppeteerTest;
+    if (testBody != null) {
+      return testBody(page, options);
+    }
+    return null;
+  },
+};
+
+// We consider taking the full page is a reasonable default.
+const defaultScreenshotOptions = () => ({ fullPage: true, encoding: 'base64' } as const);
+export const defaultImageSnapshotConfig: ImageSnapshotConfig = {
+  ...defaultCommonConfig,
+  getMatchOptions: noop,
+  getScreenshotOptions: defaultScreenshotOptions,
+  beforeScreenshot: noop,
+};

addons/storyshots/storyshots-puppeteer/src/imageSnapshot.ts

@@ -1,111 +1,20 @@
-import { Browser, Page } from 'puppeteer';
 import { toMatchImageSnapshot } from 'jest-image-snapshot';
-import { logger } from '@storybook/node-logger';
-import { constructUrl } from './url';
-import { ImageSnapshotConfig } from './ImageSnapshotConfig';
+import { defaultImageSnapshotConfig, ImageSnapshotConfig } from './config';
+import { puppeteerTest } from './puppeteerTest';
 
 expect.extend({ toMatchImageSnapshot });
 
-// We consider taking the full page is a reasonable default.
-const defaultScreenshotOptions = () => ({ fullPage: true, encoding: 'base64' } as const);
-
-const noop: () => undefined = () => undefined;
-const asyncNoop: () => Promise<undefined> = async () => undefined;
-
-const defaultConfig: ImageSnapshotConfig = {
-  storybookUrl: 'http://localhost:6006',
-  chromeExecutablePath: undefined,
-  getMatchOptions: noop,
-  getScreenshotOptions: defaultScreenshotOptions,
-  beforeScreenshot: noop,
-  getGotoOptions: noop,
-  customizePage: asyncNoop,
-  getCustomBrowser: undefined,
-  setupTimeout: 15000,
-  testTimeout: 15000,
-};
-
 export const imageSnapshot = (customConfig: Partial<ImageSnapshotConfig> = {}) => {
-  const {
-    storybookUrl,
-    chromeExecutablePath,
-    getMatchOptions,
-    getScreenshotOptions,
-    beforeScreenshot,
-    getGotoOptions,
-    customizePage,
-    getCustomBrowser,
-    setupTimeout,
-    testTimeout,
-  } = { ...defaultConfig, ...customConfig };
+  const config = { ...defaultImageSnapshotConfig, ...customConfig };
+  const { getMatchOptions, getScreenshotOptions, beforeScreenshot } = config;
 
-  let browser: Browser; // holds ref to browser. (ie. Chrome)
-  let page: Page; // Hold ref to the page to screenshot.
-
-  const testFn = async ({ context }: any) => {
-    const { kind, framework, name } = context;
-    if (framework === 'react-native') {
-      // Skip tests since we de not support RN image snapshots.
-      logger.error(
-        "It seems you are running imageSnapshot on RN app and it's not supported. Skipping test."
-      );
-
-      return;
-    }
-    const url = constructUrl(storybookUrl, kind, name);
-
-    if (!browser || !page) {
-      logger.error(
-        `Error when generating image snapshot for test ${kind} - ${name} : It seems the headless browser is not running.`
-      );
-
-      throw new Error('no-headless-browser-running');
-    }
-
-    expect.assertions(1);
-
-    let image;
-    try {
-      await customizePage(page);
-      await page.goto(url, getGotoOptions({ context, url }));
-      await beforeScreenshot(page, { context, url });
-      image = await page.screenshot(getScreenshotOptions({ context, url }));
-    } catch (e) {
-      logger.error(
-        `Error when connecting to ${url}, did you start or build the storybook first? A storybook instance should be running or a static version should be built when using image snapshot feature.`
-      );
-      throw e;
-    }
-
-    expect(image).toMatchImageSnapshot(getMatchOptions({ context, url }));
-  };
-  testFn.timeout = testTimeout;
-
-  testFn.afterAll = async () => {
-    if (getCustomBrowser && page) {
-      await page.close();
-    } else if (browser) {
-      await browser.close();
-    }
-  };
-
-  const beforeAll = async () => {
-    if (getCustomBrowser) {
-      browser = await getCustomBrowser();
-    } else {
-      // eslint-disable-next-line global-require
-      const puppeteer = require('puppeteer');
-      // add some options "no-sandbox" to make it work properly on some Linux systems as proposed here: https://github.com/Googlechrome/puppeteer/issues/290#issuecomment-322851507
-      browser = await puppeteer.launch({
-        args: ['--no-sandbox ', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-        executablePath: chromeExecutablePath,
-      });
-    }
-
-    page = await browser.newPage();
-  };
-  beforeAll.timeout = setupTimeout;
-  testFn.beforeAll = beforeAll;
-
-  return testFn;
+  return puppeteerTest({
+    ...config,
+    async testBody(page, options) {
+      expect.assertions(1);
+      await beforeScreenshot(page, options);
+      const image = await page.screenshot(getScreenshotOptions(options));
+      expect(image).toMatchImageSnapshot(getMatchOptions(options));
+    },
+  });
 };

addons/storyshots/storyshots-puppeteer/src/index.ts

@@ -1,2 +1,4 @@
-export * from './ImageSnapshotConfig';
+export * from './config';
+export * from './puppeteerTest';
+export * from './axeTest';
 export * from './imageSnapshot';

addons/storyshots/storyshots-puppeteer/src/puppeteerTest.ts

@@ -0,0 +1,87 @@
+import { Browser, Page } from 'puppeteer';
+import { logger } from '@storybook/node-logger';
+import { constructUrl } from './url';
+import { defaultPuppeteerTestConfig, PuppeteerTestConfig } from './config';
+
+export const puppeteerTest = (customConfig: Partial<PuppeteerTestConfig> = {}) => {
+  const {
+    storybookUrl,
+    chromeExecutablePath,
+    getGotoOptions,
+    customizePage,
+    getCustomBrowser,
+    testBody,
+    setupTimeout,
+    testTimeout,
+  } = { ...defaultPuppeteerTestConfig, ...customConfig };
+
+  let browser: Browser; // holds ref to browser. (ie. Chrome)
+  let page: Page; // Hold ref to the page to screenshot.
+
+  const testFn = async ({ context }: any) => {
+    const { kind, framework, name } = context;
+    if (framework === 'react-native') {
+      // Skip tests since RN is not a browser environment.
+      logger.error(
+        "It seems you are running puppeteer test on RN app and it's not supported. Skipping test."
+      );
+
+      return;
+    }
+    const url = constructUrl(storybookUrl, kind, name);
+
+    if (!browser || !page) {
+      logger.error(
+        `Error when running puppeteer test for ${kind} - ${name} : It seems the headless browser is not running.`
+      );
+
+      throw new Error('no-headless-browser-running');
+    }
+
+    try {
+      await customizePage(page);
+      await page.goto(url, getGotoOptions({ context, url }));
+    } catch (e) {
+      logger.error(
+        `Error when connecting to ${url}, did you start or build the storybook first? A storybook instance should be running or a static version should be built when using puppeteer test feature.`
+      );
+      throw e;
+    }
+    await testBody(page, { context, url });
+  };
+  testFn.timeout = testTimeout;
+
+  const cleanup = async () => {
+    if (getCustomBrowser && page) {
+      await page.close();
+    } else if (browser) {
+      await browser.close();
+    }
+  };
+
+  process.on('SIGINT', async () => {
+    await cleanup();
+    process.exit();
+  });
+  testFn.afterAll = cleanup;
+
+  const beforeAll = async () => {
+    if (getCustomBrowser) {
+      browser = await getCustomBrowser();
+    } else {
+      // eslint-disable-next-line global-require
+      const puppeteer = require('puppeteer');
+      // add some options "no-sandbox" to make it work properly on some Linux systems as proposed here: https://github.com/Googlechrome/puppeteer/issues/290#issuecomment-322851507
+      browser = await puppeteer.launch({
+        args: ['--no-sandbox ', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+        executablePath: chromeExecutablePath,
+      });
+    }
+
+    page = await browser.newPage();
+  };
+  beforeAll.timeout = setupTimeout;
+  testFn.beforeAll = beforeAll;
+
+  return testFn;
+};

examples/official-storybook/package.json

@@ -4,12 +4,12 @@
   "private": true,
   "scripts": {
     "build-storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true build-storybook -c ./",
-    "do-image-snapshots": "../../node_modules/.bin/jest --projects=./image-snapshots",
+    "do-storyshots-puppeteer": "../../node_modules/.bin/jest --projects=./storyshots-puppeteer",
     "generate-addon-jest-testresults": "jest --config=tests/addon-jest.config.json --json --outputFile=stories/addon-jest.testresults.json",
     "graphql": "node ./graphql-server/index.js",
-    "image-snapshots": "yarn run build-storybook && yarn run do-image-snapshots",
     "packtracker": "yarn storybook --smoke-test --quiet && cross-env PT_PROJECT_TOKEN=1af1d41b-d737-41d4-ac00-53c8f3913b53 packtracker-upload --stats=./node_modules/.cache/storybook/manager-stats.json",
-    "storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true start-storybook -p 9011 -c ./ --no-dll"
+    "storybook": "cross-env STORYBOOK_DISPLAY_WARNING=true DISPLAY_WARNING=true start-storybook -p 9011 -c ./ --no-dll",
+    "storyshots-puppeteer": "yarn run build-storybook && yarn run do-storyshots-puppeteer"
   },
   "devDependencies": {
     "@packtracker/webpack-plugin": "^2.0.1",

examples/official-storybook/stories/addon-storyshots.stories.js

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { styled } from '@storybook/theming';
 
 const Block = styled.div({
@@ -12,4 +12,24 @@ export default {
   title: 'Addons/Storyshots',
 };
 
-export const block = () => <Block />;
+export const block = () => {
+  const [hover, setHover] = useState(false);
+
+  return (
+    <Block data-test-block onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
+      {hover && 'I am hovered'}
+    </Block>
+  );
+};
+block.story = {
+  parameters: {
+    async puppeteerTest(page) {
+      const element = await page.$('[data-test-block]');
+      await element.hover();
+      const textContent = await element.getProperty('textContent');
+      const text = await textContent.jsonValue();
+      // eslint-disable-next-line jest/no-standalone-expect
+      expect(text).toBe('I am hovered');
+    },
+  },
+};

examples/official-storybook/storyshots-puppeteer/axe-tests.runner.js

@@ -0,0 +1,29 @@
+/* This file is not suffixed by ".test.js" to not being run with all other test files.
+ * This test needs the static build of the storybook to run.
+ * `yarn run storyshots-puppeteer` generates the static build & uses storyshots-puppeteer.
+ * */
+import path from 'path';
+import fs from 'fs';
+import initStoryshots from '@storybook/addon-storyshots';
+import { axeTest } from '@storybook/addon-storyshots-puppeteer';
+import { logger } from '@storybook/node-logger';
+
+// We run puppeteer tests on the static build of the storybook.
+// For this test to be meaningful, you must build the static version of the storybook *before* running this test suite.
+const pathToStorybookStatic = path.join(__dirname, '../', 'storybook-static');
+
+if (!fs.existsSync(pathToStorybookStatic)) {
+  logger.error(
+    'You are running puppeteer tests without having the static build of storybook. Please run "yarn run build-storybook" before running tests.'
+  );
+} else {
+  initStoryshots({
+    suite: 'Puppeteer tests',
+    storyKindRegex: /^Basics|UI/,
+    framework: 'react',
+    configPath: path.join(__dirname, '..'),
+    test: axeTest({
+      storybookUrl: `file://${pathToStorybookStatic}`,
+    }),
+  });
+}

examples/official-storybook/storyshots-puppeteer/jest.config.js

@@ -5,7 +5,7 @@ const finalJestConfig = { ...globalJestConfig };
 
 finalJestConfig.rootDir = path.join(__dirname, '../../..');
 finalJestConfig.testMatch = [
-  '<rootDir>/examples/official-storybook/image-snapshots/storyshots-image.runner.js',
+  '<rootDir>/examples/official-storybook/storyshots-puppeteer/*.runner.js',
 ];
 
 module.exports = finalJestConfig;

examples/official-storybook/storyshots-puppeteer/puppeteer-tests.runner.js

@@ -0,0 +1,29 @@
+/* This file is not suffixed by ".test.js" to not being run with all other test files.
+ * This test needs the static build of the storybook to run.
+ * `yarn run storyshots-puppeteer` generates the static build & uses storyshots-puppeteer.
+ * */
+import path from 'path';
+import fs from 'fs';
+import initStoryshots from '@storybook/addon-storyshots';
+import { puppeteerTest } from '@storybook/addon-storyshots-puppeteer';
+import { logger } from '@storybook/node-logger';
+
+// We run puppeteer tests on the static build of the storybook.
+// For this test to be meaningful, you must build the static version of the storybook *before* running this test suite.
+const pathToStorybookStatic = path.join(__dirname, '../', 'storybook-static');
+
+if (!fs.existsSync(pathToStorybookStatic)) {
+  logger.error(
+    'You are running puppeteer tests without having the static build of storybook. Please run "yarn run build-storybook" before running tests.'
+  );
+} else {
+  initStoryshots({
+    suite: 'Puppeteer tests',
+    storyKindRegex: /^Addons\/Storyshots/,
+    framework: 'react',
+    configPath: path.join(__dirname, '..'),
+    test: puppeteerTest({
+      storybookUrl: `file://${pathToStorybookStatic}`,
+    }),
+  });
+}

examples/official-storybook/storyshots-puppeteer/storyshots-image.runner.js

@@ -1,6 +1,6 @@
 /* This file is not suffixed by ".test.js" to not being run with all other test files.
  * This test needs the static build of the storybook to run.
- * `yarn run image-snapshots` generates the static build & uses the image snapshots behavior of storyshots.
+ * `yarn run storyshots-puppeteer` generates the static build & uses storyshots-puppeteer.
  * */
 import path from 'path';
 import fs from 'fs';

yarn.lock

@@ -2301,6 +2301,14 @@
   dependencies:
     "@hapi/hoek" "^8.3.0"
 
+"@hypnosphi/jest-puppeteer-axe@^1.4.0":
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/@hypnosphi/jest-puppeteer-axe/-/jest-puppeteer-axe-1.4.0.tgz#aa7a348934178fcb41defb688ebd493970e3d660"
+  integrity sha512-sQ1BpqNE9C2d0afEtm3LLQWfQjITuxHXaLF79sGDUGa7/DPnfn2qgzcQOtL9uPu7KnZOz95dmsUgoHXkyQbrmQ==
+  dependencies:
+    "@babel/runtime" "^7.4.4"
+    axe-puppeteer "^1.0.0"
+
 "@hypnosphi/jscodeshift@^0.6.4":
   version "0.6.4"
   resolved "https://registry.yarnpkg.com/@hypnosphi/jscodeshift/-/jscodeshift-0.6.4.tgz#49a3be6ac515af831f8a3e630380e3511c8c0fb7"
@@ -5586,11 +5594,18 @@ aws4@^1.8.0:
   resolved "https://registry.yarnpkg.com/aws4/-/aws4-1.8.0.tgz#f0e003d9ca9e7f59c7a508945d7b2ef9a04a542f"
   integrity sha512-ReZxvNHIOv88FlT7rxcXIIC0fPt4KZqZbOlivyWtXLt8ESx84zd3kMC6iK5jVeS2qt+g7ftS7ye4fi06X5rtRQ==
 
-axe-core@^3.3.2:
+axe-core@^3.1.2, axe-core@^3.3.2:
   version "3.4.0"
   resolved "https://registry.yarnpkg.com/axe-core/-/axe-core-3.4.0.tgz#a57ee620c182d5389aff229586aaae06bc541abe"
   integrity sha512-5C0OdgxPv/DrQguO6Taj5F1dY5OlkWg4SVmZIVABFYKWlnAc5WTLPzG+xJSgIwf2fmY+NiNGiZXhXx2qT0u/9Q==
 
+axe-puppeteer@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/axe-puppeteer/-/axe-puppeteer-1.0.0.tgz#cebbeec2c65a2e0cb7d5fd1e7aef26c5f71895a4"
+  integrity sha512-hTF3u4mtatgTN7fsLVyVgbRdNc15ngjDcTEuqhn9A7ugqLhLCryJWp9fzqZkNlrW8awPcxugyTwLPR7mRdPZmA==
+  dependencies:
+    axe-core "^3.1.2"
+
 axios-retry@^3.0.2:
   version "3.1.2"
   resolved "https://registry.yarnpkg.com/axios-retry/-/axios-retry-3.1.2.tgz#4f4dcbefb0b434e22b72bd5e28a027d77b8a3458"