diff --git a/docs/smartui-cli-build-name.md b/docs/smartui-cli-build-name.md new file mode 100644 index 000000000..33e5f4ec2 --- /dev/null +++ b/docs/smartui-cli-build-name.md @@ -0,0 +1,160 @@ +--- +id: smartui-sdk-build-name +title: Grouping Screenshots through Build Names +sidebar_label: Fetch Results +description: In this documentation, learn how to group screenshots in a single build across multiple executions. + - Visual Regression + - Visual Regression Testing Guide + - Visual Regression Test Automation + - Visual Regression Automation Testing + - Running Visual Regression Tests + - Visual Regression Testing Online + - Run Visual Regression + - Visual Regression Run Specific Test + - Visual Regression Testing Environment + - How to Run Visual Regression Tests + +url: https://www.lambdatest.com/support/docs/smartui-cli/ +slug: smartui-cli-build-name/ +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import NewTag from '../src/component/newTag'; + +--- + + + +SmartUI CLI allows you to group screenshots in a build name and append new screenshots to an existing build. This feature enables you to assign build names, add screenshots to existing builds and manage your visual tests efficiently. + + +## Prerequisites + +- Basic understanding of Command Line Interface +- Login to [LambdaTest SmartUI](https://smartui.lambdatest.com/) with your credentials. +- Ensure you are using `@lambdatest/smartui-cli` version 4.0.14 or higher. +- A properly configured SmartUI CLI project + +## Steps to Use + +### **Step 1:** Install SmartUI CLI + +If you haven't already installed SmartUI CLI, install it using npm: + +```bash +npm i @lambdatest/smartui-cli +``` + +### **Step 2:** Configure your Project Token + +Setup your project token show in the **SmartUI** app after, creating your project. + + + + +```bash +export PROJECT_TOKEN="123456#1234abcd-****-****-****-************" +``` + + + + +```bash +set PROJECT_TOKEN="123456#1234abcd-****-****-****-************" +``` + + + + +```bash +$Env:PROJECT_TOKEN="123456#1234abcd-****-****-****-************" +``` + + + +### **Step 3:** Execute Tests with custom Build Names + +You can add a custom build name by adding the `--buildName` flag to your test execution command. Here are different ways to use this feature: + +#### Custom Build Name (Expected Usage) +Specify a custom build name to group your screenshots in the following way: + +```bash +npx smartui --config .smartui.json exec --buildName "Sample Build Name" -- +``` +>**Example:** + For a `Node.js` test script : +>```bash +>npx smartui --config .smartui.json exec --buildName "Sample Build Name" -- node test.js +>``` + +#### Default Usage +If no buildname is specified, a random build name is added to the builds: + +```bash +npx smartui --config .smartui.json exec -- +``` + +### **Step 4:** Advanced Use Case + +If you are running multiple test cases in a single job (e.g., using HyperExecute) and want to club all screenshots under a single build while maintaining consistent Git baseline management, you can do the following: + +This can be done as follows: + +```bash +npx smartui --config .smartui.json exec --buildName $env:JOB_ID -- node test.js +``` +##### This approach ensures: + +- A new build is created for every HyperExecute job. +- Screenshots from all tests in the same job are appended to the same build. +- Git branching strategies remain unaffected, improving baseline management across branches. + + +>## Key Benefits +>1. Efficient grouping of screenshots by build names. +>2. Seamless integration with Git baseline management. +>3. Flexibility to append screenshots to existing builds. +>4. Optimized workflows for parallel and single-job executions. + + + diff --git a/docs/smartui-cli-upload.md b/docs/smartui-cli-upload.md index 7a499f40d..c29f3ccdb 100644 --- a/docs/smartui-cli-upload.md +++ b/docs/smartui-cli-upload.md @@ -182,6 +182,19 @@ Specify a custom filename for your results: ```bash npx smartui upload --fetch-results custom-results.json ``` +### Adding a custom build name +You can add a custom build name by adding the `--buildName` flag to your test execution command. Here is how you can utilise this feature: + +Specify a custom build name to group your screenshots in the following way: + +```bash +npx smartui upload --buildName "Sample Build Name" +``` + +> Note: +> - If no build name is provided, a random name will be automatically assigned to the build. +> - Specifying the name of an existing build within the project will append the screenshots to that build. +> - Existing screenshots with the same name and configuration in the build will be overwritten during a re-run. cmd diff --git a/docs/smartui-cli.md b/docs/smartui-cli.md index b1978c777..4d2d9c208 100644 --- a/docs/smartui-cli.md +++ b/docs/smartui-cli.md @@ -238,6 +238,22 @@ Specify a custom filename for your results: ```bash npx smartui capture urls.json --config .smartui.json --fetch-results custom-results.json ``` + +### Adding a custom build name +You can add a custom build name by adding the `--buildName` flag to your test execution command. Here is how you can utilise this feature: + +Specify a custom build name to group your screenshots in the following way: + +```bash +npx smartui capture urls.json --buildName "Sample Build Name" --config .smartui.json +``` + +> Note: +> - If no build name is provided, a random name will be automatically assigned to the build. +> - Specifying the name of an existing build within the project will append the screenshots to that build. +> - Existing screenshots with the same name and configuration in the build will be overwritten during a re-run. + + ### Setup with Continuous Integration (CI) If you are using the Continuous Integration (CI) pipeline for your application and want to integrate `SmartUI CLI` execution then the following are the steps needs to be added to your `.yaml` file: