Visual Testing with Storybook
Note: Make sure that you use Storybook version
>=6.3.0before following the instructions below. For older versions of Storybook, you can visit the Gatsby v2 documentation.
Knowing your components look as intended in every permutation is an excellent way to test them visually and provides “living documentation” for them. It makes it easier for teams to:
- know what components are available to them in a given project and
- what props do those components accept and what all of the states of that component are.
As your project grows over time, having this information available will be invaluable. This is the function of Storybook. Storybook is a UI development environment for your UI components. With it, you can visualize different states of your UI components and develop them interactively.
Note: The following instructions are using npx.
npxis a part of npm. In this case, it allows you to automatically generate a file/folder structure complete with the default configuration. If you’re running an older version of
<5.2.0), you should run the following command instead:
npm install -g @storybook/cli. You can then run
sb initfrom your Gatsby root directory to initialize Storybook.
To set up Storybook, you need to install dependencies and do some custom configuration. You can get started quickly by using the automated command line tool from your Gatsby root directory:
Note: Using the builder flag will adjust Storybook’s bootstrap process to include webpack 5 support out of the box.
Running this command adds the necessary Storybook dependencies, configuration files, and a set of boilerplate stories that you can browse.
If you’re upgrading from a previous Storybook version, be advised that Storybook relies on webpack 4, and Gatsby is currently supporting webpack 5. To update your Storybook version, run the following command:
Add the following development dependencies to enable webpack 5 with Storybook:
Then, update your
.storybook/main.js to the following:
Additional configuration is required to allow Gatsby’s components to be manually tested with Storybook. If you want to learn more about Storybook’s configuration, continue reading. If you wish to streamline the process, jump to the addon section below.
Storybook’s webpack configuration will require adjustments to allow you to transpile Gatsby’s source files and ensure the proper Babel plugins are used.
In your Storybook configuration file (i.e.,
.storybook/main.js) add the following:
.storybook/main.js should look something like this:
Next, inside your
.storybook/preview.js add the following:
preview.jsfile allows you to set up decorators, parameters, and other aspects that affect the story rendering in the Canvas. Read more about it in the official documentation.
You can streamline the entire configuration process by adding the
storybook-addon-gatsby to your Gatsby project. Run the following command:
Next, register the addon within Storybook’s main configuration file (i.e.,
Storybook v6 has out-of-the-box support for TypeScript. Your components and stories can be authored with the
A complete guide to writing stories is beyond the scope of this guide, but we’ll take a look at creating a story.
Note: Writing stories for components that use
gatsby-plugin-imageis currently not supported. Contributions to making this possible are welcome.
First, create the story file. Storybook looks for all files with a
.stories.js extension and loads them into Storybook for you. Generally, you will want your stories near where the component is defined. However, since this is Gatsby, you will have to create those files outside the
pages directory if you want stories for your pages.
A good solution is to use the
stories directory which was created when Storybook was installed and put any page stories in there.
The example above is a straightforward story with Storybook’s args. If you want to learn more about how Storybook works and what you can do with it, check out some of the resources listed below.