Get your setup working faster. Join our Discord for optimisation tips from elite testers.Join our Discord
Configure proxy settings for Selenium tests
Configure BrowserStack Local to reach websites behind a proxy, an MITM proxy, or a proxy configured using a PAC file when you run Selenium tests on Automate.
If you’ve set up Local Testing but BrowserStack still can’t reach your website, your network might route traffic through a proxy. Add your proxy details to BrowserStack Local so that Automate can reach your website.
This page applies if the website you’re testing is behind a proxy, for example, a website hosted on https://localhost:3000 or another private URL.
The proxy host and port. If the proxy requires authentication, also get the username and password.
Whether the proxy is an MITM proxy, such as BrowserMob Proxy. If it is, get its host and port, and its username and password if it requires authentication.
For a proxy configured using a PAC file, the absolute path of the PAC file on your machine. If the PAC file is hosted at a URL, download it to your machine and use its absolute path.
Check whether BrowserStack Local detects your proxy
BrowserStack Local can detect some proxy settings automatically. To check, run the Local binary with verbose logging from the directory that contains the binary:
The output shows whether BrowserStack Local connected and whether it’s using a proxy. If it doesn’t detect your proxy, configure the proxy using the section that matches your proxy type.
Configure a proxy with no authentication or basic authentication
Use this method for a standard proxy, the most common setup on office networks. You need the proxy host and port, and the username and password if the proxy uses HTTP Basic authentication.
Choose how you run BrowserStack Local and complete the steps:
Replace the placeholder values with your details. A success message in the command line confirms that BrowserStack Local is running.
(Optional) To route all requests from BrowserStack browsers and devices through your proxy, add the --force-local and --force-proxy flags to the command. Without these flags, BrowserStack Local tries to connect directly for better performance. For details, see Local binary flags.
Configure an MITM proxy
Use this method if your proxy is a man-in-the-middle (MITM) proxy, such as BrowserMob Proxy. You need the MITM proxy host and port, and the username and password if the proxy uses HTTP Basic authentication.
Choose how you run BrowserStack Local and complete the steps:
Replace the placeholder values with your details. A success message in the command line confirms that BrowserStack Local is running.
(Optional) To route all requests from BrowserStack browsers and devices through your proxy, add the --force-local and --force-proxy flags to the command. Without these flags, BrowserStack Local tries to connect directly for better performance. For details, see Local binary flags.
Configure a proxy using a PAC file
A Proxy Auto-Configuration (PAC) file contains a JavaScript function, FindProxyForURL, that decides whether each request goes directly to its destination or through a proxy server. Point BrowserStack Local at your PAC file to apply the same rules to Local Testing traffic.
PAC files don’t support proxy authentication. If your proxy returns HTTP error 407, see Troubleshoot PAC file issues.
Sample PAC file
The following PAC file sends requests for plain hostnames, such as localhost, directly. All other requests go through the proxy:
```javascript
function FindProxyForURL(url, host) {
if (isPlainHostName(host))
return "DIRECT";
else
return "PROXY proxy:80";
}
```
If you aren’t sure what your PAC file does, or you aren’t allowed to change it, contact your network or IT team. For more examples and the list of supported PAC functions, see Example PAC file rules.
Add the PAC file to BrowserStack Local
The PAC file must be on the machine that runs BrowserStack Local. If your PAC file is hosted at a URL, download it and use the absolute path of the downloaded file.
Choose how you run BrowserStack Local and complete the steps:
Replace the placeholder values with your details. A success message in the command line confirms that BrowserStack Local is running.
(Optional) To route all requests from BrowserStack browsers and devices through your proxy, add the --force-local and --force-proxy flags to the command. Without these flags, BrowserStack Local tries to connect directly for better performance. For details, see Local binary flags.
Example PAC file rules
BrowserStack Local evaluates the FindProxyForURL(url, host) function in your PAC file for each request. Write your rules using the host parameter, because rules based on the url parameter aren’t supported. Use the following examples as a starting point.
Route requests for one domain through a proxy, and send all other requests directly:
```javascript
function FindProxyForURL(url, host) {
if (dnsDomainIs(host, ".example.com")) {
return "PROXY proxy.example.com:8080";
}
return "DIRECT";
}
```
BrowserStack Local supports the following functions in PAC files:
Function
Supported
Notes
dateRange
Yes
N/A
dnsDomainIs
Yes
N/A
dnsDomainLevels
Yes
N/A
dnsResolve
Yes
N/A
isInNet
Yes
N/A
isPlainHostName
Yes
N/A
isResolvable
Yes
N/A
localHostOrDomainIs
Yes
N/A
myIpAddress
Yes
N/A
shExpMatch
Yes
N/A
timeRange
Yes
N/A
weekdayRange
Yes
N/A
split
Yes
Not part of the PAC specification. Implemented as String.prototype.split.
alert
No
N/A
Limitations
The following features don’t work with PAC files:
Not supported
Alternative
Rules based on the url parameter of FindProxyForURL
Write rules based on the host parameter.
Proxy authentication, including implicit methods such as Kerberos and NTLM
Use a proxy that doesn’t require authentication, or contact your network or IT team for alternatives.
Debug Utility (--debug-utility, --debug-url)
Find the proxy that your PAC file returns, and test it directly with the --proxy-host and --proxy-port flags.
Troubleshoot PAC file issues
BrowserStack Local returns Unable to parse the supplied PAC file
Make sure that your PAC file is valid JavaScript and isn’t minified. In a minified file, comments can merge with the code, which stops BrowserStack Local from parsing the file.
Debug Utility doesn't work with a PAC file
Debug Utility (--debug-utility, --debug-url) doesn’t work with the --pac-file flag. To test connectivity, find the proxy that your PAC file returns for the site, and run the Local binary with the --proxy-host and --proxy-port flags instead.
To find the proxy, run the Local binary with your PAC file and verbose logging, --verbose 3. The logs show the proxy used for each host, for example:
[Pac Resolver] Proxy to use for example.com is proxy.example.com:8080
If these log lines don’t appear, add the --force-local and --force-proxy flags so that all traffic goes through the proxy.
The proxy returns HTTP error 407
PAC files don’t support authentication. If you get HTTP error 407 with BrowserStack Local but not in your browser, your network might use implicit authentication, such as Kerberos, NTLM, or a custom method. BrowserStack Local doesn’t support authentication with PAC files, so contact your network or IT team for alternatives.
Run your tests
After you configure the proxy, run your tests with Local Testing enabled. If you use the BrowserStack SDK, make sure browserstackLocal is set to true in your browserstack.yml file. BrowserStack Local routes requests from BrowserStack browsers and devices through the proxy you configured.
You can optimize your web apps for your mobile users by testing them on mobile devices. Run automated mobile browser tests using BrowserStack Automate.
Join our Discord
