Skip to main content

SmartUI Capture Onboarding with HyperExecute

This comprehensive guide will walk you through setting up and running SmartUI Capture tests on HyperExecute. SmartUI Capture allows you to perform visual regression testing by capturing screenshots of static URLs across multiple browsers and devices, all orchestrated through HyperExecute's powerful test execution platform.

Prerequisites​

Before you begin, ensure you have the following:

  • Node.js v20.3 or higher (required for SmartUI CLI v4.x.x)
  • npm or yarn package manager
  • TestMu AI account with active subscription
  • HyperExecute CLI installed (Download Guide)
  • Basic understanding of:
    • Command Line Interface (CLI)
    • YAML configuration files
    • JSON file structure
    • Visual regression testing concepts
Node.js Version Requirement

If you face any problems executing tests with SmartUI-CLI versions >= v4.x.x, upgrade your Node.js version to v20.3 or above.

Overview​

SmartUI Capture on HyperExecute combines the power of:

  • SmartUI CLI Capture: Captures screenshots of static URLs across browsers and devices
  • HyperExecute: Orchestrates and executes tests at scale with parallel execution
  • Visual Regression Testing: Compares screenshots to detect UI changes

This integration is ideal for:

  • Testing production and staging environments
  • Monitoring website visual consistency
  • Detecting UI regressions across multiple pages
  • Running large-scale visual tests in parallel

Step 1: Create a SmartUI Project​

The first step is to create a SmartUI project in the dashboard. This project will contain all your builds and visual comparisons.

  1. Go to SmartUI Projects page
  2. Click on the New Project button
  3. Select the platform as CLI for executing your capture tests
  4. Add the following details:
    • Project Name: A descriptive name (e.g., "Example Company Visual Tests")
    • Approvers: Team members who can approve visual changes
    • Tags: Optional tags for filtering and organization
  5. Click on Submit or Continue
Project Token

After creating the project, you will receive a PROJECT_TOKEN. Save this token securely as you'll need it in the next steps. The token format looks like: 123456#1234abcd-****-****-****-************

Step 2: Set Up Your Project Structure​

Create a new directory for your SmartUI Capture project or use an existing one. Here's the recommended structure:

smartui-capture-project/
├── config.json              # SmartUI configuration
├── urlTest.json             # Test environment URLs
├── urlProd.json             # Production environment URLs
├── test/                    # Optional: Split test URLs
│   ├── urls_test_1.json
│   ├── urls_test_2.json
│   └── ...
├── prod/                    # Optional: Split production URLs
│   ├── urls_prod_1.json
│   ├── urls_prod_2.json
│   └── ...
├── hyperexecute.yaml        # HyperExecute configuration
└── package.json             # Node.js dependencies

Initialize Your Project​

If you're starting fresh, initialize a new Node.js project:

mkdir smartui-capture-project
cd smartui-capture-project
npm init -y

Step 3: Install Dependencies​

Install the required SmartUI CLI package. You can install it globally or locally in your project.

npm install -g @lambdatest/smartui-cli@4.1.54-beta.0

Local Installation​

npm install @lambdatest/smartui-cli@4.1.54-beta.0
Sample Repository

You can also clone the sample repository to get started quickly:

git clone https://github.com/LambdaTest/smartui-playwright-sample
cd smartui-playwright-sample
Image View on GitHub

Step 4: Configure Environment Variables​

Set up your environment variables for authentication and configuration.

Set Project Token​

The PROJECT_TOKEN is required for SmartUI CLI capture commands.

export PROJECT_TOKEN="123456#1234abcd-****-****-****-************"

Set HyperExecute Credentials​

For HyperExecute, you'll need your LambdaTest username and access key.

export LT_USERNAME="${YOUR_LAMBDATEST_USERNAME}"
export LT_ACCESS_KEY="${YOUR_LAMBDATEST_ACCESS_KEY}"
Getting Your Credentials
  • Username and Access Key: Available in your LambdaTest Profile
  • Project Token: Available in your SmartUI project settings after creation

Step 5: Create URL Configuration Files​

Create JSON files containing the URLs you want to test. Each URL entry should have a name, URL, and optional wait timeout.

Create URL File Using CLI​

You can generate a sample URL file using the SmartUI CLI:

npx smartui config:create-web-static urls.json

Manual URL File Creation​

Alternatively, create your URL file manually. Here's the structure:

urlTest.json
[
    {
        "name": "homepage",
        "url": "https://test.example.com/",
        "waitForTimeout": 5000
    },
    {
        "name": "about_page",
        "url": "https://test.example.com/about/",
        "waitForTimeout": 5000
    },
    {
        "name": "contact_page",
        "url": "https://test.example.com/contact/",
        "waitForTimeout": 5000
    }
]

URL File Structure​

Each URL object supports the following properties:

PropertyTypeRequiredDescription
namestringYesUnique identifier for the screenshot (used in SmartUI dashboard)
urlstringYesThe URL to capture
waitForTimeoutnumberNoWait time in milliseconds before capturing (useful for lazy-loaded content)

Splitting URLs for Parallel Execution​

For large test suites, you can split URLs into multiple files for better parallel execution:

test/urls_test_1.json
[
    {
        "name": "product_category_feature_a",
        "url": "https://test.example.com/product-category/feature-a/",
        "waitForTimeout": 5000
    },
    {
        "name": "product_category_feature_b",
        "url": "https://test.example.com/product-category/feature-b/",
        "waitForTimeout": 5000
    }
]

Step 6: Create SmartUI Configuration​

Create a config.json file to configure browsers, viewports, and other SmartUI settings.

Generate Configuration File​

npx smartui config:create config.json

Manual Configuration​

Create config.json with your desired settings:

config.json
{
  "web": {
    "browsers": [
      "safari",
      "chrome"
    ],
    "viewports": [
      [1367]
    ]
  },
  "mobile": {
    "devices": [
      "iPhone 14",
      "iPad 10.2 (2021)",
      "Pixel 8"
    ],
    "orientation": "portrait"
  },
  "cliEnableJavaScript": true,
  "lazyLoadConfiguration": {
    "enabled": true,
    "jumpBackToTop": true,
    "scrollDelay": 250,
    "scrollStep": 250
  },
  "waitForTimeout": 5000
}

Configuration Options Explained​

Web Configuration​

  • browsers: Array of browser names ("chrome", "firefox", "safari", "edge")
  • viewports: Array of viewport sizes
    • [1367] - Full page screenshot at 1367px width
    • [1920, 1080] - Viewport screenshot at 1920x1080

Mobile Configuration​

  • devices: Array of device names (e.g., "iPhone 14", "Galaxy S24", "Pixel 8")
  • orientation: "portrait" or "landscape"
  • fullPage: true by default for mobile

Lazy Loading Configuration​

  • enabled: Enable lazy loading detection
  • jumpBackToTop: Scroll back to top after capturing
  • scrollDelay: Delay between scroll steps (milliseconds)
  • scrollStep: Pixels to scroll per step
Advanced Configuration

For more configuration options, refer to the SmartUI SDK Config Options documentation.

Step 7: Create HyperExecute YAML Configuration​

Create a hyperexecute.yaml file to configure HyperExecute execution settings.

Basic HyperExecute YAML​

hyperexecute.yaml
---
version: 0.1
globalTimeout: 150
testSuiteTimeout: 150
testSuiteStep: 150

runson: win

retryOnFailure: true
maxRetries: 1

concurrency: 1

env:
  CACHE_DIR: node_modules_cache
  PROJECT_TOKEN: ${PROJECT_TOKEN}

# Dependency caching
cacheKey: '{{ checksum "package.json" }}'
cacheDirectories:
  - ${CACHE_DIR}

pre:
  # Install SmartUI CLI and dependencies
  - npm install @lambdatest/smartui-cli@4.1.54-beta.0
  - npm install playwright@1.57.0
  - npx playwright install

testSuites:
  - npx smartui capture urlTest.json --config config.json --buildName "Test-Release-v1.0"

jobLabel: ['HYP', 'SmartUI', 'Capture']

Advanced HyperExecute YAML with Multiple Test Suites​

For running multiple URL files in parallel:

hyperexecute.yaml
---
version: 0.1
globalTimeout: 300
testSuiteTimeout: 300
testSuiteStep: 150

runson: win

retryOnFailure: true
maxRetries: 1

concurrency: 3

env:
  CACHE_DIR: node_modules_cache
  PROJECT_TOKEN: ${PROJECT_TOKEN}

cacheKey: '{{ checksum "package.json" }}'
cacheDirectories:
  - ${CACHE_DIR}

pre:
  - npm install @lambdatest/smartui-cli@4.1.54-beta.0
  - npm install playwright@1.57.0
  - npx playwright install

matrix:
  urlFile: ["urlTest.json", "urlProd.json"]

testSuites:
  - npx smartui capture ${urlFile} --config config.json --buildName "Build-${urlFile}"

jobLabel: ['HYP', 'SmartUI', 'Capture', 'Parallel']

HyperExecute YAML Parameters​

ParameterDescriptionExample
versionYAML schema version0.1
globalTimeoutMaximum time for entire job (minutes)150
testSuiteTimeoutMaximum time per test suite (minutes)150
runsonOperating system (win, mac, linux)win
concurrencyNumber of parallel test executions3
retryOnFailureRetry failed teststrue
maxRetriesMaximum retry attempts1
preCommands to run before test executionInstallation commands
testSuitesTest commands to executeSmartUI capture commands
matrixMatrix for parallel executionMultiple URL files
HyperExecute YAML Documentation

For detailed YAML configuration options, refer to the HyperExecute YAML Documentation.

Step 8: Execute Tests on HyperExecute​

Download HyperExecute CLI​

Download the HyperExecute CLI for your operating system:

PlatformDownload Link
Windowshttps://downloads.lambdatest.com/hyperexecute/windows/hyperexecute.exe
MacOShttps://downloads.lambdatest.com/hyperexecute/darwin/hyperexecute
Linuxhttps://downloads.lambdatest.com/hyperexecute/linux/hyperexecute

Set Execute Permissions (MacOS/Linux)​

chmod u+x ./hyperexecute

Run Tests​

Execute your tests using the HyperExecute CLI:

./hyperexecute --config hyperexecute.yaml

Or with explicit credentials:

./hyperexecute --user ${YOUR_LAMBDATEST_USERNAME} --key ${YOUR_LAMBDATEST_ACCESS_KEY} --config hyperexecute.yaml

Capture Command Options​

You can enhance your capture commands with additional options:

# With custom build name
npx smartui capture urlTest.json --config config.json --buildName "Release-v1.0"

# With results export
npx smartui capture urlTest.json --config config.json --fetch-results results.json

# With parallel execution
npx smartui capture urlTest.json --config config.json --parallel 3

# Combined options
npx smartui capture urlTest.json --config config.json --buildName "Release-v1.0" --fetch-results results.json --parallel 3

Step 9: Monitor Test Execution​

HyperExecute Dashboard​

  1. Visit the HyperExecute Dashboard
  2. Find your job in the job list
  3. Click on the job to view detailed execution logs
  4. Monitor test progress in real-time

SmartUI Dashboard​

  1. After test execution completes, navigate to SmartUI Dashboard
  2. Select your project
  3. View the build with your specified build name
  4. Review captured screenshots
  5. Compare with baseline images (if available)

Understanding Results​

  • Baseline Build: First build in a project (reference images)
  • Comparison Build: Subsequent builds compared against baseline
  • Mismatches: Visual differences detected between builds
  • Approved: Manually approved visual changes
  • Rejected: Visual changes that need fixing

Using SmartUI Reporter Tool​

The SmartUI Reporter is a web-based tool that provides a comprehensive tabular view of your test results with statistics and export capabilities.

Step 1: Export Results JSON​

From CLI Capture Command:

npx smartui capture urlTest.json --config config.json --fetch-results results.json

From CLI Exec Command:

npx smartui --config config.json exec --fetch-results results.json -- <execution-command>

From SmartUI API: You can also fetch results using the Fetch Build Screenshots API endpoint:

GET /build/screenshots?project_id=YOUR_PROJECT_ID&build_id=YOUR_BUILD_ID

Step 2: Upload to Reporter​

  1. Visit SmartUI Reporter
  2. Upload your results.json file (drag & drop or click to upload)
  3. View results in a tabular format with:
    • Screenshot statistics
    • Browser and viewport information
    • Mismatch percentages
    • Status indicators
    • Direct links to baseline, captured, and diff images

Step 3: Export Options​

  • Export to PDF: Generate a comprehensive PDF report for sharing
  • Export to CSV: Export data for analysis in spreadsheet applications

For detailed information, see the Fetch Results Documentation.

Best Practices​

1. URL Organization​

Separate Test and Production URLs

Keep test and production URLs in separate files:

  • urlTest.json - Staging/test environment
  • urlProd.json - Production environment

This allows you to test both environments independently.

1.1. URL Grouping Strategies for Large Test Suites​

When working with large numbers of URLs (e.g., 1000+ URLs) that can be logically divided into sections or groups (e.g., Section 1: Product Category A, Section 2: Product Category B, Section 3: Product Category C, etc.), you have two primary strategies for organizing your SmartUI projects:

Single Project with Branching Strategy

Use a single SmartUI project and leverage SmartUI's branching capabilities to organize different URL groups within the same project.

How It Works​

  • Single Project: All URL groups/sections are managed in one SmartUI project
  • Branching Strategy: Use SmartUI's Smart Git feature to create separate branches for each section/group
  • Unified Tracking: All URLs and automation are tracked in a single project dashboard
  • Independent Baselines: Each branch maintains its own baseline and comparison history

Implementation​

Step 1: Create URL Groups

Organize your URLs into logical groups:

project/
├── sections/
│   ├── section1_category_a.json    (200 URLs)
│   ├── section2_category_b.json    (200 URLs)
│   ├── section3_category_c.json     (200 URLs)
│   ├── section4_category_d.json     (200 URLs)
│   └── section5_category_e.json    (200 URLs)
├── config.json
└── hyperexecute.yaml

Step 2: Configure HyperExecute with Matrix

Use HyperExecute matrix to run each section:

hyperexecute.yaml
---
version: 0.1
globalTimeout: 300
testSuiteTimeout: 150

runson: win
concurrency: 5

env:
  PROJECT_TOKEN: ${PROJECT_TOKEN}
  SMART_GIT: true  # Enable Smart Git for branch management

pre:
  - npm install @lambdatest/smartui-cli@4.1.54-beta.0

matrix:
  section: ["section1_category_a", "section2_category_b", "section3_category_c", "section4_category_d", "section5_category_e"]

testSuites:
  - npx smartui capture sections/${section}.json --config config.json --buildName "${section}-Build"

Step 3: Use Branching for Organization

Each section can run in its own branch or use build names to group:

# Option A: Use Smart Git with branches
export SMART_GIT=true
git checkout -b section1-category-a
npx smartui capture sections/section1_category_a.json --config config.json --buildName "Section1-CategoryA"

# Option B: Use build names for grouping (single branch)
npx smartui capture sections/section1_category_a.json --config config.json --buildName "Section1-CategoryA-Build"

Use Cases​

✅ Best for:

  • Teams that want centralized project management
  • Organizations needing unified reporting and analytics
  • Projects where sections share common configuration
  • Teams that want to track all URLs in one dashboard
  • Scenarios requiring cross-section comparisons

✅ Benefits:

  • Single project dashboard for all sections
  • Unified baseline management
  • Easier cross-section analysis
  • Simplified project administration
  • Single project token to manage

❌ Not ideal for:

  • Teams requiring completely isolated section management
  • Organizations with different approval workflows per section
  • Projects where sections have vastly different configurations

Decision Matrix​

Use this matrix to decide which strategy fits your needs:

RequirementSingle Project with BranchingSeparate Projects
Unified Dashboard✅ Yes❌ No
Cross-Section Analysis✅ Yes❌ No
Complete Isolation❌ No✅ Yes
Independent Approvals⚠️ Partial (via branches)✅ Yes
Project Management Complexity✅ Lower❌ Higher
Token Management✅ Single token❌ Multiple tokens
Configuration Sharing✅ Easy❌ Requires duplication
Reporting & Analytics✅ Unified❌ Separate per project

Hybrid Approach​

You can also combine both strategies:

  • Major Sections: Use separate projects (e.g., "Production URLs" vs "Staging URLs")
  • Sub-sections: Use branching within each project (e.g., within "Production URLs", use branches for different product categories)
# Production Project - Category A Section
export PROJECT_TOKEN="${PROJECT_TOKEN_PROD}"
export SMART_GIT=true
git checkout -b production-category-a
npx smartui capture sections/category_a_prod.json --config config.json

# Staging Project - Category A Section  
export PROJECT_TOKEN="${PROJECT_TOKEN_STAGING}"
export SMART_GIT=true
git checkout -b staging-category-a
npx smartui capture sections/category_a_staging.json --config config.json

Best Practices for Large URL Sets​

  1. Logical Grouping: Group URLs by functionality, product category, or business domain
  2. Consistent Naming: Use consistent naming conventions across groups
  3. Documentation: Document which URLs belong to which section
  4. Regular Review: Periodically review and reorganize groups as needed
  5. Parallel Execution: Leverage HyperExecute's parallel execution for faster test runs

2. Configuration Management​

Select Relevant Browsers

Only test browsers that your users actually use:

{
  "web": {
    "browsers": ["chrome", "safari", "firefox"]
  }
}

Avoid testing unnecessary browsers to reduce execution time and costs.

3. HyperExecute Configuration​

Optimize Concurrency

Set appropriate concurrency based on your test suite size:

concurrency: 3  # For 20-30 URLs

Too high concurrency may cause resource issues.

4. Build Naming​

Use descriptive build names that include:

  • Environment (Test/Prod)
  • Version or release number
  • Date or timestamp
--buildName "Test-Release-v1.0-2024-01-15"

5. Regular Baseline Updates​

  • Update baselines when intentional UI changes are made
  • Review and approve changes regularly
  • Keep baseline builds organized with clear naming

Troubleshooting​

Common Issues and Solutions​

Issue: PROJECT_TOKEN is not set or authentication failures

Solutions:

  1. Verify PROJECT_TOKEN is set correctly:

    echo $PROJECT_TOKEN  # MacOS/Linux
    echo %PROJECT_TOKEN%  # Windows CMD

  2. Check token format (should include #):

    123456#1234abcd-****-****-****-************

  3. Verify token in SmartUI dashboard project settings

  4. For HyperExecute, also verify LT_USERNAME and LT_ACCESS_KEY

Debugging Tips​

  1. Test Locally First: Run SmartUI capture locally before HyperExecute:

    npx smartui capture urlTest.json --config config.json

  2. Check Logs: Review HyperExecute job logs for detailed error messages

  3. Verify Configuration: Use npx smartui --help to verify CLI installation

  4. Test Individual URLs: Test problematic URLs individually to isolate issues

  5. Monitor Dashboard: Check both HyperExecute and SmartUI dashboards for errors

Advanced Usage​

CI/CD Integration​

Integrate SmartUI Capture with your CI/CD pipeline:

.github/workflows/smartui-capture.yml
name: SmartUI Capture Tests

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

env:
  LT_USERNAME: ${{ secrets.LT_USERNAME }}
  LT_ACCESS_KEY: ${{ secrets.LT_ACCESS_KEY }}
  PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}

jobs:
  smartui-capture:
    name: Execute SmartUI Capture
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Install Dependencies
        run: |
          npm install @lambdatest/smartui-cli@4.1.54-beta.0
          npm install playwright@1.57.0
          npx playwright install

      - name: Run SmartUI Capture
        run: |
          npx smartui capture urlTest.json --config config.json --buildName "PR-${{ github.event.pull_request.number }}"

      - name: Fetch Results
        run: |
          npx smartui capture urlTest.json --config config.json --fetch-results results.json

Scheduled Test Runs​

Use the --scheduled flag for scheduled test executions:

npx smartui capture urlProd.json --config config.json --scheduled "schedule-123"

Custom Build Names with Variables​

Use environment variables in build names:

testSuites:
  - npx smartui capture urlTest.json --config config.json --buildName "Build-${BUILD_NUMBER}"

Next Steps​

Now that you've set up SmartUI Capture with HyperExecute, explore these resources:

Additional Resources​

Last updated on

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

Book Demo

Help and Support

Related Articles