Using BrowserStack Local to Test Staging Sites Behind a Firewall

Problem: Internal Environments Are Out of Reach for Cloud‑Based Testers

When continuous‑integration pipelines run on cloud runners, they cannot reach services that live behind corporate firewalls or on localhost. Manual QA teams also struggle to test staging sites that are not publicly exposed. The result is either duplicating code in a public staging environment or exposing sensitive data to the internet.

Solution: BrowserStack Local

BrowserStack Local is a lightweight binary that establishes a secure, encrypted tunnel from your local machine (or CI runner) to BrowserStack’s cloud. Once the tunnel is up, any URL that resolves on the local network becomes reachable from the remote browser instance. Both manual and automated tests can use the same tunnel; the only difference is how you signal the tunnel in your test code.

Setting Up the Tunnel

1. Download and Run the Binary

# Linux/macOS
curl -LO https://www.browserstack.com/browserstack-local/BrowserStackLocal.zip
unzip BrowserStackLocal.zip
./BrowserStackLocal -key <YOUR_ACCESS_KEY>

# Windows (cmd)
curl -LO https://www.browserstack.com/browserstack-local/BrowserStackLocal.zip
powershell -Command "Expand-Archive BrowserStackLocal.zip -DestinationPath ."
BrowserStackLocal.exe -key <YOUR_ACCESS_KEY>

Replace <YOUR_ACCESS_KEY> with the key found in your BrowserStack account settings. The binary stays running in the background until you terminate it.

2. Verify the Tunnel Is Active

In the BrowserStack dashboard, open a new session and navigate to http://localhost:8080 (or the port your test server uses). If the page loads, the tunnel is operational. You can also view the BrowserStackLocal logs for handshake confirmation.

Automated Testing: Selenium Example

Below is a minimal JavaScript test using WebDriverIO that demonstrates how to enable the tunnel via the capabilities object. The same principle applies to Java, Python, or any language that supports Selenium.

// wdio.conf.js
exports.config = {
  runner: 'local',
  services: [],
  specs: ['./tests/*.js'],
  capabilities: [
    {
      browserName: 'chrome',
      'browserstack.local': true,            // <‑‑ enable the tunnel
      'browserstack.user': '<YOUR_USERNAME>',
      'browserstack.key': '<YOUR_ACCESS_KEY>'
    }
  ],
  // other config options omitted for brevity
};

Run the test with npx wdio wdio.conf.js. The remote Chrome instance will be able to resolve http://localhost:8080 because the browserstack.local flag tells BrowserStack to route traffic through the active tunnel.

Key Checks to Verify Success

• BrowserStack’s session page shows a green “Tunnel active” indicator.
• The test logs contain a URL request to http://localhost:8080 that completes with a 200 status.
• No “Connection refused” or DNS errors appear in the test output.

Trade‑offs and Limitations

Consideration	Impact
Latency	All traffic to the test site must travel through the tunnel, adding a few milliseconds per request. For high‑frequency API tests, this can become noticeable.
Local Resource Usage	The tunnel binary runs as a background process and consumes CPU and memory on the machine that hosts it. In CI environments, ensure the runner has enough resources.
Firewall Requirements	Outbound HTTPS (port 443) must be allowed from the machine running the tunnel to BrowserStack’s servers. In strict corporate networks, you may need to open this port or use a proxy.

When to Use BrowserStack Local

• Testing a new feature on a staging server that is not publicly exposed.
• Running end‑to‑end tests against a local development server during a sprint.
• Performing manual QA on a corporate intranet site with BrowserStack’s live testing dashboard.

Practical Checklist

1. Start the BrowserStackLocal binary before test execution.
2. Set the browserstack.local capability to true in your test configuration.
3. Verify the tunnel status in the dashboard or via logs.
4. Run your tests and monitor for latency spikes.
5. When finished, stop the binary to free resources.

By following this workflow, you can safely expose internal or local services to BrowserStack’s global device fleet without opening any ports to the public internet. The tunnel handles encryption, authentication, and routing, letting you focus on writing robust tests instead of wrestling with network configurations.