Using BrowserStack Local to Test Internal Sites Without Exposing Them

The Problem: Testing Internal Sites in Cloud Browser Farms

When you run automated cross‑browser tests on BrowserStack, the remote browsers need a public URL to reach the application under test. Most development work, however, happens on localhost or behind a corporate firewall, creating a gap: the cloud browsers cannot resolve those addresses.

How BrowserStack Local Creates a Tunnel

BrowserStack Local is a lightweight binary that opens an outbound connection from your machine to the BrowserStack cloud. Once the tunnel is active, the cloud tells the remote browser to forward requests for specific hostnames through that tunnel to your local network.

Connection Options

• Standalone Binary: Download the executable, run it with your access key. Good for quick checks or CI jobs.
• Node.js Wrapper: Install the browserstack-local npm package and start/stop the tunnel from within your test script.
• Java Library: Add the browserstack-local-java dependency and control the tunnel programmatically in JVM‑based frameworks.

Worked Example: Testing a Local React App

Assume you have a React development server running at http://localhost:3000 and you want to run a Selenium test against Chrome on BrowserStack.

1. Start the Tunnel

On the machine that hosts the React server (or any host that can reach it), run:

./BrowserStackLocal --key YOUR_ACCESS_KEY

Look for the line Connected to BrowserStack in the terminal output. If you see an error, verify that outbound TCP traffic to the BrowserStack tunnel ports (typically 443, 80) is allowed by your firewall.

2. Configure WebDriver Capabilities

In your test script, set the browserstack.local capability to true so the cloud knows to use the tunnel.

// Example using Selenium/WebDriverJS
const capabilities = {
  'browserName': 'Chrome',
  'browserVersion': 'latest',
  'browserstack.local': 'true',
  'browserstack.user': 'YOUR_USERNAME',
  'browserstack.key': 'YOUR_ACCESS_KEY'
};

3. Run the Test

Navigate to the local address exactly as you would locally:

driver.get('http://localhost:3000');

The remote Chrome browser will resolve localhost:3000 through the tunnel to your machine.

Trade‑off: Force‑Local Mode

By default, only traffic matching the hostname you are testing (e.g., localhost) goes through the tunnel. Third‑party assets hosted on public CDNs are fetched directly from the internet, which keeps page load times low.

If your application depends on internal APIs or static assets on other internal servers, you can add the --force-local flag when starting the tunnel. This forces all traffic to route via your machine.

Mode	Traffic Route	Performance Impact	Typical Use Case
Default	Tested hostname via tunnel; other hosts via public web	Lower latency	Standard development testing with public CDNs
Force‑Local	All traffic via local tunnel	Higher latency, depends on your uplink	Strict corporate networks or when all dependencies are internal

Limitation: Added Latency and How to Measure It

Because every request must travel from the BrowserStack cloud, through the tunnel, to your local machine, and back, you will notice higher round‑trip times compared with a public staging server. This can cause:

• Increased chance of timeout‑based flakiness in tests.
• Slower page load when large images, videos, or bundles are served via the tunnel.

Practical verification: Create two tiny test pages: one with just <h1>Hello</h1> and another that loads a 2 MB image or a large CSS bundle. Run the same test against both pages and compare the reported load time (e.g., using performance.now() in the browser or the network tab). If the heavy page consistently exceeds your timeout while the light page passes, increase implicit or explicit wait times in your WebDriver configuration, or consider moving heavy assets to a public CDN for the test run.

Cleaning Up the Tunnel

The tunnel consumes a socket and a small amount of CPU while it runs. Always stop it after your test suite finishes.

• With the standalone binary, press Ctrl+C in the terminal or send a SIGTERM (kill) to the process.
• With the Node.js wrapper, call local.stop() in an afterAll hook.
• With the Java library, invoke local.stop() in your test teardown.

After stopping, verify that the process no longer appears in your process list (ps aux | grep BrowserStackLocal on Unix or Task Manager on Windows).