storyshots-core

StoryShots

---

StoryShots adds automatic Jest Snapshot Testing for Storybook.

Framework Support

To use StoryShots, you must use your existing Storybook stories as the input for Jest Snapshot Testing.

Getting Started

Add the following module into your app.

npm install --save-dev @storybook/addon-storyshots

Configure your app for Jest

In many cases, for example Create React App, it's already configured for Jest. You just need to create a filename with the extension .test.js.

If you still need to configure jest you can use the resources mentioned below:

• Getting Started - Jest Official Documentation
• Javascript Testing with Jest - Egghead. paid content

Note: If you use React 16, you'll need to follow these additional instructions.

Note: Make sure you have added the json extention to moduleFileExtensions in jest.config.json. If this is missing it leads to the following error: Cannot find module 'spdx-license-ids' from 'scan.js'.

Configure Jest to work with Webpack's require.context()

Sometimes it's useful to configure Storybook with Webpack's require.context feature:

import { configure } from '@storybook/react';

const req = require.context('../stories', true, /.stories.js$/); // <- import all the stories at once

function loadStories() {
  req.keys().forEach(filename => req(filename));
}

configure(loadStories, module);

The problem here is that it will work only during the build with webpack, other tools may lack this feature. Since Storyshot is running under Jest, we need to polyfill this functionality to work with Jest. The easiest way is to integrate it to babel. One of the possible babel plugins to polyfill this functionality might be babel-plugin-require-context-hook.

To register it, add the following to your jest setup:

import registerRequireContextHook from 'babel-plugin-require-context-hook/register';
registerRequireContextHook();

And after, add the plugin to .babelrc:

{
  "presets": ["..."],
  "plugins": ["..."],
  "env": {
    "test": {
      "plugins": ["require-context-hook"]
    }
  }
}

Make sure not to include this babel plugin in the config environment that applies to webpack, otherwise it may replace a real require.context functionality.

Configure Jest for React

StoryShots addon for React is dependent on react-test-renderer, but doesn't install it, so you need to install it separately.

npm install --save-dev react-test-renderer

Configure Jest for Angular

StoryShots addon for Angular is dependent on jest-preset-angular, but doesn't install it, so you need to install it separately.

npm install --save-dev jest-preset-angular

If you already use Jest for testing your angular app - probably you already have the needed jest configuration. Anyway you can add these lines to your jest config:

module.exports = {
  globals: {
    __TRANSFORM_HTML__: true,
  },
  transform: {
    '^.+\\.jsx?$': 'babel-jest',
    '^.+\\.(ts|html)$': '<rootDir>/node_modules/jest-preset-angular/preprocessor.js',
  },
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node', '.html'],
};

Configure Jest for Vue

StoryShots addon for Vue is dependent on jest-vue-preprocessor, but doesn't install it, so you need to install it separately.

npm install --save-dev jest-vue-preprocessor

If you already use Jest for testing your vue app - probably you already have the needed jest configuration. Anyway you can add these lines to your jest config:

module.exports = {
  transform: {
    '^.+\\.jsx?$': 'babel-jest',
    '.*\\.(vue)$': '<rootDir>/node_modules/jest-vue-preprocessor',
  },
  transformIgnorePatterns: [
    '/node_modules/(?!(@storybook/.*\\.vue$))',
  ],
  moduleFileExtensions: ['vue', 'js', 'jsx', 'json', 'node'],
};

Why don't we install dependencies of each framework ?

Storyshots addon is currently supporting React, Angular and Vue. Each framework needs its own packages to be integrated with Jest. We don't want people that use only React will need to bring other dependencies that do not make sense for them.

dependencies - will installed an exact version of the particular dep - Storyshots can work with different versions of the same framework (let's say React v16 and React v15), that have to be compatible with a version of its plugin (react-test-renderer).

optionalDependencies - behaves like a regular dependency, but do not fail the installation in case there is a problem to bring the dep.

peerDependencies - listing all the deps in peer will trigger warnings during the installation - we don't want users to install unneeded deps by hand.

optionalPeerDependencies - unfortunately there is nothing like this =(

For more information read npm docs

Configure Storyshots for HTML snapshots

Create a new test file with the name Storyshots.test.js. (Or whatever the name you prefer, as long as it matches Jest's config testMatch). Then add following content to it:

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots();

That's all.

Now run your Jest test command. (Usually, npm test.) Then you can see all of your stories are converted as Jest snapshot tests.

Using createNodeMock to mock refs

react-test-renderer doesn't provide refs for rendered components. By default, it returns null when the refs are referenced. In order to mock out elements that rely on refs, you will have to use the createNodeMock option added to React starting with version 15.4.0.

Here is an example of how to specify the createNodeMock option in Storyshots:

import initStoryshots, { snapshotWithOptions } from '@storybook/addon-storyshots'
import TextareaThatUsesRefs from '../component/TextareaThatUsesRefs'

initStoryshots({
  test: snapshotWithOptions({
    createNodeMock: (element) => {
      if (element.type === TextareaThatUsesRefs) {
        return document.createElement('textarea')
      }
    },
  }),
})

Options

config

The config parameter must be a function that helps to configure storybook like the config.js does. If it's not specified, storyshots will try to use configPath parameter.

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  config: ({ configure }) =>
    configure(() => {
      require('../stories/Button.story.js');
    }, module),
});

configPath

By default, Storyshots assumes the config directory path for your project as below:

• Storybook for React: .storybook
• Storybook for React Native: storybook

If you are using a different config directory path, you could change it like this:

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  configPath: '.my-storybook-config-dir'
});

configPath can also specify path to the config.js itself. In this case, config directory will be a base directory of the configPath. It may be useful when the config.js for test should differ from the original one. It also may be useful for separating tests to different test configs:

initStoryshots({
  configPath: '.my-storybook-config-dir/testConfig1.js'
});

initStoryshots({
  configPath: '.my-storybook-config-dir/testConfig2.js'
});

suite

By default, Storyshots groups stories inside a Jest test suite called "Storyshots". You could change it like this:

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  suite: 'MyStoryshots'
});

storyKindRegex

If you'd like to only run a subset of the stories for your snapshot tests based on the story's kind:

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  storyKindRegex: /^MyComponent$/
});

This can be useful if you want to separate the snapshots in directories next to each component. See an example here.

If you want to run all stories except stories of a specific kind, you can write an inverse regex which is true for all kinds except those with a specific word such as DontTest

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  storyKindRegex:/^((?!.*?DontTest).)*$/
});

This can be useful while testing react components which make use of the findDomNode API since they always fail with snapshot testing while using react-test-renderer see here

storyNameRegex

If you'd like to only run a subset of the stories for your snapshot tests based on the story's name:

import initStoryshots from '@storybook/addon-storyshots';

initStoryshots({
  storyNameRegex: /buttons/
});

framework

If you are running tests from outside of your app's directory, storyshots' detection of which framework you are using may fail. Pass "react" or "react-native" to short-circuit this.

test

Run a custom test function for each story, rather than the default (a vanilla snapshot test). Setting test will take precedence over the renderer option. See the exports section below for more details.

renderer

Pass a custom renderer (such as enzymes mount) to record snapshots. Note that setting test overrides renderer.

import initStoryshots from '@storybook/addon-storyshots';
import { mount } from 'enzyme';

initStoryshots({
  renderer: mount,
});

If you are using enzyme, you need to make sure jest knows how to serialize rendered components. You can either pass in a serializer (see below) or specify an enzyme-compatible serializer (like enzyme-to-json, jest-serializer-enzyme etc.) as the default snapshotSerializer in your config.

Example for jest config in package.json:

"devDependencies": {
    "enzyme-to-json": "^3.2.2"
},
"jest": {
    "snapshotSerializers": [
      "enzyme-to-json/serializer"
    ]
  }

serializer

Pass a custom serializer (such as enzyme-to-json) to serialize components to snapshot-comparable data.

import initStoryshots from '@storybook/addon-storyshots';
import toJSON from 'enzyme-to-json';

initStoryshots({
  renderer: mount,
  serializer: toJSON,
});

This option only needs to be set if the default snapshotSerializers is not set in your jest config.

stories2snapsConverter

This parameter should be an instance of the Stories2SnapsConverter (or a derived from it) Class that is used to convert story-file name to snapshot-file name and vice versa.

By default, the instance of this class is created with these default options:

{
  snapshotsDirName: '__snapshots__',
  snapshotExtension: '.storyshot',
  storiesExtensions: ['.js', '.jsx', '.ts', '.tsx'],
}

This class might be overridden to extend the existing conversion functionality or instantiated to provide different options:

import initStoryshots, { Stories2SnapsConverter } from '@storybook/addon-storyshots';

initStoryshots({
  stories2snapsConverter: new Stories2SnapsConverter({
    snapshotExtension: '.storypuke',
    storiesExtensions: ['.foo'],
  }),
});

Exports

Apart from the default export (initStoryshots), Storyshots also exports some named test functions (see the test option above):

snapshot

The default, render the story as normal and take a Jest snapshot.

renderOnly

Just render the story, don't check the output at all (useful if you just want to ensure it doesn't error)

snapshotWithOptions(options)

Like the default, but allows you to specify a set of options for the test renderer. See for example here.

renderWithOptions(options)

Like the default, but allows you to specify a set of options for the renderer. See above.

multiSnapshotWithOptions(options)

Like snapshotWithOptions, but generate a separate snapshot file for each stories file rather than a single monolithic file (as is the convention in Jest). This makes it dramatically easier to review changes. If you'd like the benefit of separate snapshot files, but don't have custom options to pass, simply pass an empty object.

integrityOptions

This option is useful when running test with multiSnapshotWithOptions(options) in order to track snapshots are matching the stories. (disabled by default). The value is just a settings to a glob object, that searches for the snapshot files.

initStoryshots({
  integrityOptions: { cwd: __dirname }, // it will start searching from the current directory
  test: multiSnapshotWithOptions(),
});

shallowSnapshot

Take a snapshot of a shallow-rendered version of the component. Note that this option will be overriden if you pass a renderer option.

Stories2SnapsConverter

This is a class that generates snapshot's name based on the story (kind, story & filename) and vice versa.

Example:

Let's say we wanted to create a test function for shallow && multi-file snapshots:

import initStoryshots, { getSnapshotFileName } from '@storybook/addon-storyshots';
import { shallow } from 'enzyme';
import toJson from 'enzyme-to-json';

initStoryshots({
  test: ({ story, context }) => {
    const snapshotFileName = getSnapshotFileName(context);
    const storyElement = story.render(context);
    const shallowTree = shallow(storyElement);

    if (snapshotFileName) {
      expect(toJson(shallowTree)).toMatchSpecificSnapshot(snapshotFileName);
    }
  }
});