Skip to main content

Getting started with Lambdatest's SmartUI Figma CLI

Welcome to the LambdaTest SmartUI Figma CLI documentation!

With SmartUI Figma CLI, you can seamlessly perform visual regression testing of your Figma designs on SmartUI using your command line, identifying Visual UI Regression bugs effortlessly. This guide will walk you through the process of running successful Figma Visual tests using SmartUI CLI.

Prerequisites for running SmartUI Figma CLI​

  • Basic understanding of Command Line Interface is required.
  • Basic understanding of Figma file structuring is required.
  • Login to LambdaTest SmartUI with your credentials.

The following steps will guide you in running your visual tests for Figma files on LambdaTest platform using SmartUI CLI.

Understanding Figma Tokens​

TokenWhere It’s UsedDescription
FIGMA_TOKENEnv VariableYour Figma Personal Access Token to authenticate with the Figma API
figma_file_tokendesigns.jsonFigma file ID, extracted from the Figma file URL
figma_idsdesigns.jsonList of frame or node IDs you want to compare visually

Example Figma URL: https://www.figma.com/file/abc12345/file-name?node-id=2417-58969

  • figma_file_token: abc12345
  • figma_ids: 2417-58969

Create a SmartUI CLI 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 CLI 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​

Step 1: Install the Dependencies​

Install required NPM modules for LambdaTest SmartUI CLI globally or in your project:

Global Installation (Recommended):

npm install -g @lambdatest/smartui-cli

Local Installation:

npm install @lambdatest/smartui-cli
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.

Step 2: Create the design info file​

smartui config:create-figma designs.json

Once, the designs file will be created, you will be seeing the sample pre-filled configuration in the designs.json file:

/smartui-cli-figma-project/designs.json
{
    "depth":2, //Figma Tree depth - (Optional), change the value according to the your file structure
    "figma_config": [
      {
        "figma_file_token": "<Required Figma File token>",
        "figma_ids":[
          "Id-1", "Id-2"
        ]
      },
       {
        "figma_file_token": "<Required Figma File token>",
        "figma_ids":[
          "Id-3", "Id-4"
        ]
      }
    ]
  }

Step 3: Configure your Project Token and Figma Token​

  1. Setup your project token shown in the SmartUI app after creating your project.
export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
  1. Setup your personal access token for Figma to authenticate Figma with SmartUI.
export FIGMA_TOKEN="123456#1234abcd-****-****-****-************"

Step 4: Configure your LambdaTest Credentials​

export LT_USERNAME="YOUR_USERNAME"
cmd

SmartUI CLI Design Config Options​

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

Config KeyDescriptionUsage
figma_file_tokenFile token for your required Figma file. You can use multiple figma files in the same configuration.Mandatory
figma_idsComma separated list of nodes that you care about in the document. If specified, only a subset of the document will be returned corresponding to the nodes listed, their children, and everything between the root node and the listed nodes.Optional
depth (int)Positive integer (>1) representing how deep into the document tree to traverse. For example, setting it to 2 returns Pages and all top level objects on each page. Not setting this parameter returns all nodesOptional

Step 5: Uploading the Figma files on SmartUI Cloud using CLI​

You can now execute tests for Visual Testing for Figma objects using the following options:.

npx smartui upload-figma designs.json

Advanced options for baseline management​

  1. markBaseline - You can mark a specific build as a baseline through the runner command
npx smartui upload-figma designs.json --markBaseline
  1. buildName - You can add your custom build name to a build by running the following command
npx smartui upload-figma designs.json --buildName "<Build_Name>"
You can use these options in a nested way as well, as shown below 
npx smartui upload-figma designs.json --buildName "<Build_Name>" --markBaseline
note

If buildName is not specified, a random build name is generated for every run.

You can add more screenshots in a build by specifying the particular build name in the runner command

Best Practices​

Build Names

   npx smartui upload-figma designs.json --buildName "v1.0.0"

Branch Names

Screenshot Naming for SDK Comparisons

Important: When comparing Figma designs with live implementations captured via SDKs, add .png extension to your SDK screenshot names.

Figma-uploaded screenshots automatically have .png appended (e.g., homepage.png), so your SDK screenshots must match:

In your SDK code:

// ❌ Wrong - will not match Figma screenshot
smartuiSnapshot(driver, "homepage");

// ✅ Correct - matches Figma screenshot name
smartuiSnapshot(driver, "homepage.png");

Example for different frameworks:

// Java
SmartUISnapshot.smartuiSnapshot(driver, "homepage.png");

This ensures that Figma screenshots (e.g., homepage.png) match SDK screenshots (e.g., homepage.png) in the same build.

Setup with Continuous Integration (CI)​

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

steps:
  - name: Running SmartUI Figma CLI Tests
    - run: |
       npm install @lambdatest/smartui-cli
       npx playwright install-deps
       npx smartui upload-figma designs.json

View SmartUI Results​

You can see the SmartUI dashboard to view the results. This will help you identify the Mismatches from the existing Baseline build and do the required visual testing.

cmd

Branch Names

Screenshot Naming for SDK Comparisons

Important: When comparing Figma designs with live implementations captured via SDKs, add .png extension to your SDK screenshot names.

Figma-uploaded screenshots automatically have .png appended (e.g., homepage.png), so your SDK screenshots must match:

In your SDK code:

// ❌ Wrong - will not match Figma screenshot
smartuiSnapshot(driver, "homepage");

// ✅ Correct - matches Figma screenshot name
smartuiSnapshot(driver, "homepage.png");

Example for different frameworks:

// Java
SmartUISnapshot.smartuiSnapshot(driver, "homepage.png");

This ensures that Figma screenshots (e.g., homepage.png) match SDK screenshots (e.g., homepage.png) in the same build.

Setup with Continuous Integration (CI)​

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

steps:
  - name: Running SmartUI Figma CLI Tests
    - run: |
       npm install @lambdatest/smartui-cli
       npx playwright install-deps
       npx smartui upload-figma designs.json

View SmartUI Results​

You can see the SmartUI dashboard to view the results. This will help you identify the Mismatches from the existing Baseline build and do the required visual testing.

cmd

Troubleshooting​

Verify Figma Token

   echo $FIGMA_TOKEN

Ensure the token is valid and has not expired. Generate a new token from Figma Settings.

Additional Resources​

Last updated on

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

Book Demo

Help and Support

Related Articles