Getting started with SmartUI using K6

---

This documentation will act as your step-by-step guide in to perform K6 test with SmartUI.

Prerequisites for running SmartUI with K6

• Basic understanding of K6 is required.
• Go to SmartUI and login along with your credentials.
• Copy LT_USERNAME and LT_ACCESS_KEY credentials from Access Key button on the top right of the dashboard.

MacOS/Linux

export LT_USERNAME="YOUR_USERNAME"

Windows - CMD

set LT_USERNAME="YOUR_USERNAME"

PowerShell

$env:LT_USERNAME="YOUR_USERNAME"

The following steps will guide you in running your first Visual Regression test on LambdaTest platform -

Step 1: 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 Web for executing your K6 tests.
4. Add name of the project, approvers for the changes found, tags for any filter or easy navigation.
5. Click on the Submit.

Step 2: Configure your test with K6 Desired Capabilities

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

1. Please clone the following sample Github repo (https://github.com/LambdaTest/smartui-k6-sample).

git clone https://github.com/LambdaTest/smartui-k6-sample.git

1. Install k6 by referring to the installation guide https://k6.io/docs/get-started/installation/:

MacOS

brew install k6

Windows

winget install k6

1. Set up the LambdaTest credentials by using the commands below in the terminal.The account details are available on your LambdaTest Profile page.

For macOS:

export LT_USERNAME=LT_USERNAME
export LT_ACCESS_KEY=LT_ACCESS_KEY

For Linux:

export LT_USERNAME=LT_USERNAME
export LT_ACCESS_KEY=LT_ACCESS_KEY

For Windows:

set LT_USERNAME=LT_USERNAME
set LT_ACCESS_KEY=LT_ACCESS_KEY

1. Edit the required capabilities in your test file k6-smartui.js.

Add the following code snippet to run SmartUI with K6 in ./navigation.js

import { chromium } from 'k6/experimental/browser';
import { expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default async function () {
  const capabilities = {
    "browserName": "Chrome",
    "browserVersion": "latest",
    "LT:Options": {
      "platform": "MacOS Ventura",
      "build": "K6 Build",
      "name": "K6 SmartUI test",
      "user": __ENV.LT_USERNAME,
      "accessKey": __ENV.LT_ACCESS_KEY,
      "network": true,
      "video": true,
      "console": true,
      'tunnel': false, // Add tunnel configuration if testing locally hosted webpage
      'tunnelName': '', // Optional
      'geoLocation': '', // country code can be fetched from https://www.lambdatest.com/capabilities-generator/
      'smartUIProjectName': 'K6_Test_Sample', // Add the required SmartUI Project name
    },
  };

  const wsURL = `wss://cdp.lambdatest.com/k6?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
  const browser = chromium.connect(wsURL);

  const page = browser.newPage();

  try {
    await page.goto("https://duckduckgo.com");

    // Add the following command in order to take screenshot in SmartUI
    await captureSmartUIScreenshot(page, "Homepage")

    let element = await page.$("[name=\"q\"]");
    await element.click();
    await element.type("K6");
    await element.press("Enter");
    let title = await page.title();

    expect(title).to.equal("K6 at DuckDuckGo");

    // Pass the `page` object. Add `screennshotName` if you want to fetch response for a specific screenshot
    await validateSmartUIScreenshots(page)

    // Mark the test as passed or failed
    await page.evaluate(_ => {}, `lambdatest_action: ${JSON.stringify({ action: "setTestStatus", arguments: { status: "passed", remark: "Assertions passed" },})}`);
    await teardown(page, browser)
  } catch (e) {
      console.log('Error:: ', JSON.stringify(e))
      await page.evaluate(_ => {}, `lambdatest_action: ${JSON.stringify({ action: 'setTestStatus', arguments: { status: 'failed', remark: JSON.stringify(e) } })}`)

    await teardown(page, browser)
    throw e
  }
};

async function captureSmartUIScreenshot(page, screenshotName) {
  await page.evaluate(_ => {}, `lambdatest_action: ${JSON.stringify({ action: "smartui.takeScreenshot", arguments: { screenshotName: screenshotName } })}`);
}

async function teardown(page, browser) {
  await page.close();
  await browser.close();
}

const validateSmartUIScreenshots = async (page, screenshotName) => {
  try {
    await page.waitForTimeout(10000) // Added delay to get reports of all screenshots captured

    let screenshotResponse = JSON.parse(await page.evaluate(_ => {}, `lambdatest_action: ${JSON.stringify({ action: 'smartui.fetchScreenshotStatus', arguments: { screenshotName }})}`))
    console.log('screenshotStatus response: ', screenshotResponse)

    if (screenshotResponse.screenshotsData && Array.isArray(screenshotResponse.screenshotsData)) {
      for (let i = 0; i < screenshotResponse.screenshotsData.length; i++) {
        let screenshot = screenshotResponse.screenshotsData[i];
        if (screenshot.screenshotStatus !== "Approved") {
          throw new Error(`Screenshot status is not approved for the screenshot ${screenshot.screenshotName}`);
        }
      }
    }
  } catch (error) {
    throw new Error(error);
  }
}

Step 3: Executing the SmartUI Test Suite on Cloud

Execute the test using the following command to run the test suite using K6

MacOS/Linux

K6_BROWSER_ENABLED=true k6 run k6-smartui.js

Windows

set K6_BROWSER_ENABLED=true
k6 run k6-smartui.js

• You can check the executed builds over at LambdaTest SmartUI.

Best Practices

1. 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");

2. Wait for Page Load

• Always wait for pages to fully load before taking screenshots
• Use K6'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');
await page.waitForLoadState('networkidle');
await smartuiSnapshot(page, "Page Loaded");

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

4. Configuration Management

• Keep SmartUI configuration in version control
• Use environment variables for sensitive data
• Document custom configuration choices

5. Test Organization

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

Troubleshooting

Common Issues

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
• K6 browser not enabled

Solutions:

1. Verify PROJECT_TOKEN is set correctly:

   echo $PROJECT_TOKEN

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

3. Ensure K6 browser is enabled:

   K6_BROWSER_ENABLED=true k6 run k6-smartui.js

4. Check network connectivity to LambdaTest servers

5. Review test execution logs for error messages

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

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.waitForSelector('#content');
   await page.waitForSelector('.main-content');
   await page.waitForLoadState('networkidle');

2. Enable JavaScript in configuration:

   {
     "enableJavaScript": true
   }

3. Increase waitForTimeout in configuration

4. Verify viewport size matches expected dimensions

Issue: K6 Browser Not Enabled

Symptoms: Tests fail with "browser not enabled" error

Possible Causes:

• K6_BROWSER_ENABLED environment variable not set
• K6 browser extension not installed
• K6 version doesn't support browser

Solutions:

1. Set environment variable:

   export K6_BROWSER_ENABLED=true

2. Or run with environment variable:

   K6_BROWSER_ENABLED=true k6 run k6-smartui.js

3. Verify K6 version supports browser:

   k6 version

4. Install K6 browser extension if needed

Issue: Screenshot Status Not Approved

Symptoms: Screenshots appear but status is not "Approved"

Possible Causes:

• Screenshot comparison failed
• Baseline doesn't exist
• Mismatch threshold exceeded

Solutions:

1. Check screenshot status in response:

   if (screenshot.screenshotStatus !== "Approved") {
       // Handle non-approved status
   }

2. Review comparison results in SmartUI dashboard

3. Verify baseline exists and is correct

4. Adjust pixel threshold if needed

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 K6 Browser Testing Documentation for K6-specific 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
• K6 Browser Testing Documentation
• SmartUI API Documentation

For additional information about K6 framework please explore the documentation here

Advanced Options for Screenshot Comparison

Build Configuration - If you have multiple screenshots running the same test suite and want to run the comparison for the same test suite, want to add a build as a baseline from your test suite or need to access more SmartUI Build Config Options, click here.