Local Testing FAQs

Choose one of the following options based on the product and operating system you use:

• Local desktop app: Works on Windows and macOS. Use the app for Live and App Live.
  1. Download, install, and launch the Local desktop app.
  2. Start a Live or App Live session. The Local desktop app connects automatically.
  3. If the connection fails or your URL doesn’t open, go to the Local Console at http://localhost:45454. Follow the steps in Configure the Local desktop app.
• Local binary: Works across all operating systems. Use the binary for Automate and App Automate, and for Live and App Live on Linux, where the desktop app isn’t available.
  1. Download the binary for your OS from Releases and downloads.

  2. Run the binary from the command line with your access key:

     ./BrowserStackLocal --key YOUR_ACCESS_KEY
     

     On Windows, run BrowserStackLocal.exe --key YOUR_ACCESS_KEY instead.

  3. In your automated tests, set the browserstack.local capability to true. If you use a browserstack.yml file, set browserstackLocal: true instead.

  To customize the connection, such as when routing traffic through a proxy, add the flags for Local.

Yes. Local Testing reaches any server that your machine can reach, including servers behind a VPN or a firewall.

1. Confirm that you can open the private server from a browser on your machine. If the server is behind a VPN, connect to the VPN first.
2. On the same machine, start the Local desktop app or Local binary.
3. In your BrowserStack session, open the same private server URL that you use on your machine.

If your machine connects to the internet through a corporate proxy, provide the proxy details to the binary using the --proxy-host and --proxy-port flags, or use a PAC file. To make sure all requests go through your machine instead of the public internet, add the --force-local flag.

For more information, see How Local Testing works.

Yes. After Local Testing is connected, open each site in the remote browser using the same hostname you use on your machine, for example, http://site-a.local and http://site-b.local. You don’t need a separate connection for each site.

Local Testing resolves hostnames from your machine. Any virtual host that opens in your local browser opens in the BrowserStack session, including hosts in your hosts file.

To limit which hosts are routed through the Local connection, use the --include-hosts or --only flags.

No. IP Geolocation and Local Testing can’t run in the same session. IP Geolocation routes your traffic through a different country, which conflicts with the Local connection. When you set an IP location, BrowserStack automatically disables Local Testing for that session.

To test both scenarios, run your Local Testing and IP Geolocation tests in separate sessions.

Local Testing carries HTTP and HTTPS traffic. Raw TCP socket requests fail for the following reasons:

• They don’t follow the HTTP request structure that the Local connection expects.
• They try to connect to your application directly over the internet instead of through the Local connection. If your application isn’t publicly accessible, as is common in local development, the connection fails.

To test your application with Local Testing, make sure it communicates over HTTP or HTTPS. If your application is publicly discoverable but restricted by IP address, you can also use IP whitelisting.

Yes. With IP whitelisting, BrowserStack accesses your server directly through a fixed set of IP addresses that your network administrator whitelists. Your test traffic doesn’t pass through the Local binary or the Local desktop app.

IP whitelisting works only for servers that are publicly discoverable, such as private.example.com, but restricted by IP address.

For details on how the connection works, see Inbound IP Whitelisting.

The number of IP addresses you need to whitelist depends on the type of access you choose:

• Shared IP whitelisting: You whitelist the IP addresses of BrowserStack’s entire shared fleet.
• Dedicated IP whitelisting: BrowserStack allocates a dedicated machine that connects only to your network, reducing the number of IP addresses you need to whitelist.

BrowserStack shares the list of IP addresses with your organization when you set up the feature.

No. IP whitelisting can’t reach localhost or other parts of your network that aren’t publicly discoverable. To test these, use the Local binary or the Local desktop app.

IP whitelisting takes priority by default. To route your session through the Local binary instead, explicitly enable Local Testing in your test configuration in one of the following ways:

• In your capabilities, set browserstack.local to true.
• In your browserstack.yml file, set browserstackLocal: true.

IP whitelisting is an Enterprise feature. If you have an Enterprise plan, contact support to enable it and get the IP addresses to whitelist. Otherwise, contact sales.

Safari on macOS and iOS has known issues with opening URLs that contain localhost. To fix this, try the following options:

• Use your machine’s IP address instead of localhost: Keep the same port and path. For example, change http://localhost:3000/login to http://192.168.1.10:3000/login.
• Use a supported port: Older Safari versions accept only specific ports. To check whether your port is supported, see Which ports can I use to test my local or private server?.
• On iOS 10 and later, use bs-local.com: See Why does localhost change to bs-local.com in my session?.

If the issue persists, contact support.

On all browsers except Safari 8 to 11, you can use any port.

On Safari 8 to 11 on macOS and iOS, run your local server on one of the following ports:

22, 80, 81, 443, 1010, 1111, 1185, 1201, 1234, 1313, 1337, 1400, 1534, 1535, 1776, 1859, 1999, 2000, 2016, 2022, 2100, 2101, 2104, 2222, 3000 to 3012, 3020, 3025, 3030, 3039, 3050, 3090, 3093, 3099, 3100, 3128, 3200, 3300, 3306, 3330, 3333, 3334, 3335, 3535, 3621, 3778, 3791, 4000, 4001, 4002, 4003, 4018, 4021, 4040, 4100, 4200, 4201, 4202, 4203, 4207, 4209, 4211, 4232, 4242, 4250, 4300, 4400, 4443, 4444, 4500, 4502, 4503, 4567, 4568, 4600, 4702, 5000, 5001, 5002, 5003, 5005, 5006, 5010, 5015, 5020, 5026, 5050, 5051, 5200, 5250, 5443, 5500, 5501, 5502, 5757, 5790, 6006, 6007, 6009, 6010, 6060, 6080, 6567, 7000, 7001, 7005, 7009, 7071, 7072, 7152, 7200, 7443, 7456, 7774, 7777, 8000, 8001, 8002, 8003, 8004, 8005, 8007, 8008, 8011, 8020, 8031, 8050, 8063, 8070, 8080 to 8092, 8096, 8100, 8101, 8103, 8108, 8443, 8500, 8686, 8760, 8800, 8848, 8887, 8888, 8889, 8890, 8899, 9000 to 9100, 9200 to 9400, 9601, 9606, 9876, 9877, 9880, 9898, 9900 to 9999, 10000, 10002, 10039, 10358, 11085, 12001, 13000, 13260, 14357, 19006, 22081, 25600, 31033, 31832, 33995, 38946, 40080, 40980, 43500, 43501, 44300, 44303, 44304, 44305, 44307, 44313, 44322, 44323, 44327, 44332, 44335, 44343, 44344, 44345, 44346, 44358, 44359, 44368, 44373, 44382, 44398, 45454, 49190, 49660, 49772, 50208, 50291, 50425, 51528, 53124, 53541, 54134, 54136, 54457, 55555, 55595, 55739, 56978, 59353, 60778, 63342, 64000, 64900, 65508

If your port isn’t listed, switch your server to a listed port before you test on these Safari versions.

Safari on iOS 10 and later doesn’t support http://localhost. When Local Testing is enabled, BrowserStack automatically replaces localhost with bs-local.com, which points to your machine. For example, http://localhost:3000/login opens as http://bs-local.com:3000/login.

• Manual testing: If localhost doesn’t open, or the URL doesn’t change automatically, enter bs-local.com in place of localhost yourself.
• Automated testing: If API calls to a localhost endpoint fail, update those endpoints to use bs-local.com.

If your machine uses a proxy server, add bs-local.com to your proxy bypass list so requests reach your local server.

Remote Safari on iOS 10 and later can’t fetch assets that use absolute localhost URLs. To load your assets, follow these steps:

1. Change the asset URLs in your code to relative paths by removing prefixes such as http://localhost, https://localhost, 127.0.0.1, http://127.0.0.1, and https://127.0.0.1.

   For example, change https://localhost/assets/style.css to /assets/style.css.

2. Reload the page in your Safari session.
3. To confirm that the assets load, open the same page in Chrome on an Android device from the Live dashboard.

If the assets still don’t load, contact support.

BrowserStack shows Local Testing as connected only after the Local desktop app connects to the BrowserStack backend. A running app is not enough. To find what blocks the connection, follow these steps:

1. Open the Local Console at http://localhost:45454.
   • If you see the connection dashboard, the app is connected. Go to step 3.
   • If you see an Unable to connect error, your network blocks the connection. Go to step 2.
2. Configure the app for your network, then retry the connection:
   • If your network uses a proxy, enter the proxy host, port, and credentials in the Local Console. For a PAC file, enter its path instead.
   • If your proxy uses SSL inspection, disable SSL inspection for BrowserStack Local, or ask your network administrator to exclude *.browserstack.com.

   For detailed steps, see Configure the Local desktop app.

3. Make sure the access key in the Local Console belongs to the BrowserStack account that you use to start your session.
4. Make sure no other process uses ports 45690 and 45691, which BrowserStack Local needs. An older version of the app, another user’s instance on the same machine, or a different program can occupy these ports. To check and fix each case, see Troubleshoot the Local desktop app.
5. If you upgraded from an older version of the app, check your Applications folder and uninstall any older version that is still there.
6. Restart the Local desktop app and start a new session.

If BrowserStack still doesn’t detect the app, contact support.

The spawn ETXTBSY error occurs when more than one copy of the Local binary exists in the same location and your test tries to start a copy that is already in use. To resolve this error, configure your tests to use a single binary by following these step:

1. Download the Local binary for your OS from Releases and downloads and save it to a fixed location.

2. This step applies to the browserstack-local Node.js package. In bsLocalArgs, set binarypath to the absolute path of the binary, along with your access key:

   const bsLocalArgs = {
     key: 'YOUR_ACCESS_KEY',
     binarypath: '/absolute/path/to/BrowserStackLocal'
   };
   

3. Run your tests again.

If you need to run several Local connections at the same time, assign a unique name to each connection using the --local-identifier flag.

These errors mean your network uses SSL inspection, which replaces the certificates that BrowserStack Local relies on to connect securely. Use one of the following solutions:

• Bypass BrowserStack: Ask your network administrator to exclude *.browserstack.com from SSL inspection.
• Disable SSL inspection: Turn off SSL inspection for BrowserStack Local traffic.

• Trust your root certificate on Windows: Provide your organization’s root CA certificate to the Local binary as a .pem file.

  In your browserstack.yml file:

  browserstackLocal: true
  browserStackLocalOptions:
    -use-ca-certificate: <PEM_file_abs_path>
  

  From the command line:

  ./BrowserStackLocal --key YOUR_ACCESS_KEY --force-local --use-ca-certificate <PEM_file_abs_path>
  

• Trust system certificates on macOS or Linux: Allow the Local binary to use the certificates installed on your machine. You don’t need a certificate file.

  In your browserstack.yml file:

  browserstackLocal: true
  browserStackLocalOptions:
    -use-system-installed-ca: true
  

  From the command line:

  ./BrowserStackLocal --key YOUR_ACCESS_KEY --force-local --use-system-installed-ca
  

The root certificate options work only with the Local binary, not with the Local desktop app.

For more information, see Local Testing with SSL Inspection and Flags for Local.

These errors mean your network uses SSL inspection, which replaces the certificates that BrowserStack Local relies on to connect securely. Use one of the following solutions:

• Bypass BrowserStack: Ask your network administrator to exclude *.browserstack.com from SSL inspection.
• Disable SSL inspection: Turn off SSL inspection for BrowserStack Local traffic.

• Trust your root certificate on Windows: Provide your organization’s root CA certificate to the Local binary as a .pem file.

  In your browserstack.yml file:

  browserstackLocal: true
  browserStackLocalOptions:
    -use-ca-certificate: <PEM_file_abs_path>
  

  From the command line:

  ./BrowserStackLocal --key YOUR_ACCESS_KEY --force-local --use-ca-certificate <PEM_file_abs_path>
  

• Trust system certificates on macOS or Linux: Allow the Local binary to use the certificates installed on your machine. You don’t need a certificate file.

  In your browserstack.yml file:

  browserstackLocal: true
  browserStackLocalOptions:
    -use-system-installed-ca: true
  

  From the command line:

  ./BrowserStackLocal --key YOUR_ACCESS_KEY --force-local --use-system-installed-ca
  

The root certificate options work only with the Local binary, not with the Local desktop app.

For more information, see Local Testing with SSL Inspection and Flags for Local.

Your account has exceeded the per-user limit for open WebSocket connections. BrowserStack enforces this limit to keep sessions stable for everyone, and it automatically blocks the extra connections.

To fix this, follow these steps:

1. Close idle connections on your side, such as unused sessions, tabs, or test runners that are still connected.
2. Wait a few minutes, then run your tests again.

If you still see the message, contact support.