Using BrowserStack Local with Selenium Java to Test Internal Web Apps

Quick answer

To run Selenium Java tests against a site that is not publicly reachable (e.g., localhost, an internal staging server, or an intranet URL), start the BrowserStack Local binary, set the capability browserstack.local to true, and direct the WebDriver to the BrowserStack hub. The tunnel created by the binary forwards all HTTP/HTTPS traffic from the cloud VM to your machine, allowing the test to interact with the internal site as if it were public.

How it works – a minimal working configuration

1. Prerequisites

• Java 8 or newer installed.
• Maven (or Gradle) for dependency management.
• BrowserStack access key (found in your BrowserStack account settings).
• Outbound TCP 443 (HTTPS) access from the machine where the Local binary runs.

2. Add Selenium and BrowserStack dependencies

    
        org.seleniumhq.selenium
        selenium-java
        4.18.0
    
    
        com.browserstack
        browserstack-local-java
        1.0.3
    

3. Start the Local binary from your test suite

Binary location: download the appropriate BrowserStackLocal executable for your OS from BrowserStack Local and make it executable (chmod +x BrowserStackLocal on Linux/macOS).

import com.browserstack.local.Local;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;

public class LocalTest {
    private static Local local;
    private static WebDriver driver;

    public static void main(String[] args) throws Exception {
        // 1️⃣  Start the Local tunnel
        local = new Local();
        Map options = new HashMap<>();
        options.put("key", "YOUR_ACCESS_KEY"); // replace with env var or secret manager
        options.put("forcelocal", "true");
        local.start(options);

        // 2️⃣  Verify the tunnel is up (optional but recommended)
        if (!local.isRunning()) {
            throw new IllegalStateException("BrowserStack Local failed to start");
        }

        // 3️⃣  Configure Selenium capabilities
        DesiredCapabilities caps = new DesiredCapabilities();
        caps.setCapability("browser", "Chrome");
        caps.setCapability("browser_version", "latest");
        caps.setCapability("os", "Windows");
        caps.setCapability("os_version", "10");
        caps.setCapability("name", "Local Selenium Java test");
        caps.setCapability("build", "browserstack-local-demo");
        caps.setCapability("browserstack.local", "true"); // <‑‑ tells BrowserStack to route via the tunnel

        // 4️⃣  Create the RemoteWebDriver pointing to BrowserStack hub
        driver = new RemoteWebDriver(
                new URL("https://hub-cloud.browserstack.com/wd/hub"),
                caps);

        // 5️⃣  Run a simple test against an internal URL
        driver.get("http://localhost:8080/healthcheck"); // replace with your internal endpoint
        String title = driver.getTitle();
        System.out.println("Page title: " + title);

        // 6️⃣  Clean up
        driver.quit();
        local.stop();
    }
}

4. Where to run the code and required permissions

• Run the Java class on any developer workstation, CI agent, or dedicated test machine that can outbound to hub-cloud.browserstack.com:443.
• The process executing the binary needs permission to open a network socket and to execute the downloaded BrowserStackLocal file.
• Never hard‑code the access key; inject it via an environment variable (BROWSERSTACK_ACCESS_KEY) or a secrets manager and read it at runtime.

Limits and considerations

• Concurrent tunnels: Each BrowserStack account allows up to 5 simultaneous Local tunnels. Exceeding this limit will cause the binary to refuse new connections with an error like "Tunnel limit reached".
• Latency: Expect an additional 100‑200 ms round‑trip due to the tunnel hop; plan timeouts accordingly.
• Protocol support: Only HTTP and HTTPS traffic is forwarded. UDP, raw TCP, or WebSocket‑only protocols will not work.
• Binary version: Use the Local binary version that matches the BrowserStack SDK version you are using (check the compatibility matrix on the BrowserStack docs). An outdated binary may fail to establish a tunnel or miss security patches.

Common mistakes and how to avoid them

1. Forgot to start the binary or used an invalid key – The test will timeout with "net::ERR_CONNECTION_REFUSED". Verify that local.isRunning() returns true before creating the WebDriver.
2. Set browserstack.local to false – The cloud VM will try to reach the URL directly and fail. Double‑check the capability is explicitly set to true.
3. Mixed‑content (HTTP page loading HTTPS resources) – If your internal site serves HTTPS assets but the main page is loaded over HTTP, browsers may block them. Keep the scheme consistent or configure your internal server to serve everything over HTTPS.
4. Leaving the tunnel running after the suite – Orphan BrowserStackLocal processes consume a tunnel slot and may cause "Tunnel limit reached" errors on subsequent runs. Always call local.stop() in a finally block or use a shutdown hook.
5. Hard‑coding the access key in source control – Leads to accidental exposure. Use environment variables or a secret‑management tool and add the key file to .gitignore.

Verification steps

• Run a simple test that accesses http://localhost:/healthcheck on your machine. If the test passes, the Local tunnel is active.
• Watch the Local binary’s console output for lines such as "Connected to BrowserStack Local" and "Tunnel established".
• After the test suite finishes, confirm that the BrowserStackLocal process has exited (e.g., ps -ef | grep BrowserStackLocal returns no lines) or manually stop it.

Rollback

Starting the Local binary changes system state (it opens a listening socket and creates a tunnel). The rollback is simply stopping the binary via local.stop() or killing the process, which removes the tunnel and frees the slot.