How to Use the SmartUI Agent Skill to Run Visual Tests

What Is the SmartUI Agent Skill?

An agent skill is a folder of verified instructions and code patterns that an AI coding agent reads before it generates anything, so it produces the correct SmartUI CLI command and config on the first attempt rather than an outdated pattern scraped from a two-year-old blog post. The agent-skills repository packages this per framework and testing discipline, and smartui-skill is the one for visual regression.

SmartUI itself is TestMu AI's visual regression testing product: it captures screenshots through a CLI or an SDK call inside your existing suite, compares them against an approved baseline, and applies an AI engine to filter out anti-aliasing and rendering noise before a reviewer sees the diff. The skill is the fast path to wiring that up correctly from your terminal.

Prerequisites

• Node.js and npm, for the SmartUI CLI and the skill installer.
• An AI coding agent - Claude Code, Cursor, GitHub Copilot, or Gemini CLI all read the same skill format.
• A TestMu AI account with a SmartUI project token from the SmartUI dashboard, plus a username and access key if you also plan to run on the Selenium cloud grid.
• An existing Playwright, Selenium, or Cypress suite, since the skill adds visual coverage to tests you already run rather than generating a suite from nothing.

Installing the Skill

git clone https://github.com/LambdaTest/agent-skills && cd agent-skills
npx agentskillsforall add https://github.com/LambdaTest/agent-skills.git --skill smartui-skill

Set your SmartUI project token, generated from the SmartUI dashboard, as an environment variable so the CLI can authenticate:

export PROJECT_TOKEN="your-smartui-project-token"

# Only needed if you also run Selenium against the cloud grid:
export LT_USERNAME="your-username"
export LT_ACCESS_KEY="your-access-key"

Configuring Your First Project

Ask your agent to scaffold a config for your target browsers and breakpoints, or generate one directly:

npx smartui config:create smartui.config.json

A config that covers desktop and mobile in one run looks like this:

{
  "web": {
    "browsers": ["chrome", "firefox", "safari"],
    "viewports": [[1920, 1080], [1366, 768], [375, 812]]
  },
  "waitForPageRender": 2000,
  "waitForTimeout": 5000
}

Commit this file to source control. Pinning the browser and viewport list here, instead of leaving it to whatever ran locally, is what keeps two developers' runs comparable against the same baseline.

Running a Visual Test

Tell the agent what to cover in plain language, for example: "Add a SmartUI visual test for the homepage and login page, waiting for network idle before each screenshot." It should produce something close to the patterns below, one per framework.

const { chromium } = require('playwright');
const { smartuiSnapshot } = require('@lambdatest/smartui-cli');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto('https://www.testmuai.com/selenium-playground/');
  await page.waitForLoadState('networkidle');
  await smartuiSnapshot(page, 'Selenium Playground Home');

  await browser.close();
})();

npx smartui --config smartui.config.json exec -- npx playwright test

Map<String, Object> ltOptions = new HashMap<>();
ltOptions.put("user", System.getenv("LT_USERNAME"));
ltOptions.put("accessKey", System.getenv("LT_ACCESS_KEY"));
ltOptions.put("build", "smartui-selenium");
ltOptions.put("smartUI.project", "My SmartUI Project");

ChromeOptions options = new ChromeOptions();
options.setCapability("LT:Options", ltOptions);

WebDriver driver = new RemoteWebDriver(new URL("https://hub.lambdatest.com/wd/hub"), options);
driver.get("https://www.testmuai.com/selenium-playground/");
((JavascriptExecutor) driver).executeScript("smartui.takeScreenshot=selenium-playground-home");

[
  { "name": "Homepage", "url": "https://example.com/", "waitForTimeout": 3000 },
  { "name": "Pricing", "url": "https://example.com/pricing", "waitForTimeout": 2000 }
]

npx smartui --config smartui.config.json capture urls.json --buildName "release-v2.1"

Reviewing Results on the Dashboard

The first run against a project has no baseline, so every screenshot captured becomes the baseline automatically. Every run after that produces a diff, and results land in the SmartUI dashboard for review, not in your terminal.

• Open the build in the SmartUI dashboard and inspect each flagged screenshot side by side against its baseline.
• Approve intentional changes - the new screenshot becomes the baseline for that screen going forward.
• Reject regressions - the old baseline is kept and the change is treated as a bug.
• When a global change like a brand color or font update affects many screens at once, use bulk approval instead of clicking through each one individually.

If a build never shows up in the dashboard at all, the most common cause is a missing environment variable - verify PROJECT_TOKEN, or LT_USERNAME and LT_ACCESS_KEY for the Selenium path, are actually exported in the shell that ran the tests.

Handling False Positives

A visual suite that flags the same three widgets on every run trains a team to stop reading the report within two sprints. Fix the sources of noise before you scale up coverage, not after.

• Timestamps, live counters, and rotating banners - hide them with a DOM script before the screenshot call, or exclude them with ignoreDOM regions in the config.
• Cookie and consent banners - remove them from the DOM entirely before capturing, since their presence is inconsistent run to run.
• Anti-aliasing and font sub-pixel differences - raise the comparison threshold slightly, for example to 0.1, rather than treating every 1px edge difference as a regression.
• Lazy-loaded images shifting layout - wait for networkidle and add an explicit wait on the element you are about to screenshot, not just a fixed timeout.

Common Problems and Fixes

Best Practices

• Name screenshots by what they show, such as login-validation-error, not screenshot-1, so a failing build is readable without opening every diff.
• Run on every pull request rather than nightly only, so a regression is caught before merge instead of after several commits have piled on top of it.
• Screenshot components in isolation through Storybook visual testing in addition to full pages, so a shared-component regression is caught from one story instead of every page that uses it.
• Review and approve baselines deliberately - do not let a bad screenshot become the new reference simply because nobody looked at the first run.

Conclusion

Install the skill, generate a config pinned to the browsers and breakpoints you actually support, and run one page you suspect changes often before scaling to the full suite. The first run sets your baseline; every run after that is only as trustworthy as how well you have masked the dynamic content that would otherwise flag noise as a regression.

For the full debugging table and CI/CD templates for GitHub Actions, see the smartui-skill playbook, or read the visual regression testing guide to see how SmartUI's AI engine classifies and scores each detected change beyond the raw diff.