Testing Internal Services with BrowserStack Local: A Practical Guide

Why you need a tunnel for internal testing

When your application lives behind a corporate firewall or only runs on localhost, standard BrowserStack cloud VMs cannot reach it. Exposing the service to the public internet is often undesirable for security or compliance reasons. BrowserStack Local solves this by creating a secure tunnel that forwards traffic from the cloud VMs to your machine’s local network, letting you run automated tests against internal endpoints without opening them to the world.

How BrowserStack Local works

The Local feature is a lightweight binary you download from BrowserStack. When you start it with your account’s access key, it opens an outbound connection to BrowserStack’s tunnel servers. Those servers then act as a relay: any request the cloud VM makes to http://localhost or an internal hostname is forwarded through the tunnel to your machine, where it is resolved by your local DNS and network stack. The tunnel preserves HTTP headers, cookies, and works for both HTTP and HTTPS.

Setting up the tunnel

1. Download the binary – From your BrowserStack Automate dashboard, choose “Local Testing” and download the appropriate binary for your OS (macOS, Linux, or Windows).
2. Make it executable (Linux/macOS):

   chmod +x BrowserStackLocal

3. Run the tunnel – Replace YOUR_ACCESS_KEY with the key found in your account settings. Run the command in a terminal where you have outbound internet access:

   ./BrowserStackLocal --key YOUR_ACCESS_KEY

   The binary will print logs and, once connected, show a line like Connected. LocalTesting identifier: xxxxxx.

Where to run it: On any developer workstation, CI agent, or dedicated test machine that can reach the internal service you want to test. No special privileges are required beyond the ability to execute the binary and open outbound TCP connections to BrowserStack’s tunnel endpoints (typically port 443).

Risks to consider: If your network blocks outbound connections to those endpoints, the tunnel will fail to start. You’ll need to work with your network team to allow traffic to bs-local.com or the specific IP ranges listed in BrowserStack’s documentation.

Running a test against localhost

Once the tunnel shows “Connected”, you can point your automated tests at http://localhost:<port> just as if the service were publicly accessible. Below is a minimal Selenium Java example that verifies a simple internal page.

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;

public class LocalTest {
    public static void main(String[] args) throws Exception {
        // BrowserStack hub URL
        URL hubUrl = new URL("https://hub-cloud.browserstack.com/wd/hub");

        // Desired capabilities – adjust browser/version as needed
        Map caps = new HashMap<>();
        caps.put("browserName", "Chrome");
        caps.put("browserVersion", "latest");
        Map bstackOptions = new HashMap<>();
        bstackOptions.put("userName", "YOUR_BROWSERSTACK_USERNAME");
        bstackOptions.put("accessKey", "YOUR_ACCESS_KEY");
        bstackOptions.put("local", true); // tells BrowserStack to use the tunnel
        caps.put("bstack:options", bstackOptions);

        WebDriver driver = new RemoteWebDriver(hubUrl, caps);
        try {
            driver.get("http://localhost:8080/my-internal-app");
            String title = driver.getTitle();
            System.out.println("Page title: " + title);
            // Simple assertion – adjust to your app
            if (!title.contains("Expected Title")) {
                throw new AssertionError("Unexpected title");
            }
        } finally {
            driver.quit();
        }
    }
}

Where to run the test: On any machine that can reach the BrowserStack hub (public internet) and has the Java SDK and Selenium bindings installed. The test itself does not need to be on the same machine as the tunnel, but the tunnel must be running somewhere in the network so the cloud VM can reach localhost:8080.

How to verify it worked:

• Check the terminal where you started BrowserStackLocal – you should see a steady “Connected” status and request/response logs as the test runs.
• In the BrowserStack Automate dashboard, the session will show a green “Connected” indicator under the Local Testing section.
• If the test passes, you know the tunnel successfully forwarded the request to your internal service.

Trade‑offs and limitations

• Latency: Each request incurs an extra hop through the tunnel, typically adding 10‑30 ms. For most functional tests this is negligible, but performance‑sensitive benchmarks may need to account for it.
• Proxy or firewall restrictions: Strict outbound rules can block the tunnel. You must allow traffic to BrowserStack’s tunnel servers (see their IP list) or configure the binary to use an HTTP proxy with the --proxy-host and --proxy-port flags.
• Binary updates: BrowserStack periodically releases new versions of the Local binary. Using an outdated version can lead to connection failures; check the dashboard for version notifications and replace the binary when prompted.

Actionable next steps

1. Sign up for a free BrowserStack trial (if you don’t already have an account).
2. Download the Local binary for your OS from the Automate dashboard.
3. Start the tunnel with your access key and verify the “Connected” message appears.
4. Run a simple test like the Selenium example above against http://localhost:<port>.
5. Monitor latency in your test logs; if it exceeds your comfort threshold, consider running performance‑critical tests directly on a local grid instead of through the tunnel.

By following these steps you can safely validate internal features, staging branches, or microservices without exposing them to the public internet, keeping your testing workflow both secure and efficient.