diff --git a/docs/smartui-storybook-integration.md b/docs/smartui-storybook-integration.md index 1c6188287..bddc0fab6 100644 --- a/docs/smartui-storybook-integration.md +++ b/docs/smartui-storybook-integration.md @@ -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 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 tunnel so that SmartUI can load your stories. The tunnel needs your username and access key. You can skip this step if you only run tests on a `storybook-static` directory. + + + + +
+ + {`export LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +export LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`} + +
+ + + + +
+ + {`set LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +set LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`} + +
+ + + + +
+ + {`$env:LT_USERNAME="${ YOUR_LAMBDATEST_USERNAME()}" +$env:LT_ACCESS_KEY="${ YOUR_LAMBDATEST_ACCESS_KEY()}"`} + +
+ + + + +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: @@ -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
Ex: `"/login/","/marketing/"` | Optional | | backgroundTheme | Theme for capturing stories. Options: `"light"`, `"dark"`, or `"both"` (captures both themes)
Ex: `"light"` | Optional (default: `"light"`) | | useGlobals | Enable Storybook global decorators and parameters (required for theme switching)
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`.
Ex: `50` | Optional (default: `50` for a Storybook URL, `100` for a static build) | :::note SmartUI Storybook testing now supports `Edge` browser. @@ -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:. @@ -715,12 +767,21 @@ smartui storybook ./storybook-static --config .smartui.json // Captures al ```bash -smartui storybook https:// --config .smartui.json // Captures all the stories running on local server +smartui storybook https:// --config .smartui.json // Captures all the stories running on the hosted URL ``` +:::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 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: @@ -750,6 +811,10 @@ steps: npm i npm install @lambdatest/smartui-storybook -g smartui storybook https:// --config .smartui.json + env: + PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }} + LT_USERNAME: ${{ secrets.LT_USERNAME }} + LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }} ``` @@ -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 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 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 @@ -787,6 +856,22 @@ Verify Storybook Server >**Note**: `buildStoriesJson` is available for Storybook versions below v9. + + + +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. | +