Skip to main content

GitLab PR Checks with SmartUI Hooks

This guide shows you how to integrate SmartUI visual regression testing with GitLab merge requests using the SmartUI Hooks approach. This works for both web testing (Selenium, Playwright, Cypress, Puppeteer) and mobile app testing (Appium, WebdriverIO) across all supported languages.

SmartUI Hooks vs SDK

This guide covers the SmartUI Hooks approach, where you pass SmartUI capabilities directly in your test configuration. This is different from the SDK approach:

SmartUI Hooks (This Guide):

  • ✅ No npx smartui exec command needed
  • ✅ Tests run normally (e.g., npm test, mvn test, pytest)
  • ✅ SmartUI integration happens automatically through capabilities
  • ✅ Suitable for TypeScript/JavaScript/Java/Python/Ruby/C#/WebdriverIO/Appium
  • ✅ Works with web testing (Selenium, Playwright, Cypress, Puppeteer)
  • ✅ Works with mobile app testing (Appium, iOS/Android)

SmartUI SDK:

  • Requires npx smartui exec -- <your-test-command>
  • Used for Java SDK and CLI-based projects
  • See SmartUI Appium Java SDK for SDK approach

Prerequisites​

Before you begin, ensure you have:

  • LambdaTest account with active subscription
  • GitLab repository with CI/CD enabled
  • SmartUI project created in LambdaTest SmartUI Dashboard
  • Test suite configured (Selenium/Playwright/Cypress/Puppeteer/Appium/WebdriverIO)
  • Test framework configured in your preferred language (TypeScript/JavaScript/Java/Python/Ruby/C#)
  • LambdaTest credentials (LT_USERNAME and LT_ACCESS_KEY)

Step 1: Integrate GitLab with LambdaTest​

  1. Go to LambdaTest Integrations page
  2. Search for GitLab and select the integration
  3. Click on OAuth as your preferred authentication method
  4. Click Install and authorize the integration
  5. After successful authentication, refresh the Integrations page to verify GitLab is installed
GitLab integration setup in LambdaTest
Integration Status

You can verify your GitLab integration is active by checking the Integrations page. The GitLab integration should show as "Installed" or "Active".

Step 2: Configure SmartUI Capabilities with GitLab Integration​

Configure your test suite with SmartUI capabilities. Since you're using the Hooks approach, you'll pass SmartUI capabilities directly in your test configuration, including the GitLab integration capability.

Example: TypeScript Selenium Configuration with SmartUI Hooks and GitLab
import { Builder, Capabilities } from 'selenium-webdriver';

const capabilities = {
  browserName: 'Chrome',
  browserVersion: 'latest',
  platformName: 'Windows 10',
  'LT:Options': {
    username: process.env.LT_USERNAME,
    accessKey: process.env.LT_ACCESS_KEY,
    project: 'Your Project Name',
    w3c: true,
    name: 'Web Test Session',
    build: process.env.CI 
      ? `${process.env.CI_PROJECT_NAME}-${process.env.CI_PIPELINE_ID}`
      : `smartui-local-build-${new Date().toISOString().split('T')[0]}`,
    
    // SmartUI Hooks Configuration
    "smartUI.project": `${process.env.SMARTUI_PROJECT_NAME}-visual`,
    "smartUI.build": process.env.CI 
      ? `${process.env.CI_PROJECT_NAME}-${process.env.CI_PIPELINE_ID}`
      : `smartui-local-build-${new Date().toISOString().split('T')[0]}`,
    "smartUI.baseline": false,
    
    // GitLab Integration Capability
    github: {
      url: process.env.GIT_URL // GitLab API URL for status updates
    }
  }
};

const driver = await new Builder()
  .usingServer(`https://${process.env.LT_USERNAME}:${process.env.LT_ACCESS_KEY}@hub.lambdatest.com/wd/hub`)
  .withCapabilities(capabilities)
  .build();
GitLab Capability Note

The capability is named github (legacy name) but works with GitLab's API endpoint. Use the GIT_URL environment variable to pass the GitLab API URL. This is the same capability used for GitHub integration and supports both GitHub and GitLab status APIs.

Taking Screenshots with SmartUI Hooks​

In your test code, use the SmartUI execute command to capture screenshots:

Taking Screenshots with SmartUI Hooks
// Viewport screenshot
await driver.execute("smartui.takeScreenshot=Homepage");

// Full page screenshot (if supported)
const config = {
  screenshotName: 'Homepage',
  fullPage: true,
  pageCount: 15  // Minimum 1, Maximum 20
};
await driver.execute("smartui.takeScreenshot", config);

Step 3: Configure GitLab CI/CD Pipeline​

Create or update your .gitlab-ci.yml file. Since you're using Hooks, you just need to run your tests normally - no SmartUI CLI exec command required.

Complete GitLab CI/CD Configuration​

.gitlab-ci.yml - TypeScript/JavaScript Example
stages:
  - test

variables:
  NODE_VERSION: "18"
  LT_USERNAME: $LT_USERNAME
  LT_ACCESS_KEY: $LT_ACCESS_KEY
  SMARTUI_PROJECT_NAME: $SMARTUI_PROJECT_NAME

visual_regression_tests:
  stage: test
  image: node:${NODE_VERSION}
  
  before_script:
    - npm ci
  
  script:
    # Get GitLab project ID and commit SHA
    - |
      PROJECT_ID=${CI_PROJECT_ID}
      COMMIT_SHA=${CI_COMMIT_SHA}
      
      # For merge requests, use the merge request commit SHA
      if [ -n "$CI_MERGE_REQUEST_IID" ]; then
        COMMIT_SHA=${CI_MERGE_REQUEST_SHA:-${CI_COMMIT_SHA}}
      fi
      
      # Construct GitLab API URL for status updates
      GITHUB_URL="https://gitlab.com/api/v4/projects/${PROJECT_ID}/statuses/${COMMIT_SHA}"
      
      echo "GitLab Project ID: ${PROJECT_ID}"
      echo "Commit SHA: ${COMMIT_SHA}"
      echo "GitLab Status URL: ${GITHUB_URL}"
      
      # Export GITHUB_URL as environment variable for use in test capabilities
      export GITHUB_URL="${GITHUB_URL}"
      
      # Run your tests normally - SmartUI Hooks work automatically through capabilities
      npm test
      # Or: npx wdio run wdio.conf.ts
      # Or: npm run test:mobile
      
  only:
    - merge_requests
    - main
    - develop
  
  environment:
    name: visual-regression/$CI_COMMIT_REF_NAME

Key Configuration Points​

  1. No SmartUI CLI exec needed: With Hooks, you run your tests normally (e.g., npm test, mvn test, pytest)
  2. GitLab Project ID: Automatically available as CI_PROJECT_ID in GitLab CI/CD
  3. Commit SHA: Use CI_COMMIT_SHA for regular commits, or CI_MERGE_REQUEST_SHA for merge requests
  4. GitLab API URL: Export as GIT_URL environment variable, which your test capabilities will use
  5. GitLab API URL Format: https://gitlab.com/api/v4/projects/{projectId}/statuses/{commitId}
How Hooks Work

With SmartUI Hooks:

  • You pass SmartUI capabilities (including github.url with GIT_URL for GitLab) in your test configuration
  • Run your tests normally (no npx smartui exec command)
  • SmartUI integration happens automatically through the capabilities
  • GitLab PR checks are updated automatically when tests complete

Step 4: Set Up GitLab CI/CD Variables​

Configure the following variables in your GitLab project:

  1. Go to your GitLab project → Settings → CI/CD → Variables
  2. Add the following variables:
GitLab CI/CD Variables configuration
Variable NameDescription
LT_USERNAMEYour LambdaTest username
LT_ACCESS_KEYYour LambdaTest access key
SMARTUI_PROJECT_NAMEYour SmartUI project name

Step 5: View Pipeline Results in GitLab​

After your pipeline runs, you can view the results in the GitLab Pipelines page:

GitLab Pipelines page showing SmartUI test results

The pipeline will show:

  • Pipeline status (Success/Failed)
  • Job status for SmartUI tests
  • Screenshot statistics (Total, Approved, Changes Found) in the job tooltip

Step 6: View PR Check Results in GitLab Merge Request​

After your pipeline runs, you'll see SmartUI status checks in your GitLab merge request:

GitLab merge request showing SmartUI PR check status

Successful Status​

When all visual tests pass:

  • ✅ Status: Success
  • Details: Click "Details" to view the SmartUI build in the dashboard
  • Screenshot: All screenshots match baseline or are approved

Failed Status​

When visual differences are detected:

  • ❌ Status: Failed
  • Details: Click "Details" to review differences in SmartUI dashboard
  • Action Required: Review and approve/reject changes in SmartUI dashboard

Complete Working Examples​

example.spec.ts - Complete Web Test with SmartUI Hooks and GitLab
import { Builder, Capabilities } from 'selenium-webdriver';

describe('Web Visual Regression Tests', () => {
  let driver;

  before(async () => {
    // Construct GitLab URL (in CI/CD, this would come from environment variable)
    const gitUrl = process.env.GIT_URL || 
      `https://gitlab.com/api/v4/projects/${process.env.CI_PROJECT_ID}/statuses/${process.env.CI_COMMIT_SHA}`;

    const capabilities = {
      browserName: 'Chrome',
      browserVersion: 'latest',
      platformName: 'Windows 10',
      'LT:Options': {
        username: process.env.LT_USERNAME,
        accessKey: process.env.LT_ACCESS_KEY,
        project: 'Your Project Name',
        w3c: true,
        name: 'Web Visual Tests',
      build: process.env.CI 
        ? `${process.env.CI_PROJECT_NAME}-${process.env.CI_PIPELINE_ID}`
        : `local-build-${Date.now()}`,
      "smartUI.project": `${process.env.SMARTUI_PROJECT_NAME}-visual`,
      "smartUI.build": process.env.CI 
        ? `${process.env.CI_PROJECT_NAME}-${process.env.CI_PIPELINE_ID}`
        : `local-build-${Date.now()}`,
      "smartUI.baseline": false,
      // GitLab integration capability
      github: {
          url: gitUrl
        }
      }
    };

    driver = await new Builder()
      .usingServer(`https://${process.env.LT_USERNAME}:${process.env.LT_ACCESS_KEY}@hub.lambdatest.com/wd/hub`)
      .withCapabilities(capabilities)
      .build();
  });

  after(async () => {
    if (driver) {
      await driver.quit();
    }
  });

  it('should capture homepage screenshot', async () => {
    await driver.get('https://example.com');
    await driver.executeScript("smartui.takeScreenshot=Homepage");
  });

  it('should capture login page screenshot', async () => {
    await driver.get('https://example.com/login');
    await driver.executeScript("smartui.takeScreenshot=LoginPage");
  });
});

Troubleshooting​

Issue: PR Check Not Appearing in GitLab

Symptoms: Pipeline runs but no SmartUI status check appears in merge request.

Solutions:

  1. Verify GitLab integration is active in LambdaTest Integrations
  2. Check that github.url capability is correctly set in your test configuration
  3. Verify GIT_URL environment variable is exported in CI/CD pipeline
  4. Ensure CI_PROJECT_ID and CI_COMMIT_SHA are correctly set
  5. For merge requests, use CI_MERGE_REQUEST_SHA instead of CI_COMMIT_SHA
  6. Check test logs to ensure tests completed successfully
  7. Verify GitLab API URL format: https://gitlab.com/api/v4/projects/{projectId}/statuses/{commitId}

Key Differences: Hooks vs SDK​

AspectSmartUI Hooks (This Guide)SmartUI SDK
CommandRun tests normally (npm test, mvn test, pytest)Use npx smartui exec -- <command>
IntegrationAutomatic via capabilitiesRequires CLI wrapper
SetupAdd capabilities to test configConfigure CLI and run with exec
GitLab IntegrationAdd github.url capability with GIT_URLUse --gitURL parameter with exec
LanguagesTypeScript/JS/Java/Python/Ruby/C#/WebdriverIO/AppiumJava SDK, CLI projects
Java Support✅ Yes - Use capabilities with github capability✅ Yes - Use npx smartui exec -- mvn test

Next Steps​

Last updated on

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

Book Demo

Help and Support

Related Articles