For AI agents and LLMs: a machine-readable index is available at llms.txt. A plain-Markdown version of any documentation page is available by appending .md to its URL.
Skip to main content

Getting started with SmartUI using Storybook On TestMu AI

Using the TestMu AI 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 TestMu AI 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

module.exports = {
  features: {
    // Required for Storybook < v9
    buildStoriesJson: true,
  },
};

Note: buildStoriesJson is available for Storybook versions below v9.

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 3.1: Configure Proxy (Optional)​

If you are behind a proxy, you can configure the SMARTUI_API_PROXY environment variable.

export SMARTUI_API_PROXY=http://172.17.0.1:3128

Note: Replace the IP address and port with the appropriate values for your environment.

Step 3.2: Configure your TestMu AI Credentials (Storybook URL only)​

When you pass a Storybook URL to the CLI (a local dev server or a hosted Storybook), the CLI starts a TestMu AI tunnel so that SmartUI can load your stories. The tunnel needs your TestMu AI username and access key. You can skip this step if you only run tests on a storybook-static directory.

export LT_USERNAME="undefined"
export LT_ACCESS_KEY="undefined"

You can also pass them on the command line with --userName and --accessKey. Command-line values take precedence over the environment variables.

note

Tunnel-based rendering of Storybook URLs is available from @lambdatest/smartui-storybook version 1.2.0. Run npm install @lambdatest/smartui-storybook@latest -g to upgrade.

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)
chunkSizeNumber of stories SmartUI renders together in one batch. For a Storybook URL, values below 25 are raised to 25 and values above 100 are lowered to 100. Lower it if you configure many browsers and viewports, because each batch renders every browser and viewport combination. If the stories left over at the end are no more than half of chunkSize, they join the last batch, so that batch can be up to 1.5 times chunkSize.
Ex: 50		Optional (default: 50 for a Storybook URL, 100 for a static build)
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
How a Storybook URL is rendered

From CLI version 1.2.0, when you pass a Storybook URL the CLI reads the story list from the URL, then starts a TestMu AI tunnel and SmartUI renders the stories through it. This means:

  • The URL can be on localhost or on your internal network. It can be a dev server started with npm run storybook (webpack or Vite builder) or a hosted Storybook.
  • The CLI needs your LT_USERNAME and LT_ACCESS_KEY, as described in Step 3.2 above. The tunnel block in .smartui.json is ignored for a Storybook URL, because the CLI starts its own tunnel.
  • Keep the CLI running until it reports the build result. The tunnel stays open until the build finishes or fails. If the build is still running after two hours, the CLI closes the tunnel and exits with a non-zero code.
  • If your dev server is still compiling, open the Storybook once in a browser before you run the command, so that the first render does not time out.
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
      npm install @lambdatest/smartui-storybook -g
      npm run build-storybook
      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
--buildNameName of the SmartUI build, for example your pipeline or branch nameOptional
--force-rebuildRebuild a build that already exists with the same nameOptional
--userNameYour TestMu AI username, used to start the tunnel for a Storybook URL. Defaults to LT_USERNAMERequired for a Storybook URL, unless LT_USERNAME is set
--accessKeyYour TestMu AI access key, used to start the tunnel for a Storybook URL. Defaults to LT_ACCESS_KEYRequired for a Storybook URL, unless LT_ACCESS_KEY is set

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

Note: buildStoriesJson is available for Storybook versions below v9.

Additional Resources​

Last updated on

Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

×
Schedule Your Personal Demo
Kane CLI terminal

Help and Support

Related Articles