@spring-media/storybook-addon-image-snapshots

Intro

This plugin uses @storybook/storyshots-puppeteer to capture screenshots from your stories. It provided some additional features like:

• capturing specific viewports (dependency on @storybook/addon-viewport)
• capture only specific elements on the page
• adds a panel in the storybook ui to display the snapshots However, the main purpose is to run the tests against a (chrome) browser that is running in a docker container, please see Why docker? for a detailed explanation.

Table of contents

• Installation
• Usage
  • Running storybook server
  • Static storybook build
  • Testing different viewports
  • Select a specific element
  • Custom configuration
  • Display snapshots in storybook
• Notes
  • Why Docker?

Getting Started

Installation

Install the following package:

npm i @spring-media/storybook-addon-image-snapshots -D

Usage

Within the .storybook/main.js add the package to the plugins list:

module.exports = {
  addons: ['@spring-media/storybook-addon-image-snapshots']
}

This is optional if you don't want to display the snapshots within storybook

Create a file image-snapshots.runner.js with the following content:

The file should not be suffixed with '.test.js' to avoid being run with all other test files

import { initImageSnapshots } from '@spring-media/storybook-addon-image-snapshots';

initImageSnapshots();

Add the following entry to the script section of your package.json:

"scripts": {
  "image-snapshots": "jest --config your-specific-jest.config.js image-snapshots.runner.js"
}

Do not forget to add a rule for the 'runner.js' suffix in jest's testMatch option.

Testing with a local running storybook server

By default, the plugin expects that a local storybook server is running on the port 9001.

Start the docker container with the following arguments:

docker run -p 9222:3000 --rm -d --name chrome browserless/chrome

Then run the previously added script:

npm run image-snapshots

Testing with a local static storybook build

There are a few things that has to be changed in order to test a static build of storybook:

docker run -p 9222:3000 -d --rm --name chrome -v $(pwd)/storybook-static/:/opt/storybook-static browserless/chrome

By default, storybook will create a storybook-static directory that contains all static files

Since the tests are running in a docker container, we must mount the local static directory into the containers file system

Change the storybookUrl option (see Custom Configuration) to file:///opt/storybook-static.

Testing different viewports

Testing different viewports requires the official @storybook/addon-viewport to be installed and activated.

Below is an example how to configure your story with the viewport configuration:

export const myStory = () => ({...});
myStory.story = {
  parameters: {
    viewport: {
      defaultViewport: 'small'
    }
  }
};

This example assumes, that a viewport plugin has a configuration entry with a key "small".

Select a specific element for taking a snapshot

You can configure the story to take a snapshot only of a certain element by providing a selector.

export const myStory = () => ({...});
myStory.story = {
  parameters: {
    imageSnapshot: {
      selector: '.my-element'
    }
  }
};

Disable image snapshots for specific stories

To disable specific stories from generating image snapshots, configure your story as follows:

export const myStory = () => ({...});
myStory.story = {
  parameters: {
    storyshots: {
      disable: true,
    }
  }
};

Custom Configuration

Since this plugin is only a wrapper around storyshots-puppeteer, the signature of initImageSnapshots is the same as initStoryshots. But, you should not customize getCustomBrowser, beforeScreenshot and getScreenshotOptions since there are used internally by this plugin.

browserUrl

This url should point to the running docker container (default: http://localhost:9222)

storybookUrl

This is the url to your storybook server that is called from within the docker container (default: http://host.docker.internal:9001)

Make sure your storybook server run on port 9001

You may ask what the heck is this host and where does it come from: host.docker.internal? Find more information here: docker networking why we need to set this host.

Display snapshots in storybook

This plugin adds a panel in the storybook ui to display the image snapshot of a story.

First register the addon in the main.js file:

module.exports = {
  addons: ['@spring-media/storybook-addon-image-snapshots']
}

Then you have to tell the panel where to find the image. You can do this by either add a global parameter in the preview.js file:

import { addParameters } from '@storybook/vue';

addParameters({
  imageSnapshots: {
    snapshotFileName: ({ id }) => `storyshots-${id}-snap.png`,
  },
});

or in the configuration of a story:

export const myStory = () => ({...});
myStory.story = {
  parameters: {
    imageSnapshots: {
      snapshotFileName: ({ id }) => `storyshots-${id}-snap.png`,
    }
  }
};

You can customize the filename of the snapshot through getMatchOptions

The last thing is to add the directory of your image snapshots to the static-dir configuration of the storybook server:

{
    "scripts": {
        "storybook": "start-storybook -p 8888 -s .image-snapshots"
    }
}

The example above assumes, that the images are be located within the .image-snapshots directory.

Notes

Why Docker?

There are some challenges when it comes to capture screens from a browser as described here. Because of that, we need a way to create a result that is as much as possible independent of the host system. By using docker, we get an isolated system that is reliable enough to produce the same results on different host systems.