Using BrowserStack Local Testing to Run Cross‑Browser Tests on a Staged Server Behind a Firewall

Goal

Expose a localhost or staging server that sits behind a firewall or NAT to BrowserStack’s remote browsers so that your automated tests can run against the real environment rather than a public URL.

Prerequisites

• BrowserStack account with Automate access (any tier). Free tier allows one concurrent tunnel.
• Local server running on an IP/port accessible from the machine that will launch the tunnel.
• Node.js (or any language) and npm if you plan to run a test framework such as Cypress or WebDriverIO.
• Environment variables set for BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY or a ~/.browserstackrc file.
• Download the BrowserStack Local binary for your OS from BrowserStack Local.

Setup Steps

1. Verify binary version
   

   browserstack-local --version

   Check that the output matches the version shown in the BrowserStack Automate dashboard under Local Testing.

2. Start the local tunnel
   

   browserstack-local --key $BROWSERSTACK_ACCESS_KEY --verbose

   Run this command on the machine that hosts your local server. The --verbose flag prints connection state and helps debug failures.

3. Configure your test framework
   

   Below is a Cypress example. Add the following to cypress.json:

   {
     "baseUrl": "http://localhost:3000",
     "browserstack": {
       "local": true,
       "browser": "chrome",
       "browser_version": "latest",
       "os": "Windows",
       "os_version": "10"
     }
   }

   The local: true flag tells BrowserStack to route traffic through the tunnel.

4. Run tests from CI
   

   Example Jenkins pipeline step:

   stage('Run Tests') {
     sh 'browserstack-local --key $BROWSERSTACK_ACCESS_KEY && npm run test:ci'
   }

   Ensure the tunnel is started before the test command and stopped afterward.

Verifying Connectivity

• On the BrowserStack dashboard, open the Local tab. The tunnel should show as Active and list the hostname you provided.
• In the test logs, look for entries similar to:
  

  Using tunnel: https://.browserstack.com

• Navigate to the test URL in a remote browser (e.g., https://.browserstack.com/your-app) and confirm the page loads.

Common Pitfalls & Recovery

• Binary‑Dashboard mismatch
  

  If the tunnel refuses to connect, run browserstack-local --version and compare to the dashboard. Download the latest binary if they differ.

• Firewall blocks outbound ports
  

  BrowserStack Local uses port 443 for HTTPS. Ensure outbound traffic to *.browserstack.com on port 443 is allowed.

• Free tier timeouts
  

  Sessions may drop after ~30 min of inactivity. Add a keep‑alive ping or run tests in batches to avoid this.

• Tunnel restart
  

  When a tunnel disconnects, simply stop the binary and restart it. In CI, wrap the start/stop in a try/finally block to guarantee cleanup.

Limits & Considerations

• Free tier: one concurrent tunnel, 30 min idle timeout. Paid plans increase concurrent tunnels and remove idle limits.
• Only HTTP/HTTPS/TCP are supported. WebSocket traffic requires a separate configuration flag (--ws).
• The tunnel URL is unique per session; do not hard‑code it in test scripts. Use environment variables or the browserstack.local capability instead.
• Security: the tunnel exposes your local server to BrowserStack’s infrastructure. Restrict access to trusted IP ranges if possible.

By following this guide you can reliably run cross‑browser tests against a protected staging environment, ensuring that your CI pipeline reflects real‑world user interactions.