Skip to main content

Getting started with SmartUI using Storybook On LambdaTest

Using the LambdaTest platform, perform regression testing in just one click and find Visual UI Regression bugs easily with the help of Smart Testing. This documentation will act as your step-by-step guide in performing successful Visual Regression tests.

Prerequisites for running SmartUI with StoryBook​

  • Basic understanding of StoryBook is required.
  • Node.js v20.3+ installed (required for SmartUI CLI v4.x.x)
  • StoryBook version installed should be higher than 6.4.0. Click here to know more
note

If you face any problems executing tests with SmartUI-CLI versions >= v4.x.x, upgrade your Node.js version to v20.3 or above.

The following steps will guide you in running your first Visual Regression test on LambdaTest platform -

Steps to create a SmartUI Project​

The first step is to create a project with the application in which we will combine all your builds run on the project. To create a SmartUI Project, follow these steps:

  1. Go to Projects page
  2. Click on the new project button
  3. Select the platform as CLI for executing your StoryBook tests.
  4. Add name of the project, approvers for the changes found, tags for any filter or easy navigation.
  5. Click on the Submit.

Steps to run your first test​

Github Sample

Please try our StoryBook SmartUI Github sample repository for trying an example.

git clone https://github.com/LambdaTest/smartui-storybook-sample.git

Step 1: Install the Dependencies​

Install required NPM modules for LambdaTest SmartUI StoryBook CLI in your Frontend project.

npm install @lambdatest/smartui-storybook -g

Step 2: Setup with StoryBook​

Add the following to your .storybook/main.js. You can read more about this here Storybook Feature flags

.storybook/main.js
module.exports = {
  features: {
    buildStoriesJson: true,
  },
};

Storybook v9+ Play Function Support​

SmartUI supports Storybook's play function (available in Storybook v9+) for interactive component testing. The play function allows you to interact with components before capturing screenshots.

Example with Play Function:

Button.stories.js

export default {
  title: 'Components/Button',
  component: Button,
};

export const InteractiveButton = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button', { name: /click me/i });

    // Interact with the button before screenshot
    await userEvent.click(button);
    await expect(button).toHaveTextContent('Clicked!');
  },
};

Best Practices for Play Functions:

  • Use play functions to set up component states before screenshots
  • Wait for async operations to complete using waitFor or findBy queries
  • Avoid animations or transitions that might cause timing issues
  • Use waitForTimeout in SmartUI config if components need additional render time after play functions

Storybook Globals (Themes) Configuration​

SmartUI supports Storybook's global decorators and parameters, including theme switching. You can configure themes in your .smartui.json file.

Configuration Example:

.smartui.json
{
  "storybook": {
    "browsers": ["chrome", "firefox", "safari", "edge"],
    "viewports": [[1920, 1080]],
    "backgroundTheme": "light",  // Options: "light", "dark", or "both"
    "useGlobals": true,  // Enable global decorators and parameters
    "waitForTimeout": 0
  }
}

Theme Options:

  • "light": Capture stories in light theme only
  • "dark": Capture stories in dark theme only
  • "both": Capture stories in both light and dark themes (creates separate screenshots)

Example Story with Theme Globals:

Card.stories.js
export default {
  title: 'Components/Card',
  component: Card,
  parameters: {
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#1a1a1a' },
      ],
    },
  },
  globalTypes: {
    theme: {
      description: 'Global theme for components',
      defaultValue: 'light',
      toolbar: {
        title: 'Theme',
        icon: 'circlehollow',
        items: ['light', 'dark'],
        dynamicTitle: true,
      },
    },
  },
};

export const Default = {
  decorators: [
    (Story, context) => {
      const theme = context.globals.theme || 'light';
      return (
        <div className={`theme-${theme}`}>
          <Story />
        </div>
      );
    },
  ],
};

Using Multiple Themes:

If you set "backgroundTheme": "both" in your SmartUI config, each story will be captured twice - once in light theme and once in dark theme. The screenshot names will be automatically suffixed (e.g., Card-Default-light.png and Card-Default-dark.png).

Note: When using "backgroundTheme": "both", ensure your Storybook stories properly handle theme switching via globals or decorators.

Step 3: Configure your Project Token​

Setup your project token shown in the SmartUI app after creating your project.

export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
cmd

Step 4: Create and Configure SmartUI Config​

You can now configure your project settings on using various available options to run your tests with the SmartUI integration. To generate the configuration file, please execute the following command:

smartui config create .smartui.json

Once, the configuration file will be created, you will be seeing the default configuration pre-filled in the configuration file:

/smartUi-storybook-project/smartui.json
{
  "storybook": {
    "browsers": [
      "chrome",
      "firefox",
      "safari",
      "edge",
      // Add more browser configuration here
    ],
    "viewports": [
      [1920, 1080]        // Add more view ports to capture here
    ],
    "waitForTimeout": 0, // (Optional) Add wait time for the page to load
    "include": [],       // (Optional) Only compare limited stories
    "exclude": []        // (Optional) Don't compare the stories // Apply exclusions/inclusions at directory, sub-directory, or individual story level
  }
}

SmartUI StoryBook Config Options​

Please read the following table for more information about the configuration file:

Config KeyDescriptionUsage
browsersYou can add all the supported browsers brands here to run your tests for SmartUI.
Ex: "chrome", "firefox", "safari", "edge", etc..		Mandatory
viewportsYou can add all the supported browser viewpoints here to run your tests for SmartUI
Ex: [1920, 1080],[width, height] etc..
Mandatory
waitForTimeoutYou can add wait time for the page to load DOM of your StoryBook components. This can be added globally to your configuration and to individual stories as well.
Ex: 3000		Optional
includeAdd the stories which should only be included in SmartUI tests
Ex: "/dashboard/","/features/"		Optional
excludeDon't compare the stories which should be excluded in SmartUI tests
Ex: "/login/","/marketing/"		Optional
backgroundThemeTheme for capturing stories. Options: "light", "dark", or "both" (captures both themes)
Ex: "light"		Optional (default: "light")
useGlobalsEnable Storybook global decorators and parameters (required for theme switching)
Ex: true		Optional (default: false)
note

SmartUI Storybook testing now supports Edge browser.

info

For capturing the stories in full page without limiting the height to the viewport then in the viewports array, you can change the following configuration:

"viewports": [
  [1920],  // Only mention the width of the viewport
  [1440]
]

Custom Viewport Configuration New​

To facilitate the visualization of your UI components on various device screens, you can now setup custom viewport configurations. This feature is an extension of Storybook's existing Viewport toolbar item, enabling you to capture and view stories in different dimensions, such as mobile or tablet, with specific orientations like portrait or landscape.

To configure custom viewports for your stories, you can update the .smartui.json file within your project repository.

{
...
...
"customViewports": [
      {
        "stories": [
          "<name of the stories/components>"
        ],
      {
        "styles": {
            "width": 322,
            "height": 321
          },
        "exclude": [ // Example: Excluding stories for a specific viewport
          "/directory1",
          "/directory2/subdirectory1",
          "/directory2/subdirectory2",
          "/directory3/subdirectory3/item1",
        ]
      },
      },
      {
        "stories": [
          "<name of the stories/components>"
        ],
        "styles": {
          "width": 834, //Tablet view
          "height": 1112
        },
        "waitForTimeout": 4000 //Story-level waitForTimeout (Applied to all the combinations of the mentioned stories)
      }
      {
        "stories": [
          "<name of the stories/components>"
        ],
        "waitForTimeout": 3000 //Story-level waitForTimeout (Applied to all the combinations of the mentioned stories)
        }
      }
      // Additional custom viewport configurations can be added here
]
...
...
}
info

The waitForTimeout setting at the story level takes precedence over the global waitForTimeout configuration and only applies to the specific stories to which it is assigned.

For instance, if Story-1 has a story-level waitForTimeout value (T1) set within custom viewport settings, and there exists a global waitForTimeout value (T2) defined in the configuration, all browser and viewport combinations of Story-1 will render with T1. Conversely, all other stories will be rendered with T2 across all combinations.

Step 5: Execute the Tests on SmartUI Cloud using CLI​

You can now execute your StoryBook components for Visual Regression Testing using the following options:.

npm run storybook                                                 // Starts your local StoryBook server
smartui storybook http://localhost:6006 --config .smartui.json    // Captures all the stories running on local server
For Continuous Integration (CI)

If you are using the Continuous Integration (CI) pipeline for your application and want to integrate SmartUI StoryBook execution then the following are the steps needs to be added to your .yaml file:

steps:
  - name: Running SmartUI StoryBook Tests
    - run: npm i
    - run: npm install @lambdatest/smartui-storybook -g
    - run: npm run build-storybook
    - run: smartui storybook ./storybook-static --config .smartui.json

CLI Options and Keys​

The following are supported CLI (Command Line Interface) options for Visual Regression Testing with SmartUI:

CLI Flag KeyDescriptionUsage
--configThis is the reference configuration file containing the SmartUI Cloud ConfigurationOptional
--helpThis will print all help information for the SmartUI CLI optionsOptional

Step 6: View SmartUI Results​

You can now see the SmartUI dashboard to view the results. Can also identify the mis-matches from the existing Baseline build.

cmd

Troubleshooting​

Verify Storybook Server

  • Ensure Storybook is running on the specified URL/port
    • Check that buildStoriesJson: true is set in .storybook/main.js

Additional Resources​

Last updated on

Test across 3000+ combinations of browsers, real devices & OS.

Book Demo

Help and Support

Related Articles