Nightly Panic Munchies

    TypeScript icon, indicating that this package has built-in type declarations

    0.11.0 • Public • Published


    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

    Getting Started


    Install the following package:

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


    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';

    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.


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


    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';
      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.


    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.


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

    DownloadsWeekly Downloads






    Unpacked Size

    19 kB

    Total Files


    Last publish


    • andreasprang
    • feitm
    • tech_red
    • preventdefault