Integrate SmartUI SDK with Puppeteer Tests

---

Welcome to the world of simplified visual testing with the SmartUI SDK.

Integrating seamlessly into your existing Puppeteer testing suite, SmartUI SDK revolutionizes the way you approach visual regression testing. Our robust solution empowers you to effortlessly capture, compare, and analyze screenshots across a multitude of browsers and resolutions, ensuring comprehensive coverage and accuracy in your visual testing endeavors.

Prerequisites

• Basic understanding of Command Line Interface and Puppeteer is required.
• Login to LambdaTest SmartUI with your credentials.

The following steps will guide you in running your first Visual Regression test on LambdaTest platform using SmartUI Puppeteer SDK integration.

Create a SmartUI 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 SDK 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

Once you have created a SmartUI Project, you can generate screenshots by running automation scripts. Follow the below steps to successfully generate screenshots

Step 1: Create/Update your test

You can clone the sample repository to run LambdaTest automation tests with SmartUI and use the puppeteerCloud.js file present in the sdk folder.

git clone https://github.com/LambdaTest/smartui-puppeteer-sample
cd smartui-puppeteer-sample/sdk

Step 2: Install the Dependencies

Install required NPM modules for LambdaTest SmartUI Puppeteer SDK in your Frontend project.

npm install @lambdatest/smartui-cli @lambdatest/puppeteer-driver puppeteer

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 3: Configure your Project Token

Setup your project token shown in the SmartUI app after creating your project.

MacOS/Linux

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

Windows - CMD

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

PowerShell

$env:PROJECT_TOKEN=123456#1234abcd-****-****-****-************"

Step 4: Create and Configure SmartUI Config

You can now configure your project configurations on using various available options to run your tests with the SmartUI integration. To generate the configuration file, please execute the following command:

npx smartui config:create .smartui.json

Once, the configuration file will be created, you will be seeing the default configuration pre-filled in the configuration file:

/smartui-sdk-project/.smartui.json

{
  "web": {
    "browsers": [
      "chrome",
      "firefox",
      "safari",
      "edge"
    ],
    "viewports": [
      [
        1920
      ],
      [
        1366
      ],
      [
        1028
      ]
    ] // Full Page screenshots are captured by default for web viewports
  },
  "mobile": {
    "devices": [
      "iPhone 14",  //iPhone 14 viewport
      "Galaxy S24"  //Galaxy S24 viewport
    ],
    "fullPage": true, //Full Page is true by default for mobile viewports
    "orientation": "portrait" //Change to "landscape" for landscape snapshot
  },
  "waitForTimeout": 1000, //Optional (Should only be used in case lazy-loading/async components are present)
  "waitForPageRender": 50000, //Optional (Should only be used in case of websites which take more than 30s to load)
  "enableJavaScript": false, //Enable javascript for all the screenshots of the project
  "allowedHostnames": [] //Additional hostnames to capture assets from
}

Advanced options in SmartUI configuration

• For capturing fullpage or viewport screenshots, please refer to this documentation
• For the list of available mobile viewports, please refer to this documentation
• For more information about SmartUI config global options, please refer to this documentation.

Step 5: Adding SmartUI function to take screenshot

• You can incorporate SmartUI into your custom Puppeteer automation test (any platform) script by adding the smartuiSnapshot function in the required segment of Puppeteer script of which we would like to take the screenshot, as shown below:

const puppeteer = require("puppeteer");
const { smartuiSnapshot } = require('@lambdatest/puppeteer-driver'); // Assuming you still want to use smartuiSnapshot locally

(async () => {
  // Launch a browser instance locally
  const browser = await puppeteer.launch({
    headless: false, // Set to false to see the UI
    args: ['--start-maximized'], // Start browser maximized, remove if not needed
  });
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 720 }); // Set viewport size as needed

  // Navigate to the desired URL
  await page.goto('https://www.lambdatest.com');

  // Take a screenshot with SmartUI. Replace "LT-Home" with a relevant name for your use case
  await smartuiSnapshot(page, "LT-Home");

  // Close the browser
  await browser.close();
})();

Step 6: Execute the Tests on SmartUI Cloud

Execute visual regression tests on SmartUI using the following commands

npx smartui exec node puppeteerCloud.js --config .smartui.json

note

You may use the npx smartui --help command in case you are facing issues during the execution of SmartUI commands in the CLI.

View SmartUI Results

You have successfully integrated SmartUI SDK with your Puppeteer tests. Visit your SmartUI project to view builds and compare snapshots between different test runs.

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.

Arguments supported in the smartUISnapshot function

The following are the different options which are currently supported:

Key	Description
driver (instance)	The instance of the web driver used in your tests.
"Screenshot Name" (string)	Specify a name for the screenshot in your tests to match the same screenshot with the name from your baseline.
options (object)	Specify one or a combination of selectors in the ignoreDOM or selectDOM objects. These selectors can be based on HTML DOM IDs, CSS classes, CSS selectors, or XPaths used by your webpage. They define elements that should be excluded from or included in the visual comparison.

Handling Dynamic Data in SmartUI SDK New

When conducting visual tests, you may encounter scenarios where certain elements within your application change between test runs. These changes might introduce inconsistencies in your test results.You can ignore / select specific element(s) to be removed from the comparison by parsing the options in the smartuiSnapshot function in the following way

Ignore ID

This is a sample for your configuration for Puppeteer to ignore by

let options = {
            ignoreDOM: {
                id: ["ID-1", "ID-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Ignore Class

This is a sample for your configuration for Puppeteer to ignore by

let options = {
            ignoreDOM: {
                class: ["Class-1", "Class-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Ignore XPath

This is a sample for your configuration for Puppeteer to ignore by

let options = {
            ignoreDOM: {
                xpath: ["Xpath-1", "Xpath-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Ignore CSS Selector

This is a sample for your configuration for Puppeteer to ignore by CSS

let options = {
            ignoreDOM: {
                cssSelector: ["CSS-Selector-1", "CSS-Selector-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Select ID

This is a sample for your configuration for Puppeteer to select by

let options = {
            selectDOM: {
                id: ["ID-1", "ID-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Select Class

This is a sample for your configuration for Puppeteer to select by

let options = {
            selectDOM: {
                class: ["Class-1", "Class-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Select XPath

This is a sample for your configuration for Puppeteer to select by

let options = {
            selectDOM: {
                xpath: ["Xpath-1", "Xpath-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Select CSS Selector

This is a sample for your webhook configuration for Puppeteer to select by CSS

let options = {
            selectDOM: {
                cssSelector: ["CSS-Selector-1", "CSS-Selector-2"],
            }
        }
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

For capturing the screenshot of a specific element

You can capture screenshots of targeted elements by leveraging various locator mechanisms such as XPath, CSS ID, class, and selectors. This precision-driven approach ensures accurate and specific visual regression testing for your web application's components.

Capture Element by ID

This is a sample for your configuration for Puppeteer to capture an element by

let options = {
      element: {
          id: 'Required ID',
      }
  };
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Capture Element by Class

This is a sample for your configuration for Puppeteer to capture an element by

let options = {
      element: {
          class: 'Required Class',
      }
  };
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Capture Element by XPath

This is a sample for your configuration for Puppeteer to capture an element by

let options = {
      element: {
          xpath: 'Required Xpath',
      }
  };
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

Capture Element by Selector

This is a sample for your webhook configuration for Puppeteer to capture an element by CSS

let options = {
      element: {
          cssSelector: 'Required CSS Selector',
      }
  };
        await page.goto('Required URL');
        await smartuiSnapshot.smartuiSnapshot(page, "Screenshot Name", options);

For capturing interactive lazy loading elements

If you encounter difficulties loading interactive elements that appear on scroll in full-page screenshots, consider functionally incorporating a full-page scroll into your script before capturing the screenshot. This approach ensures the elements load first, facilitating the screenshot processing.

const puppeteer = require('puppeteer');
const { smartuiSnapshot } = require('@lambdatest/puppeteer-driver');

(async () => {
  const browser = await puppeteer.launch({ headless: false }); // Launches a browser
  const page = await browser.newPage(); // Opens a new page

  try {
    await page.goto('Required URL'); // Navigate to the required URL

    // Function to scroll to the bottom of the page
    async function quickScrollToBottom(lastPageWait) {
      await page.evaluate(async (lastPageWait) => {
        const scrollToBottom = async (lastPageWait) => {
          const getScrollHeight = () => document.body.scrollHeight;
          let lastHeight = await getScrollHeight();
          let currentHeight = 0;

          while (currentHeight < lastHeight) {
            window.scrollTo(0, lastHeight);
            await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for the page to load more content
            currentHeight = lastHeight;
            lastHeight = await getScrollHeight();
          }

          if (lastPageWait) {
            await new Promise(resolve => setTimeout(resolve, lastPageWait)); // Additional wait at the bottom
          }

          // Scroll back to the top after reaching the bottom
          window.scrollTo(0, 0);
          await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for scroll to top
        };
        await scrollToBottom(lastPageWait);
      }, lastPageWait);
    }

    await quickScrollToBottom(100); // Adjust the wait time as needed

    // Taking a screenshot with SmartUI
    await smartuiSnapshot(page, "Screenshot Name");

  } finally {
    await browser.close(); // Close the browser
  }
})();

Best Practices

Screenshot Naming

Screenshot Naming

• Use descriptive, consistent names for screenshots
• Include page/component name in screenshot names
• Avoid special characters that might cause issues
• Use consistent naming conventions across your test suite

Example:

await smartuiSnapshot(page, HomePage-Header");
await smartuiSnapshot(page, "ProductPage-MainContent");

Wait for Page Load

Wait for Page Load

• Always wait for pages to fully load before taking screenshots
• Use Puppeteer's built-in wait methods for dynamic content
• Consider using waitForTimeout in configuration for lazy-loaded content

Example:

await page.goto('https://example.com');
await page.waitForSelector('#main-content', { visible: true });
await page.waitForLoadState('networkidle');
await smartuiSnapshot(page, Page Loaded");

Handle Dynamic Content

Handle Dynamic Content

• Use ignoreDOM for elements that change between runs
• Use selectDOM when you only need to compare specific areas
• Document why elements are ignored for future reference

Configuration Management

Configuration Management

• Keep .smartui.json in version control
• Use environment variables for sensitive data
• Document custom configuration choices

Test Organization

Test Organization

• Group related screenshots in the same build
• Use meaningful build names
• Run tests in consistent environments

Troubleshooting

Screenshots Not Appearing in Dashboard

Issue: Screenshots Not Appearing in Dashboard

Symptoms: Tests run successfully but no screenshots appear in SmartUI dashboard

Possible Causes:

• Project token not set or incorrect
• Project name mismatch
• Network connectivity issues
• CLI not installed or outdated

Solutions:

1. Verify PROJECT_TOKEN is set correctly:

   echo $PROJECT_TOKEN

2. Check project name matches exactly (case-sensitive)

3. Verify SmartUI CLI is installed:

   npx smartui --version

4. Check network connectivity to LambdaTest servers

5. Review test execution logs for error messages

Project Not Found Error

Issue: Project Not Found" Error

Symptoms: Error message indicating project cannot be found

Possible Causes:

• Incorrect project token
• Project deleted or renamed
• Token from wrong project

Solutions:

1. Verify project exists in SmartUI dashboard
2. Copy project token directly from Project Settings
3. Ensure token includes the project ID prefix (e.g., 123456#...)
4. Check for extra spaces or quotes in token

Screenshots Show Blank or Incorrect Content

Issue: Screenshots Show Blank or Incorrect Content

Symptoms: Screenshots captured but show blank pages or incorrect content

Possible Causes:

• Page not fully loaded
• JavaScript not executed
• Viewport size issues
• Timing issues

Solutions:

1. Add explicit waits before screenshots:

   await page.goto('https://example.com');
   await page.waitForSelector('#content', { visible: true });
   await page.waitForLoadState('networkidle');

2. Enable JavaScript in configuration:

   {
     enableJavaScript": true
   }

3. Increase waitForTimeout in configuration

4. Verify viewport size matches expected dimensions

Build Execution Fails

Issue: Build Execution Fails

Symptoms: npx smartui exec command fails

Possible Causes:

• Missing or incorrect configuration file
• Invalid JSON in configuration
• Port conflicts
• Permission issues

Solutions:

1. Verify .smartui.json exists and is valid JSON
2. Check configuration file syntax
3. Try different port if default is in use:

   npx smartui exec -P 5000 -- <command">
4. Check file permissions for configuration and project files

npm Dependencies Not Resolving

Issue: npm Dependencies Not Resolving

Symptoms: npm cannot find @lambdatest/puppeteer-driver or @lambdatest/smartui-cli

Possible Causes:

• Incorrect package version
• npm registry access issues
• Network connectivity problems

Solutions:

1. Check latest versions on npm:

   npm view @lambdatest/puppeteer-driver version
   npm view @lambdatest/smartui-cli version

2. Clear npm cache:

   npm cache clean --force

3. Verify internet connectivity for npm registry access

4. Check package.json for version conflicts

Screenshot Names Not Matching Baseline

Issue: Screenshot Names Not Matching Baseline

Symptoms: Screenshots appear as New" instead of comparing with baseline

Possible Causes:

• Screenshot name changed
• Baseline doesn't exist
• Name contains special characters

Solutions:

1. Ensure screenshot names are consistent across test runs
2. Verify baseline exists in project
3. Avoid special characters in screenshot names
4. Check for case sensitivity issues

Getting Help

If you encounter issues not covered here:

• Review the Comprehensive Troubleshooting Guide for detailed solutions
• Check SmartUI Configuration Options documentation
• See Handling Dynamic Data for dynamic content issues
• Visit LambdaTest Support for additional resources
• Contact support at support@lambdatest.com or use 24/7 Chat Support

Additional Resources

• Comprehensive Troubleshooting Guide
• SmartUI Configuration Options
• Handling Dynamic Data
• Handling Lazy Loading
• Baseline Management
• Running Your First Project
• SmartUI API Documentation