A powerful Java SDK for seamlessly integrating Selenium tests with the LambdaTest cloud platform. This SDK provides automatic capability injection, test status management, and simplified configuration for running Selenium tests on LambdaTest's cloud infrastructure.

✨ Automatic Capability Injection - No need to manually configure LambdaTest capabilities
🔧 Java Agent Support - Bytecode instrumentation for seamless integration
📊 Test Status Management - Automatically mark tests as passed/failed on LambdaTest
🎯 Framework Support - Works with TestNG, JUnit 5, and plain Selenium tests
🌐 Tunnel Management - Built-in support for LambdaTest Tunnel
⚙️ YAML Configuration - Simple YAML-based configuration
🚀 Zero Code Changes - Just add the agent, no changes to existing tests

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.lambdatest</groupId>
    <artifactId>lambdatest-selenium-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Add the following to your build.gradle:

dependencies {
    implementation 'io.github.lambdatest:lambdatest-selenium-java-sdk:1.0.0'
}

Add the following to your build.gradle.kts:

dependencies {
    implementation("io.github.lambdatest:lambdatest-selenium-java-sdk:1.0.0")
}

Create a lambdatest.yaml file in your project root:

# LambdaTest credentials
username: YOUR_LAMBDATEST_USERNAME
accessKey: YOUR_LAMBDATEST_ACCESS_KEY

# Browser capabilities
capabilities:
  browserName: chrome
  browserVersion: latest
  platformName: Windows 10
  
# Test configuration
testName: My Selenium Test
build: Build #1
project: My Project

The easiest way to use this SDK is with the Java agent, which automatically instruments your Selenium tests:

Maven:

mvn test -DargLine="-javaagent:/path/to/lambdatest-selenium-java-sdk-1.0.0-agent.jar"

Gradle:

./gradlew test -Djvmargs="-javaagent:/path/to/lambdatest-selenium-java-sdk-1.0.0-agent.jar"

IDE (IntelliJ IDEA / Eclipse):

Add VM option: -javaagent:/path/to/lambdatest-selenium-java-sdk-1.0.0-agent.jar

If you prefer not to use the agent, you can use the SDK programmatically:

import com.lambdatest.selenium.LambdaTestRemoteTest;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.testng.annotations.Test;

public class MySeleniumTest extends LambdaTestRemoteTest {
    
    @Test
    public void testGoogle() {
        WebDriver driver = getDriver(); // Automatically configured for LambdaTest
        
        driver.get("https://www.google.com");
        System.out.println("Title: " + driver.getTitle());
        
        // Test will be automatically marked as passed/failed
    }
}

Create lambdatest.yaml in your project root:

# Authentication (Required)
username: YOUR_USERNAME
accessKey: YOUR_ACCESS_KEY

# Or use environment variables:
# username: ${LT_USERNAME}
# accessKey: ${LT_ACCESS_KEY}

# Capabilities (Optional - will be merged with test capabilities)
capabilities:
  browserName: chrome
  browserVersion: latest
  platformName: Windows 10
  resolution: 1920x1080
  
# LambdaTest Options
ltOptions:
  build: Build #1
  project: My Project
  network: true
  video: true
  console: true
  visual: true
  
# Tunnel Configuration (Optional)
tunnel:
  enabled: true
  name: my-tunnel
  
# Grid Configuration
gridUrl: https://hub.lambdatest.com/wd/hub

You can also configure using environment variables:

• LT_USERNAME - LambdaTest username
• LT_ACCESS_KEY - LambdaTest access key
• LT_GRID_URL - Grid URL (default: https://hub.lambdatest.com/wd/hub)

This SDK supports all Selenium 4 and LambdaTest advanced capabilities. See CAPABILITIES.md for comprehensive documentation.

Selenium 4 Capabilities:

• browserName, browserVersion (alias: version), platformName (alias: platform, OS)
• driver_version (aliases: driverVersion, driver)
• selenium_version (aliases: seleniumVersion, seVersion)
• idleTimeout (alias: idle)

Test Organization:

• build, project, name

Debugging Capabilities:

• video (default: true) - Video recording
• visual (alias: debug) - Command-by-command screenshots
• network (alias: networkLogs) - Network packet capture
• console - JavaScript console logs
• verboseWebDriverLogging - Detailed Selenium logs
• network.mask - Mask network traffic for security

Environment:

• resolution - Screen resolution (e.g., "1920x1080")
• timezone - Custom timezone (e.g., "UTC+05:30")

Local Testing:

• tunnel (alias: local) - Enable Lambda Tunnel
• tunnelName (alias: localName) - Tunnel identifier

Advanced Testing Capabilities:

• autoHeal - Automatically recover from element locator failures (Learn more)
• smartWait - Automatically wait for elements to be ready (mutually exclusive with autoHeal) (Learn more)
• smartWaitRetryDelay - Delay between smartWait retries in milliseconds
• geoLocation - Simulate user location (e.g., "US", "IN") (Learn more)
• lambdaMaskCommands - Mask sensitive data in logs (e.g., ["setValues", "setCookies", "getCookies"]) (Learn more)
• networkThrottling - Simulate network conditions (e.g., "Regular 3G", "Good 4G") (Learn more)
• customHeaders - Add custom HTTP headers to all requests (Learn more)
• customDnsMap - Custom DNS mapping for testing (Learn more)
• network.full.har - Capture full HAR logs with request/response bodies (Learn more)
• lambda:userFiles (alias: userFiles) - Pre-uploaded files for testing (Learn more)

# Authentication
username: "your_username"
accesskey: "your_accesskey"

# Browser Configuration
browserName: "Chrome"
browserVersion: "latest"  # or "latest-1", "101.0", etc.
platformName: "Windows 10"

# Test Organization
build: "Selenium 4 Build"
project: "My Project"
name: "Sample Test"

# Debugging (increases test time)
video: true
visual: false
network: false
console: false
verboseWebDriverLogging: false

# Environment
resolution: "1920x1080"
timezone: "UTC+05:30"

# Performance
idleTimeout: 600
selenium_version: "4.15.0"

# Local Testing
tunnel: false
tunnelName: "my-tunnel"

# Advanced Testing Capabilities
autoHeal: false  # Note: Cannot be used with smartWait
smartWait: false  # Note: Cannot be used with autoHeal
smartWaitRetryDelay: 1000  # milliseconds
geoLocation: "US"  # Country code for geolocation testing
networkThrottling: "Regular 3G"  # Simulate network conditions
network.full.har: true  # Capture full HAR logs

# Security & Privacy
lambdaMaskCommands:  # Mask sensitive data in logs
  - setValues
  - setCookies
  - getCookies

# Custom Configuration
customHeaders:  # Add custom HTTP headers
  X-Custom-Header: "value"
  Authorization: "Bearer token"

customDnsMap:  # Custom DNS mapping
  example.com: "192.168.1.1"
  test.local: "127.0.0.1"

# File Upload (files must be pre-uploaded via LambdaTest API)
lambda:userFiles:
  - "sample.pdf"
  - "test-image.jpg"

Auto Healing - Automatically recover from element locator failures:

autoHeal: true

This feature helps tests automatically adapt when element locators change. Note: Cannot be used together with smartWait.

Smart Wait - Automatically wait for elements:

smartWait: true
smartWaitRetryDelay: 500  # Retry every 500ms

Automatically waits for elements to be ready. Note: Cannot be used together with autoHeal.

Geolocation Testing:

geoLocation: "IN"  # Simulate location from India
timezone: "Asia/Kolkata"

Network Throttling - Simulate different network conditions:

networkThrottling: "Regular 4G"
# Options: "Regular 2G", "Good 2G", "Regular 3G", "Good 3G", "Regular 4G", "LTE", "DSL", "Wifi"

Masking Sensitive Data in Logs:

lambdaMaskCommands:
  - setValues      # Hide sendKeys input
  - setCookies     # Hide cookies being set
  - getCookies     # Hide cookies being retrieved

Custom Headers for API Testing:

customHeaders:
  X-API-Key: "your-api-key"
  Authorization: "Bearer token"
  Custom-Header: "custom-value"

Custom DNS Mapping:

customDnsMap:
  internal.example.com: "192.168.1.100"
  staging.myapp.com: "10.0.0.50"

Full HAR Logs with Request/Response Bodies:

network: true
network.full.har: true

For detailed documentation with examples, see CAPABILITIES.md.

Reference Documentation:

• Selenium 4 Capabilities
• LambdaTest Advanced Capabilities

Add TestNG listener for automatic test status updates:

<!-- testng.xml -->
<suite name="LambdaTest Suite">
    <listeners>
        <listener class-name="com.lambdatest.selenium.LambdaTestStatusListener"/>
    </listeners>
    
    <test name="My Tests">
        <classes>
            <class name="com.example.MyTest"/>
        </classes>
    </test>
</suite>

Or programmatically:

@Listeners(LambdaTestStatusListener.class)
public class MyTest {
    // Your tests
}

Use the JUnit transformer with the Java agent (automatically detected).

Enable LambdaTest Tunnel for testing local/private applications:

tunnel:
  enabled: true
  name: my-tunnel
  # Additional tunnel options
  tunnelName: custom-tunnel
  verbose: true

Merge custom capabilities with configured ones:

import com.lambdatest.selenium.LambdaTestCapabilities;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
options.addArguments("--start-maximized");

// SDK will merge these with lambdatest.yaml capabilities
LambdaTestCapabilities.enhance(options);

The SDK fully supports parallel test execution:

TestNG:

<suite name="Parallel Suite" parallel="tests" thread-count="5">
    <test name="Chrome Test">
        <parameter name="browser" value="chrome"/>
        <classes><class name="com.example.Test1"/></classes>
    </test>
    <test name="Firefox Test">
        <parameter name="browser" value="firefox"/>
        <classes><class name="com.example.Test1"/></classes>
    </test>
</suite>

• Java 8 or higher
• Gradle 7.0+

# Clone the repository
git clone https://github.com/LambdatestIncPrivate/lambdatest-selenium-java-sdk.git
cd lambdatest-selenium-java-sdk

# Build the project
./gradlew clean build

# Generated artifacts will be in build/libs/
# - lambdatest-selenium-java-sdk-1.0.0.jar (main JAR)
# - lambdatest-selenium-java-sdk-1.0.0-agent.jar (agent JAR with dependencies)

For maintainers publishing to Maven Central:

# See MAVEN_CENTRAL_PUBLISHING.md for detailed instructions
./verify-setup.sh          # Verify publishing prerequisites
./gradlew publishToMavenLocal  # Test local publishing
./gradlew publishMavenJavaPublicationToOSSRHRepository  # Publish to Maven Central

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;
import java.net.URL;

public class BasicTest {
    WebDriver driver;
    
    @BeforeMethod
    public void setup() throws Exception {
        ChromeOptions options = new ChromeOptions();
        options.setCapability("platformName", "Windows 10");
        options.setCapability("browserVersion", "latest");
        
        // SDK will automatically inject LambdaTest capabilities
        driver = new RemoteWebDriver(
            new URL("https://hub.lambdatest.com/wd/hub"), 
            options
        );
    }
    
    @Test
    public void testExample() {
        driver.get("https://www.example.com");
        String title = driver.getTitle();
        System.out.println("Page title: " + title);
        assert title.contains("Example");
    }
    
    @AfterMethod
    public void teardown() {
        if (driver != null) {
            driver.quit();
        }
    }
}

import org.testng.annotations.*;

public class CrossBrowserTest {
    
    @Parameters({"browser", "version", "platform"})
    @BeforeMethod
    public void setup(String browser, String version, String platform) {
        // SDK automatically configures based on parameters
    }
    
    @Test
    public void testAcrossBrowsers() {
        // Your test code
    }
}

Issue: Driver not connecting to LambdaTest

• Verify credentials in lambdatest.yaml or environment variables
• Check your LambdaTest account has active minutes
• Ensure grid URL is correct

Issue: Java agent not working

• Verify agent JAR path is correct
• Use the -agent classifier JAR (with all dependencies)
• Check Java version compatibility (Java 8+)

Issue: Tests not marked as passed/failed

• Ensure TestNG listener is configured
• Verify driver session ID is available
• Check network connectivity to LambdaTest

Add to your test:

System.setProperty("lambdatest.debug", "true");

• Java: 8 or higher
• Selenium: 4.x (tested with 4.15.0)
• TestNG: 7.4.0+ (optional, for TestNG integration)
• JUnit: 5.10.0+ (optional, for JUnit integration)

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• 📧 Email: support@lambdatest.com
• 📚 Documentation: https://www.lambdatest.com/support/docs/
• 💬 Community: https://community.lambdatest.com/
• 🐛 Issues: GitHub Issues

• LambdaTest Platform
• LambdaTest Documentation
• Maven Central Repository

Made with ❤️ by LambdaTest