Storybook Selenium Storyshots

Run multi-browser storyshot visual tests on Chrome, IE, and Safari (or more) with services like Browserstack.

This addon enables storybook storyshots with selenium which these services support and expect as a form of automation.

Quick Start

Install:

$ yarn add -D addon-storyshots-selenium browserstack-local-promise

Run a local storybook server (part of your CI or manually if you want).

Configure:

  // storyshots.spec.js
  import { imageSnapshot as seleniumImageSnapshots } from 'addon-storyshots-selenium'
  const browserstackLocal = require('browserstack-local-promise').default
  const browserstack = {
    key: '--key--',
    user: '--user--'
  }
  const browsers = [
    {
      browserName: 'Chrome',
      browser_version: '62.0',
      os: 'Windows',
      os_version: '10',
      resolution: '1024x768'
    'browserstack.user': browserstack.user,
    'browserstack.key': browserstack.key,
    'browserstack.local': 'true'
    }
  ]
  beforeAll(async () => {
    await browserstackLocal({ key: browserstack.key, force: true })
  })
  browsers.forEach(capabilities =>
    initStoryshots({
      suite: `Browsers ${capabilities.os}-${capabilities.os_version}-${
        capabilities.browserName
      }-${capabilities.browser_version}`,
      test: seleniumImageSnapshots({
        seleniumServer: 'http://hub-cloud.browserstack.com/wd/hub',
        capabilities
      })
    })
  )

Configuration

Internally, it uses jest-image-snapshot.

Specifying options to jest-image-snapshots

If you wish to customize jest-image-snapshot, then you can provide a getMatchOptions parameter that should return the options config object. Additionally, you can provide beforeScreenshot which is called before the screenshot is captured.

const getMatchOptions = ({context : {kind, story}, url}) => {
  return {
    failureThreshold: 0.2,
    failureThresholdType: 'percent',
  }
}
const beforeScreenshot = (page, {context : {kind, story}, url}) => {
  return new Promise(resolve =>
      setTimeout(() => {
          resolve();
      }, 600)
  )
}
initStoryshots({suite: 'Image storyshots', test: seleniumImageSnapshots({storybookUrl: 'http://localhost:6006', getMatchOptions, beforeScreenshot})});

getMatchOptions receives an object: { context: {kind, story}, url}. kind is the kind of the story and the story its name. url is the URL the browser will use to screenshot.

beforeScreenshot receives the Selenium driver instance and an object: { context: {kind, story}, url}. kind is the kind of the story and the story its name. url is the URL the browser will use to screenshot. beforeScreenshot is part of the promise chain and is called after the browser navigation is completed but before the screenshot is taken. It allows for triggering events on the page elements and delaying the screenshot and can be used avoid regressions due to mounting animations.

Specifying a custom get sequence

You might use get to specify a different flow when Selenium is navigating to a story.

const get = async (page, url) => {
  await page.get(url)
  await page.sleep(1000)
}
initStoryshots({suite: 'Image storyshots', test: seleniumImageSnapshots({storybookUrl: 'http://localhost:6006', getOptions})});

Customizing a page instance

Sometimes, there is a need to customize a page before it calls the get api.

function customizePage(page) {
  return page.executeScript("...");
}

initStoryshots({
  suite: 'Image storyshots', 
  test: seleniumImageSnapshots({
      storybookUrl: 'http://localhost:6006', 
      customizePage,
  })
});

Customizing a Selenium Driver

Some times you might have customizations such as browser-specific instructions. You can swap the default build function.

const build = ({ seleniumServer, capabilities })=>
    new webdriver.Builder()
      .usingServer(seleniumServer)
      .withCapabilities(capabilities)
      .setEdgeOptions(...)
      .build(),

initStoryshots({
  suite: 'Image storyshots', 
  test: seleniumImageSnapshots({
      storybookUrl: 'http://localhost:6006', 
      build,
  })
});

Contributing

Fork, implement, add tests, pull request, get my everlasting thanks and a respectable place here :).

Thanks:

To all Contributors - you make this happen, thanks!

Copyright

Copyright (c) 2018 @jondot. See LICENSE for further details.