SmartUI Plugin for Katalon Studio

The Katalon Studio SmartUI Plugin integrates Katalon Studio with LambdaTest SmartUI, enabling visual regression testing directly inside your test automation workflows.

With this plugin, you can:

• Capture screenshots at any point in your test flow
• Compare them with visual baselines
• Detect UI changes early in your CI/CD pipeline

---

Installation

Option 1: Install via Katalon Store (Recommended)

1. Open Katalon Store.
2. Search for “SmartUI” or browse under Plugins > Integrations.
3. Click Install to add the plugin to your Katalon Studio instance.

Option 2: Manual Installation via JAR

1. Download the latest katalon-studio-smartui-plugin.jar from the official release page.
2. In Katalon Studio, go to Project > Settings > Plugins > Import Plugin.
3. Select the downloaded .jar file and click Import.

---

Configuration & Usage

Step 1: Create a SmartUI Project

1. Go to SmartUI Projects Page.
2. Click New Project.
3. Select platform as CLI (for Katalon integration).
4. Enter project name, approvers, and tags (optional).
5. Click Submit and copy your Project Token from the dashboard.

Your Project Token will be used to authenticate screenshot uploads to SmartUI.

---

Step 2: Start your Katalon Instance from terminal

Run the following command in the terminal to start the Katalon instance.

/Applications/Katalon\ Studio\ Enterprise.app/Contents/MacOS/katalon

---

Step 3: Set Environment Variable

In your Katalon project, set the PROJECT_TOKEN environment variable:

Via Project Settings:

1. Go to Project > Settings > Plugins > SmartUI Integration.
2. Here you may set your project token

PROJECT_TOKEN = "project_token..."

---

Step 4: Configure SmartUI in Your Test Case

Use the provided custom keywords to start, capture, and stop SmartUI sessions.

Minimal Example:

// Start SmartUI Server
// Replace 'buildName' with your desired build name (optional)
CustomKeywords.'com.katalon.plugin.keyword.smartui.SmartKeywords.startServer'('My Katalon Build', '', '')

// Open Browser
WebUI.openBrowser('')
WebUI.navigateToUrl('https://lambdatest.com')

// Capture Snapshot with SmartUI
// The string parameter is the snapshot name (will appear in SmartUI Dashboard)
CustomKeywords.'com.katalon.plugin.keyword.smartui.SmartKeywords.takeSnapshot'('Homepage Snapshot')

// Stop SmartUI Server
CustomKeywords.'com.katalon.plugin.keyword.smartui.SmartKeywords.stopServer'()

// Close Browser
WebUI.closeBrowser()

---

Step 5: Advanced Configuration (Optional)

You can pass additional configuration via a JSON file or inline parameters.

Using a Config File (config.json):

{
  "deviceName": "Chrome Desktop",
  "platform": "Windows",
  "fullPage": true,
  "ignoreBoxes": {
    "xpath": [
      "//*[@class='dynamic-ad']",
      "//*[@id='timestamp']"
    ]
  }
}

Then use it in your test:

CustomKeywords.'com.katalon.plugin.keyword.smartui.SmartKeywords.startServer'('Build v1.0', 'config.json', '')

Use ignoreBoxes to exclude dynamic elements (ads, timestamps) from comparison.
Use selectBoxes to compare only specific regions (e.g., main content area).

---

Running Tests

1. Execute your test case as usual in Katalon Studio.
2. After test completion, visit your SmartUI Dashboard to:
   • View captured screenshots
   • Compare against baseline images
   • Approve or reject visual changes
   • Manage builds and baselines

---

Best Practices

• Always include startServer() before taking screenshots and stopServer() after.
• Use descriptive snapshot names for easy identification in SmartUI.
• For CI/CD pipelines, set PROJECT_TOKEN as an environment variable in your CI tool (Jenkins, GitHub Actions, etc.).
• Combine with Katalon’s built-in reporting for comprehensive test insights.

---

Troubleshooting

• “Project Token not found”: Ensure PROJECT_TOKEN is set in environment variables or passed explicitly.
• No screenshots uploaded: Verify network connectivity and that SmartUI server started successfully.
• Dynamic content causing false positives: Use ignoreBoxes or selectBoxes in config to stabilize comparisons.

---