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 TestMu AI's SmartUI Figma-Web CLI

Welcome to the TestMu AI SmartUI Figma Web CLI documentation!

With SmartUI Figma-Web CLI, you can seamlessly perform visual regression testing of your Figma designs on SmartUI using your command line, identifying discrepancies between your designs and live websites. This guide will walk you through the process of running successful Figma-Web 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 TestMu AI SmartUI with your credentials.
  • Ensure you are using @lambdatest/smartui-cli version 4.1.43 or higher
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 visual tests for Figma files on TestMu AI 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 TestMu AI SmartUI CLI globally or in your project:

Global Installation (Recommended):

Verified 
npm install -g @lambdatest/smartui-cli

Local Installation:

Verified 
npm install @lambdatest/smartui-cli

Step 2: Create the design configuration file​

Verified 
smartui config:create-figma-web designs.json

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

Verified
/smartui-cli-figma-project/designs.json
{
  "web": {
    "browsers": [
      "chrome",
      "firefox",
      "safari",
      "edge"
    ]
  },
  "figma": {
    "depth": 2, //Optional. Remove it to capture only figma_ids; each extra level adds more screenshots and Figma API calls
    "configs": [
      {
        "figma_file_token": "<token>",
        "figma_ids": [
          "id-1",
          "id-2"
        ],
        "screenshot_names": [
          "homepage",
          "about"
        ]
      },
      {
        "figma_file_token": "<token>",
        "figma_ids": [
          "id-3",
          "id-4"
        ],
        "screenshot_names": [
          "xyz",
          "abc"
        ]
      }
    ]
  }
}

Note: Unlike vanilla Figma CLI, designs.json includes browser parameters and auto-fetches viewports of Figma frames for efficient comparison.

Step 3: Configure your Project Token and Figma Token​

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

Step 4: Configure your TestMu AI Credentials​

Verified 
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)Optional. Leave it out to capture only the frames listed in figma_ids. If you set it above 1, every node down to that depth in the fetched tree also becomes a screenshot: 2 adds the top-level frames, and each extra level adds every child layer inside them. More screenshots means more Figma API requests; see Figma API usage and rate limits.Optional

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:.

Verified 
npx smartui upload-figma-web designs.json

Working example with actual web comparisons​

  1. Please clone the following sample GitHub repo (https://github.com/LambdaTest/smartui-figma-web-cli-sample).
Verified 
git clone https://github.com/LambdaTest/smartui-figma-web-cli-sample
  1. Install the node modules using the command:
Verified 
npm i
  1. Configure your project token and Figma token
  • Setup your project token shown in the SmartUI app after creating your project.
Verified 
export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"
Verified 
export FIGMA_TOKEN="123456#1234abcd-****-****-****-************"
  1. Create your figma baseline
Verified 
npx smartui upload-figma-web designs.json --buildName=FigmaBaseline2
  1. Execute your functional test script (Selenium Nodejs in this sample)
Verified 
npx smartui --config web-config.json exec --buildName=web-build -- node figma-web-local.js

Points to Consider

  • The browsers listed in the Figma configuration are used solely to enable comparisons between your designs and their corresponding live webpages.
  • Websites may exhibit browser-specific behaviors. To account for these variations, it is recommended to create distinct designs tailored for each browser, if necessary.

Best Practices​

Build Names

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

Figma API usage and rate limits​

Every upload calls the Figma REST API with your FIGMA_TOKEN, and Figma limits how many calls a token can make. When the limit is reached, Figma answers with HTTP 429 and SmartUI cannot fetch your frames.

Requests one upload makes​

For each entry in figma.configs, upload-figma-web makes:

Figma API callHow many
GET /v1/files/<file>2 (one to check the token and file before the build is created, one to read the frames)
GET /v1/images/<file>1 for every 10 frames it renders

For example, a configuration with two files and 25 frames in each makes 2 x (2 + 3) = 10 Figma API calls. The number of frames rendered is the figma_ids you list, plus every node that depth adds, so a large depth value on a big file multiplies the image calls.

What happens when Figma returns 429​

SmartUI does not wait and retry a rate-limited call, so the upload stops at the first 429. What you see depends on which call hit the limit:

  • While checking the token and file: the command fails with Figma's reason, for example Figma API rate limit reached for your token. Your file is on the 'starter' plan tier ... and your token's rate-limit bucket is 'low'.
  • While reading frames or rendering images: the build has already been created, so the task title still reads Web Figma images uploaded successfully to SmartUI, but the printed result is {"error": "Failed to process Web Figma Screenshots"} and the build has no Figma screenshots. Treat that output as a failed upload.

How to stay under the limit​

  • Leave depth out, and list only the frames you compare in figma_ids.
  • Wait before retrying. Figma's limits reset over minutes, not seconds, so an immediate re-run usually fails again.
  • Avoid re-running the Figma upload in every pipeline run when the designs have not changed.
  • Use a token that belongs to an Editor seat on a paid Figma plan. Figma puts tokens of View or Collab seats, and files on the free Starter plan, in its lowest rate-limit bucket.
  • Check Figma's own rate limit documentation for the current limits of your plan.

Troubleshooting​

Verified

Verify Figma Token

   echo $FIGMA_TOKEN

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

Additional Resources​

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
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
On this page