Run BrowserStack Automate Tests Against Private Apps With Local Testing

Problem: tests can’t reach your internal app

Automate sessions run in BrowserStack’s cloud. Without a tunnel, a test that tries https://staging.internal.example.com will fail with DNS or connection errors. BrowserStack Local creates an outbound tunnel from your network to BrowserStack so Automate can reach private hosts as if they were public.

The useful takeaway is to keep the tunnel narrow, start it before the test run, and verify connectivity from the Automate dashboard before executing the suite. That avoids flaky failures caused by late tunnel startup or port conflicts.

Desired outcome

Start a Local tunnel on a CI runner or dev machine, run Selenium/WebDriverIO tests against an internal URL through the tunnel, and confirm requests reach your private server logs.

Prerequisites

• BrowserStack account with Automate access and an access key from Account Settings.
• Node.js ≥14 on the machine that will start the tunnel.
• BrowserStack Local binary installed via npm or direct download. Run browserstack-local --version in a terminal to confirm installation. Match the binary version to what your project documents; mismatched CLI and binary versions can cause authentication errors or silent failures.
• Outbound network access to bs-local.com on port 443 allowed by firewall.

Start the Local tunnel

Run the binary where your tests will execute. In CI this is typically the same job step as the test runner, with permissions to read the access key from environment variables.

browserstack-local --key <YOUR_ACCESS_KEY> --only-automate

Placeholders: replace <YOUR_ACCESS_KEY> with your BrowserStack key. --only-automate restricts the tunnel to Automate sessions, reducing latency for CI pipelines. Avoid running multiple Local instances with the same access key on overlapping ports; this can lead to port conflicts and dropped connections.

Risk: the tunnel holds an open outbound connection. If the process is killed without a clean stop, the previous tunnel may remain active on BrowserStack’s side. Use --force to override an existing tunnel when you need to replace a stale one.

Point your test runner through the tunnel

Configure WebDriver capabilities to use BrowserStack Automate and target the internal host via localhost. The tunnel maps your private host to a BrowserStack-routed address.

capabilities: {
  browserName: 'chrome',
  browserVersion: 'latest',
  'bstack:options': {
    local: true,
    userName: process.env.BROWSERSTACK_USERNAME,
    accessKey: process.env.BROWSERSTACK_ACCESS_KEY
  }
}

// Test URL points to your internal app
await browser.url('https://staging.internal.example.com/login')

For Selenium, the hub URL remains https://hub-cloud.browserstack.com/wd/hub. The local flag tells Automate to route traffic through the active tunnel.

Verify the tunnel is working

• Check Local stdout for the connection message indicating the tunnel is up, and ensure no error messages appear before test execution.
• Open the BrowserStack Automate dashboard and look for the Local Testing indicator turning green for the session.
• Execute a simple test that accesses an internal endpoint and assert the response. Check your internal server logs for incoming connections from BrowserStack IPs to confirm requests are reaching the private server.

Limitation: Local tunnels only forward HTTP/HTTPS traffic. Services requiring custom protocols, VPN-only routing, or host-based authentication beyond the tunnel will need additional network configuration.

Recovery options

If the tunnel disconnects during a run, restart the Local binary with the same key. In CI, add a retry step that kills any existing process and relaunches with --force.

If tests report timeouts, verify firewall rules allow outbound 443 to bs-local.com and that no other Local instance is using the same key and port.

To stop the tunnel cleanly, send SIGTERM to the Local process. This releases the tunnel on BrowserStack’s side and avoids orphaned sessions.