Choosing the right BrowserStack Local Testing mode for CI pipelines

Decision and constraints

Enable BrowserStack Local Testing to securely test internal web applications (running on localhost, a staging server, or any private network) from a CI/CD pipeline without exposing those applications to the public internet.

To use this feature you need:

• A BrowserStack account that includes the Automate or Live product.
• The BrowserStack Local binary (bs-local) installed on the CI runner.
• Outbound network access from the runner to bs-local.com on ports 443 and 80.
• A valid BrowserStack access key (treated as a secret).
• Selenium or Appium client bindings compatible with the binary version.

Options comparison

Option	Description	When to use	Pros	Cons
bs-local --key (default)	Creates a tunnel that forwards only traffic matching the test session’s hostname/port.	You want the simplest setup and are confident no other outbound traffic from the runner will use the tunnel.	Minimal configuration; lowest latency for test traffic.	Non‑test outbound connections (e.g., dependency downloads) may bypass the tunnel and reach the public internet, potentially leaking internal details.
bs-local --key --force-local	Forces all outbound TCP traffic from the runner through the Local tunnel.	You need strict isolation, ensuring no traffic escapes the tunnel (e.g., in highly regulated environments).	Guarantees that every outbound request is routed via BrowserStack, eliminating accidental exposure.	Adds latency because all traffic (including package managers, DNS lookups) traverses the tunnel; may affect CI performance.
bs-local --key --only-automate	Limits the tunnel to traffic generated by BrowserStack Automate sessions only; Live/manual sessions are blocked.	You run only Automate tests in CI and want to reduce tunnel overhead.	Lower overhead; Live sessions cannot accidentally consume the tunnel.	If you later need Live debugging or manual exploratory testing, the tunnel must be restarted without --only-automate.

Trade‑offs summary

• Default mode is easiest but relies on the test framework to limit traffic; accidental leaks are possible.
• --force-local provides the strongest isolation at the cost of increased latency and potential bandwidth consumption.
• --only-automate reduces overhead for pure Automate pipelines but excludes Live/manual use.

Implementation example

The steps below assume a Linux‑based CI runner with bash and curl available. Adjust paths and permissions for your environment.

1. Download and prepare the binary (run as the CI user, no special privileges needed):

   # Replace VERSION with the latest release noted in BrowserStack docs
   curl -fsSL -o bs-local.zip "https://www.browserstack.com/browserstack-local/BrowserStackLocal-linux-x64.zip"
   unzip bs-local.zip
   chmod +x bs-local
   

2. Start the tunnel with the chosen mode. Example using --force-local for maximum isolation:

   # Run in background; store the PID for later cleanup
   ./bs-local --key "${BROWSERSTACK_ACCESS_KEY}" --force-local --local-identifier "ci-tunnel-${CI_JOB_ID}" &
   BS_LOCAL_PID=$!
   # Optional: wait a few seconds for the tunnel to establish
   sleep 5
   

3. Configure your test suite to enable the Local capability. For a Selenium Java test:

   DesiredCapabilities caps = new DesiredCapabilities();
   caps.setCapability("browserstack.local", true);
   caps.setCapability("browserstack.user", "YOUR_BROWSERSTACK_USERNAME");
   caps.setCapability("browserstack.key", "${BROWSERSTACK_ACCESS_KEY}");
   // … other capabilities
   WebDriver driver = new RemoteWebDriver(new URL("https://hub-cloud.browserstack.com/wd/hub"), caps);
   

4. Run your tests as usual. The binary will forward requests to internal hosts (e.g., http://internal-app:3000) through the tunnel.
5. Clean up after the job finishes:

   kill $BS_LOCAL_PID 2>/dev/null || true
   

Validation and practical checks

After the tunnel starts, verify it is ready before executing tests:

• Log check – run the binary with the verbose flag (-v) and look for the line:

  Connected to BrowserStack Local successfully

  If this line does not appear, the tunnel failed to establish.
• Dashboard check – In the BrowserStack Automate UI, open the session details and confirm that the capability browserstack.local is set to true. The session logs should show requests to your internal host (e.g., GET http://internal-app:3000/health).
• Endpoint test – Include a simple step in your test suite that requests a known internal URL and asserts a successful response:

  Response resp = given().get("http://internal-app:3000/health");
  assertThat(resp.getStatusCode()).isEqualTo(200);
  

  A non‑200 response indicates the tunnel is not routing correctly.

Limitations and how to mitigate them

• Binary version mismatch – Using an outdated bs-local can cause intermittent disconnects. Always download the binary version recommended for your SDK release (check the BrowserStack documentation).
• Concurrent tunnel limit – Most accounts allow a limited number of simultaneous Local tunnels (commonly 5). If you exceed this, new tunnel start requests are rejected with an error like "Tunnel limit exceeded". Mitigate by re‑using a single tunnel across multiple jobs or by queuing tunnel start calls.
• Network restrictions – Firewalls or corporate proxies that block outbound connections to bs-local.com on ports 443/80 will prevent the tunnel from starting. Ensure outbound rules allow these destinations, or configure the binary to use an HTTP proxy via the --proxy-host and --proxy-port flags if your environment requires it.