Documenting & Testing React Dashboard Components with Storybook 7.0

In my last article, I explained how to write stories for both simple components – like buttons – and more complex state-based components – like filters and dropdowns – with the help of Storybook.

In this article, I’ll show you how to document your own components with Storybook’s Autodocs feature and MDX. I will also give you a small introduction to Chromatic’s visual testing capability. 

But first, let’s talk about Storybook 7.0.

What Is Storybook 7.0?

The Storybook team released a new version at the beginning of April – Storybook 7.0. This version introduces a lot of changes regarding how you write and document stories. If you want to upgrade, the Storybook team provides you with a clear step-by-step tutorial on how to do so. It also gives you the option of migrating your components to the new story format CSF3.

If you don’t migrate your components after upgrading, they will still function in the old CSF2 format. However, you will see deprecated warnings.

In order to make sure this article is up to date with the Storybook 7.0 changes, I’ll work with the new documentation changes introduced in the update. This means you’ll need this version of Storybook to fully utilize these features.

How Do I Document My Components?

There are two ways to document your components in Storybook. You can use the Autodocs feature to utilize prop commenting and automatically generate documentation for your components. Or you can use MDX to customize the documentation page of your stories.

Let’s use our Button component from my last article:

interface IButtonProps {
 variant: 'text' | 'outlined';
 onClick: () => void;
 children: React.ReactNode;
}
export const MyButton: FC<IButtonProps> = ({ variant, onClick, children }) => (
 <Button variant={variant} onClick={onClick}>
   {children}
 </Button>
);

This is the corresponding story file that utilizes the new CSF3 format:

const meta: Meta<typeof MyButton> = {
 title: 'MyButton',
 component: MyButton,
 render: args => <MyButton {...args}>My Button</MyButton>,
};


export default meta;
type Story = StoryObj<typeof MyButton>;


export const Outlined: Story = {
 args: {
   variant: 'outlined',
 },
};


export const Text: Story = {
 args: { variant: 'text' },
};

When migrating to Storybook 7.0, during the automatic migration steps, the Autodocs feature will automatically be enabled by adding the following code to the main.js Storybook file.

ocs: {
   autodocs: true
 }

This will create the new docs substory for every component’s story.

The Autodocs feature will generate the documentation story and show you all the stories created and the component’s properties on one page.

With the help of prop commenting, you can enhance the props’ descriptions.

interface IButtonProps {
 /** The variant of the button. Outlined Buttons do have a border around the child. */
 variant: 'text' | 'outlined';
 /** The onClick function that will be executed when clicking on the button */
 onClick: () => void;
 children: React.ReactNode;
}
 /** Default Button Component for interaction. */
export const MyButton: FC<IButtonProps> = ({ variant, onClick, children }) => (
 <Button variant={variant} onClick={onClick}>
   {children}
 </Button>
);

As you can see, I’ve added comments above the properties in the TypeScript interface, as well as above the component itself. These comments will automatically be added to the documentation.

You can also add comments above the substories in the story file to give them a subheading.

You can use MDX to fully customize your stories or documentation. MDX utilizes a mix of Markdown and JSX so that you can generate your own stories and documentation layouts. One common use for MDX is to create overviews of icons, typography, or color options in your project. 

To create new MDX pages, create a new .stories.mdx file first. When using VSCode, I recommend installing the MDX plugin, which supports highlighting for the file. Every MDX file needs the meta tag for Storybook to render it correctly. The Storybook framework comes with some tags that you can import via @storybook/blocks.

{/* MuiIcons.stories.mdx */}


import {Meta} from '@storybook/blocks'


<Meta title="MuiIcons" />

As an example, we can create a small list of icons from MUI.

{/* MuiIcons.stories.mdx */}


import { Meta, IconGallery, IconItem } from '@storybook/blocks'
import { ArrowBack, ArrowForward, ArrowUpward, ArrowDownward } from '@mui/icons-material';


<Meta title="MuiIcons" />


# Mui Icons


<IconGallery>
 <IconItem name="ArrowBackIcon">
   <ArrowBack />
 </IconItem>
 <IconItem name="ArrowForwardIcon">
   <ArrowForward />
 </IconItem>
 <IconItem name="ArrowUpIcon">
   <ArrowUpward />
 </IconItem>
 <IconItem name="ArrowDownIcon">
   <ArrowDownward />
 </IconItem>
</IconGallery>

How Do I Test My Components with Storybook?

When it comes to our Storybook setup for the dashboard project we’re working on at adjoe, we publish our stories on successful deployment to our production servers.

We have enabled UI tests (which you can do in the Manage section of the Chromatic project options) that will be run automatically on the Chromatic project when a new Storybook build is pushed. These UI tests will create snapshots of each story created and compare it to the latest accepted baseline version of the component. 

When the test detects changes in the visual snapshot, or detects new components, it will set the status of the build to “Review.”

This means the build is not automatically accepted as the latest Storybook. A developer needs to manually review the change and either accept it or deny it.
If all changes are accepted, the build is marked as successful and is then the new baseline. All components of the latest accepted build will be used as the baseline for future UI tests. The permanent links to the library and Storybook will subsequently use this build.

If any change under review is denied (it does not matter if one or more are denied), the build is marked as failed. It will not be used as the new baseline, and new pushes of denied components will automatically be set to review, even if there are no changes to them.

At adjoe, we are currently thinking of utilizing Storybook’s UI test feature in addition to unit tests as an alternative to snapshots. You can set up merge requests in a way that they cannot be merged if the UI test is failing. This could either be due to the build being under review or a component being denied.

You can achieve this in various ways based on if you are using a linked or unlinked project in Chromatic. Unlinked projects are used by self-hosted GitLab repositories or enterprise providers. They cannot utilize direct merge request integrations with Chromatic, but have to use their CI settings to block merges.

Summarizing Storybook

Now you should have the tools to implement Storybook in your own React projects and utilize its visualization capabilities, documentation, and testing features to improve your daily development workflow.

If you want to learn more about Storybook, you can find a lot more information with examples on the official website. Especially, about the new Storybook 7.0 update.

I hope my articles about Storybook gave you a good introduction to the key features of Storybook’s framework. You now should have some useful examples to help you start working with it in your own projects. Thanks for reading!