Skip to content

SmartUI Storybook: document tunnel-based rendering for Storybook URLs (TE-28456) #3575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
surishubham merged 2 commits into from
Sep 23, 2026
Merged

SmartUI Storybook: document tunnel-based rendering for Storybook URLs (TE-28456) #3575

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9ffd2ad
docs(smartui): Storybook URL builds render through a tunnel (TE-28456)
Sep 22, 2026
360ef02
docs(smartui): URL-mode details from the backend PRs (TE-28456)
Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 86 additions & 1 deletion docs/smartui-storybook-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,49 @@ set 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 <BrandName /> 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 <BrandName /> tunnel so that SmartUI can load your stories. The tunnel needs your <BrandName /> username and access key. You can skip this step if you only run tests on a `storybook-static` directory.

<Tabs className='docs__val' groupId='language'>
<TabItem value='MacOS/Linux' label='MacOS/Linux' default>

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`export LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}"
export LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}
</CodeBlock>
</div>

</TabItem>
<TabItem value='Windows' label='Windows (CMD)'>

<div className="lambdatest__codeblock">
<CodeBlock className="language-bash">
{`set LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}"
set LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}
</CodeBlock>
</div>

</TabItem>
<TabItem value='PowerShell' label='PowerShell'>

<div className="lambdatest__codeblock">
<CodeBlock className="language-powershell">
{`$env:LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}"
$env:LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`}
</CodeBlock>
</div>

</TabItem>
</Tabs>

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:
Expand Down Expand Up @@ -601,6 +644,7 @@ Please read the following table for more information about the configuration fil
| exclude | Don't compare the stories which should be excluded in SmartUI tests <br/> Ex: `"/login/","/marketing/"` | Optional |
| backgroundTheme | Theme for capturing stories. Options: `"light"`, `"dark"`, or `"both"` (captures both themes) <br/> Ex: `"light"` | Optional (default: `"light"`) |
| useGlobals | Enable Storybook global decorators and parameters (required for theme switching) <br/> Ex: `true` | Optional (default: `false`) |
| chunkSize | Number 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`. <br/> Ex: `50` | Optional (default: `50` for a Storybook URL, `100` for a static build) |

:::note
SmartUI Storybook testing now supports `Edge` browser.
Expand Down Expand Up @@ -689,6 +733,14 @@ The `waitForTimeout` setting at the story level takes precedence over the global
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.
:::

:::caution Storybook URL builds
When you pass a Storybook URL (CLI version `1.2.0` and later), a custom viewport's `waitForTimeout` works differently:

- It applies only to entries that also set `styles`, and it applies to every story captured at that viewport size.
- An entry with only `stories` and `waitForTimeout` (no `styles`) is ignored. Use the global `waitForTimeout` instead.
- If two entries use the same width and height, the longer wait is used.
:::

### **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:.
Expand All @@ -715,12 +767,21 @@ smartui storybook ./storybook-static --config .smartui.json // Captures al
<TabItem value='public-hosted' label='For Public Hosted URL'>

```bash
smartui storybook https://<your_public_hosted_url> --config .smartui.json // Captures all the stories running on local server
smartui storybook https://<your_public_hosted_url> --config .smartui.json // Captures all the stories running on the hosted URL
```

</TabItem>
</Tabs>

:::info 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 <BrandName /> 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.
:::

:::note 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:
Expand Down Expand Up @@ -750,6 +811,10 @@ steps:
npm i
npm install @lambdatest/smartui-storybook -g
smartui storybook https://<replace_with_your_url> --config .smartui.json
env:
PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}
LT_USERNAME: ${{ secrets.LT_USERNAME }}
LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }}
```

</TabItem>
Expand All @@ -765,6 +830,10 @@ The following are supported `CLI (Command Line Interface)` options for Visual Re
| ------------ | ----------------------------------------------------------------------------------- | -------- |
| --config | This is the reference configuration file containing the SmartUI Cloud Configuration | Optional |
| --help | This will print all help information for the SmartUI CLI options | Optional |
| --buildName | Name of the SmartUI build, for example your pipeline or branch name | Optional |
| --force-rebuild | Rebuild a build that already exists with the same name | Optional |
| --userName | Your <BrandName /> username, used to start the tunnel for a Storybook URL. Defaults to `LT_USERNAME` | Required for a Storybook URL, unless `LT_USERNAME` is set |
| --accessKey | Your <BrandName /> access key, used to start the tunnel for a Storybook URL. Defaults to `LT_ACCESS_KEY` | Required for a Storybook URL, unless `LT_ACCESS_KEY` is set |

### **Step 6:** View SmartUI Results

Expand All @@ -787,6 +856,22 @@ Verify Storybook Server

>**Note**: `buildStoriesJson` is available for Storybook versions below v9.

</TabItem>
<TabItem value='storybook-url-builds' label='Storybook URL Builds' >

Storybook URL Builds

These apply to CLI version `1.2.0` and later, when you pass a Storybook URL.

| Message | What to do |
| ------- | ---------- |
| `MISSING_LT_CREDENTIALS` | Set `LT_USERNAME` and `LT_ACCESS_KEY`, or pass `--userName` and `--accessKey`. |
| `tunnel not found; the storybook URL cannot be reached without a running tunnel` | SmartUI could not find the tunnel the CLI started. The CLI tries 3 times before it fails. Check that nothing on your network stops the tunnel, then run again. |
| `LambdaTest tunnel did not start` | Check that the username and access key are correct, and that the machine running the CLI can reach `*.lambdatest.com`. |
| `Storybook did not serve index.json or stories.json` | Make sure the Storybook is running at that URL. For Storybook 6.x, enable `buildStoriesJson` in `.storybook/main.js`. |
| `gave up waiting for the build after ... minutes` | The build ran for more than two hours. Lower `chunkSize` or reduce the number of browsers and viewports, then run again. |
| Stories time out on the first render | SmartUI waits up to 60 seconds for each story page through the tunnel and retries once. Your dev server may still be compiling: open the Storybook once in a browser, then run the command again. |

</TabItem>
<TabItem value='check-story-inclusion-exclusion' label='Check Story Inclusion/Exclusion' >

Expand Down
Loading