BrowserStack Selenium Integration: Run Java Tests on the Cloud

You already have Selenium tests that pass on your laptop. Now you need them on Safari, older Windows browsers or a real phone you do not own. BrowserStack hosts those browsers and devices, and its Java setup lets your existing tests run there with one config file and almost no code changes. This tutorial walks through that setup for a Maven project, then covers parallel runs, private staging sites, CI and debugging. Every setting name below comes from BrowserStack's public Selenium with Java guide, read on 27 October 2026. New to the tool itself? Read our BrowserStack review first.

• A BrowserStack account with your username and access key. Both are shown in your account profile.
• JDK 11 or newer, Maven 3.6 or newer and Selenium 4.23 or newer. These are the minimums BrowserStack lists for its Java setup. Gradle is also supported.
• A working Selenium test that passes locally. If you need a refresher, start with our Selenium WebDriver guide.

Fix flaky local tests before you move them. A cloud adds network distance, so weak waits fail more often there, not less.

Locally, Selenium starts a browser on your machine. On BrowserStack, the browser runs on their machines and your test talks to it over the internet. The BrowserStack Java SDK handles that switch: it reads browserstack.yml, creates a remote session for each platform you list, and passes your credentials. Your test still creates a normal WebDriver, so page objects, assertions and test runners stay the same.

The quickest way to see a working setup is BrowserStack's sample project, which you can download from the guide and open in IntelliJ IDEA or Eclipse. For a fresh Maven project, the guide gives an archetype command that creates one with the SDK already wired in:

mvn archetype:generate -B -DarchetypeGroupId=com.browserstack \
  -DarchetypeArtifactId=browserstack-sdk-archetype-setup -DarchetypeVersion=1.1 \
  -DgroupId=com.browserstack -DartifactId=vanilla-java-browserstack -Dversion=1.0 \
  -DBROWSERSTACK_USERNAME=YOUR_USERNAME -DBROWSERSTACK_ACCESS_KEY=YOUR_ACCESS_KEY \
  -DBROWSERSTACK_PROJECT_REPO=vanilla-java-browserstack
cd vanilla-java-browserstack

For an existing project, follow the "integrate your test suite" path in the same guide, which adds the SDK dependency to your pom.xml. Check the guide for the current SDK version rather than copying an old one from a blog post.

The file lives in the project root. This is a small, readable starting point using setting names from BrowserStack's capabilities reference:

# browserstack.yml
userName: YOUR_USERNAME
accessKey: YOUR_ACCESS_KEY
framework: testng

platforms:
  - os: Windows
    osVersion: 11
    browserName: Chrome
    browserVersion: latest
  - os: OS X
    osVersion: Monterey
    browserName: Safari
    browserVersion: 15.6
  - deviceName: iPhone 13
    osVersion: 15
    browserName: safari

parallelsPerPlatform: 1

projectName: Shop regression
buildName: smoke
buildIdentifier: '${BUILD_NUMBER}'

browserstackLocal: false
debug: false
networkLogs: false
consoleLogs: errors

A few notes:

• platforms is the list of browsers and devices. Use the platform picker in the guide to get exact names.
• projectName and buildName group runs on the dashboard. buildIdentifier adds a counter or timestamp to each run so builds don't merge.
• debug takes a screenshot for every Selenium command. Useful while you investigate, slow for daily runs.

A normal TestNG test is enough. The SDK swaps the local driver for a cloud session at run time:

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.testng.Assert;
import org.testng.annotations.*;
import java.time.Duration;

public class SearchTest {
  private WebDriver driver;

  @BeforeMethod
  public void setUp() {
    driver = new ChromeDriver(); // the SDK routes this to BrowserStack
  }

  @Test
  public void searchShowsResults() {
    driver.get("https://example.com");
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    wait.until(ExpectedConditions.titleContains("Example"));
    Assert.assertTrue(driver.findElement(By.tagName("h1")).isDisplayed());
  }

  @AfterMethod
  public void tearDown() {
    if (driver != null) driver.quit();
  }
}

Use explicit waits, never fixed sleeps. Our guide to implicit, explicit and fluent waits explains why this matters even more on a remote browser.

mvn test

Each platform in your file gets its own session. Open the Automate dashboard and you will see the build name you set, with one row per session, each with video, screenshots and logs. If nothing appears, check the credentials first; a typo in the access key is the most common first-run problem.

parallelsPerPlatform sets how many threads run for each platform. BrowserStack's reference gives the arithmetic: three platforms with parallelsPerPlatform: 2 uses six parallel threads, and one platform with a value of 5 uses five. Your plan decides how many sessions can run at once; anything above that waits in a queue.

Parallel runs only help if tests are independent. Each test should create its own data and never rely on another test running first. Shared logins and shared carts are the usual reasons a suite passes one at a time and fails in parallel.

Cloud browsers can't see localhost or a staging server behind your company network. Set browserstackLocal: true and the SDK opens a BrowserStack Local tunnel for the run. The capabilities reference also lists browserStackLocalOptions for proxies, forcing all traffic through the tunnel (forcelocal) and naming tunnels when several run at once (localIdentifier).

browserstackLocal: true
browserStackLocalOptions:
  forcelocal: false
  localIdentifier: ci-run

Self-hosting instead? Our Selenium Grid 4 Docker guide shows the in-house alternative.

Never commit a real access key. Leave placeholders in browserstack.yml and supply the values from your CI's secret store as environment variables. BrowserStack's setup uses the names BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY. A GitHub Actions job then looks like this:

# .github/workflows/browserstack.yml
name: BrowserStack smoke
on: [push]
jobs:
  smoke:
    runs-on: ubuntu-latest
    env:
      BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
      BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '17'
      - run: mvn -B test

Check the guide's CI section for how your SDK version reads these variables, then rotate the key if it was ever committed.

Some teams prefer to manage the remote session themselves, for example inside an existing driver factory. Selenium 4 sends vendor options under a namespaced capability, which for BrowserStack is bstack:options:

MutableCapabilities bstack = new MutableCapabilities();
bstack.setCapability("os", "Windows");
bstack.setCapability("osVersion", "11");
bstack.setCapability("buildName", "smoke");
bstack.setCapability("userName", System.getenv("BROWSERSTACK_USERNAME"));
bstack.setCapability("accessKey", System.getenv("BROWSERSTACK_ACCESS_KEY"));

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("latest");
options.setCapability("bstack:options", bstack);

// Use the hub address from BrowserStack's current Selenium guide
WebDriver driver = new RemoteWebDriver(new URL(System.getenv("BROWSERSTACK_HUB_URL")), options);

This gives you full control, but you lose the SDK's automatic parallel runs and tunnel handling. Keeping the hub address in an environment variable also means the same factory can point at a local Grid.

1. Open the failed session on the dashboard and watch the video around the failing step.
2. Read the Selenium log to see the exact command that failed.
3. Turn on networkLogs: true for failed API calls or missing files, and raise consoleLogs to warnings or info for front-end errors.
4. Use debug: true only while investigating; it adds a screenshot per command.
5. Re-run just that test locally with the same browser version before changing code.

If the same test fails only on one platform, it is usually a real browser difference worth a bug report. If it fails randomly on all of them, look at waits and test data.

Stuck on something else? Ask in the QA Community, where testers share real setups.