@testplane/storybook

Overview

Use the @testplane/storybook plugin to automatically check the changes in your Storybook components with screenshot testing without a single line of test code.

This plugin adds:

automatic screenshot tests for storybook stories;
an ability to write Testplane tests for storybook stories right inside of the stories.

Installation

npm install @testplane/storybook --save-dev

Setup

info

Storybook 6.4+ is required to use this plugin.

Storybook

If you use storybook@6, you will need to enable buildStoriesJson feature in your storybook config:

export default {
    // ...
    features: {
        // ...
        buildStoriesJson: true,
    },
};

You don't need to do this with storybook@7 or storybook@8.

Testplane

Add @testplane/storybook plugin into your Testplane config:

.testplane.conf.ts
export default {
    plugins: {
        "@testplane/storybook": {},

        // other Testplane plugins...
    },

    // other Testplane settings...
};

With this minimal config, you will be able to run npx testplane --storybook to autotest each storybook story with Testplane assertView command. Testplane will open each story, wait for play function to finish (if defined), and then call assertView command. These tests would be generated in runtime.

Description of configuration parameters

Parameter	Type	Default	Description
enabled	`Boolean`	true	Enable / disable plugin.
storybookConfigDir	`String`	".storybook"	Path to the storybook configuration directory.
autoScreenshots	`Boolean`	true	Enable / disable auto-screenshot tests
autoscreenshotSelector	`String`	""	Custom selector, which will be used in auto-screenshot tests
autoScreenshotStorybookGlobals	`Record<string, Record<string, unknown>>`		Run multiple auto-screenshot tests with different storybook globals
localport	`Number`	6006	Port to launch storybook dev server on.
remoteStorybookUrl	`String`	""	URL of the remote Storybook. If specified, local storybook dev sever would not be launched.
browserIds	`Array<String \| RegExp>`	[]	Array of `browserId` to run storybook tests on. By default, all of browsers, specified in Testplane config would be used

info

Storybook tests performance greatly depends on Testplane testsPerSession parameter, as these tests speeds up on reusing existing sessions, so setting values around 20+ is preferred. These tests ignore Testplane isolation. It would be turned off unconditionally.

autoScreenshotStorybookGlobals

For example, with autoScreenshotStorybookGlobals set to:

{
    "default": {},
    "light theme": {
        "theme": "light"
    },
    "dark theme": {
        "theme": "dark"
    }
}

3 autoscreenshot tests will be generated for each story, each test having its corresponding storybook globals value:

... Autoscreenshot default
... Autoscreenshot light theme
... Autoscreenshot dark theme

Advanced usage

If you have ts-node in your project, you can write your Testplane tests right inside of storybook story files:

stories/Primary.stories.ts
import type { StoryObj } from "@storybook/react";
import type { WithTestplane } from "@testplane/storybook";

export const Primary: WithTestplane<StoryObj> = {
    args: {
        primary: true,
        label: "Button",
    },
    testplane: {
        "my test": async ({ browser, expect }) => {
            const element = await browser.$(".storybook-button");

            await expect(element).toHaveText("Button");
        },
    },
};

You can also specify extra options in story default config:

import type { WithTestplane } from "@testplane/storybook";
import type { Meta, StoryObj } from "@storybook/react";

const meta: WithTestplane<Meta<typeof Button>> = {
    title: "Example/Button",
    component: Button,
    testplaneConfig: {
        // If true, skips all Testplane tests from this story file
        skip: false,
        // Overrides default "autoScreenshots" value from plugin config
        autoScreenshots: true,
        // Overrides default "autoscreenshotSelector" value from plugin config
        autoscreenshotSelector: ".my-selector",
        // Extends default "autoScreenshotStorybookGlobals" value from plugin config
        autoScreenshotStorybookGlobals: { "dark theme": { theme: "dark" } },
        // Testplane browsers to run tests from this story file
        browserIds: ["chrome"],
        // Overrides default assertView options for tests from this file
        assertViewOpts: {
            ignoreDiffPixelCount: 5,
        },
    },
};

export default meta;

And then override these options for specific exports:

import type { StoryObj } from "@storybook/react";
import type { WithTestplane } from "@testplane/storybook";

export const Primary: WithTestplane<StoryObj> = {
    args: {
        primary: true,
        label: "Button",
    },
    testplaneConfig: {
        // Overrides testplaneConfig.skip from default export
        skip: true,
        // Extends testplaneConfig.assertViewOpts from default export
        assertViewOpts: {
            // "ignoreDiffPixelCount: 5" config value will be inherited from default export
            ignoreElements: [".some-selector"],
        },
        // Add extra globals set
        autoScreenshotStorybookGlobals: { "eng locale": { locale: "en" } },
    },
};

You can also disable specific sets for the whole story-file (in default export) and for the single story (in named export) by setting null value to the set:

import type { WithTestplane } from "@testplane/storybook";
import type { Meta, StoryObj } from "@storybook/react";

const meta: WithTestplane<Meta<typeof Button>> = {
    title: "Example/Button",
    component: Button,
    testplaneConfig: {
        autoScreenshotStorybookGlobals: { "dark theme": { theme: "dark" } },
    },
};

export default meta;

export const Primary: WithTestplane<StoryObj> = {
    // ...other Storybook properties
    testplaneConfig: {
        // Don't test this story in dark theme
        autoScreenshotStorybookGlobals: { "dark theme": null },
    },
};

Besides extending and disabling, you also can overwrite "autoScreenshotStorybookGlobals", providing the value as a function:

import type { StoryObj } from "@storybook/react";
import type { WithTestplane } from "@testplane/storybook";

export const Primary: WithTestplane<StoryObj> = {
    // ...other Storybook properties
    testplaneConfig: {
        // Replaces all global sets with this one
        autoScreenshotStorybookGlobals: () => ({ "eng locale": { locale: "en" } }),
    },
};

If you decide to create separate config for storybook auto-tests (which is suggested), you need to specify config path via CLI option. For example:

npx testplane --storybook -c .testplane.storybook.conf.ts

This allows you to store references next to your story files:

.testplane.conf.ts
import path from "path";
import { getStoryFile } from "@testplane/storybook";

export default {
    screenshotsDir: test => {
        const relativeStoryFilePath = getStoryFile(test);
        const relativeStoryFileDirPath = path.dirname(relativeStoryFilePath);

        return path.join(relativeStoryFileDirPath, "screens", test.id, test.browserId);
    },
    // other Testplane settings...
};

In this example, screenshot references would be stored in screens/<testId>/<browserId> folder, next to each of your story files.

@testplane/storybook

Overview​

Installation​

Setup​

Storybook​

Testplane​

Description of configuration parameters​

autoScreenshotStorybookGlobals​

Advanced usage​

Useful links​