Puppeteer testing of private websites behind a proxy

Guide for running your Puppeteer tests when your application is behind a proxy.

If you have correctly set up Local Testing but are still unable to load your local/internally-hosted website/assets on BrowserStack, then you are probably behind a proxy.

You can use Local Testing to test websites hosted behind proxies, on our remote browsers and devices. The setup will vary based on the proxy implementation in your network. Refer to this article to find proxy settings on your computer or contact your network/IT team.

Currently, we only support Local Testing through the following proxies:

1. Proxy with no authentication or HTTP Basic Authentication.
2. MITM proxy with no authentication or HTTP Basic Authentication.
3. PAC (Proxy Auto-Configuration) with no authentication.

If you’re behind a proxy

If the website against which you want to run your tests is hosted behind a proxy, you can use the following proxy options while starting the BrowserStackLocal binary:

BrowserStackLocal --key YOUR_ACCESS_KEY --proxy-host <proxy_host> --proxy-port <proxy_port>

If your proxy requires authentication, add --proxy-user and --proxy-pass to the above command.

To resolve all requests on our remote browsers and mobile devices through your proxy, add --force-proxy and --force-local flags to the command. Without these flags, Local binary tries to connect directly for better performance.

If you’re using the browserstack-local node package

You can pass all the above flags even when you are using the browserstack-local node package to run your tests as shown below:

const BS_LOCAL_ARGS = {
    'key': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
    'proxyHost': 'your-proxy-host',
    'proxyPort': 'your-proxy-port',
    'proxyUser': 'your-proxy-username',
    'proxyPass': 'your-proxy-password'
};
bsLocal.start(BS_LOCAL_ARGS, testFn);  // testFn is the actual function that contains the test

You can read more about specifying different flags in the arguments of the method call for creating the connection using the node package.

If you’re behind an MITM Proxy

If your proxy type is MITM (like BrowserMob), you will need the Proxy Host and Proxy Port. Once you have the Host and Port, you can establish a Local Testing connection like this:

BrowserStackLocal --key YOUR_ACCESS_KEY --local-proxy-host <proxy_host> --local-proxy-port <proxy_port>

To resolve all requests on our remote browsers and mobile devices through your proxy, add --force-proxy and --force-local flags to the command. Without these flags, Local binary tries to connect directly for better performance.

Once the connection is established, you can use local key in the connection_settings option to specify the Local connection settings. For example:

If you’re using the browserstack-local node package

You can pass all the above flags even when you are using the browserstack-local node package to run your tests as shown below:

const BS_LOCAL_ARGS = {
    'key': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
    'proxyHost': 'your-proxy-host',
    'proxyPort': 'your-proxy-port',
    'proxyUser': 'your-proxy-username',
    'proxyPass': 'your-proxy-password'
};
bsLocal.start(BS_LOCAL_ARGS, testFn);  // testFn is the actual function that contains the test

You can read more about specifying different flags in the arguments of the method call for creating the connection using the node package.

PAC (Proxy Auto-Configuration)

PAC file (Proxy auto-configuration file) contains a Javascript function that determines whether a request should be sent via the proxy server.

Once you have the absolute path of the PAC file on your machine, you can establish a Local Testing connection like this:

BrowserStackLocal --key YOUR_ACCESS_KEY --pac-file <pac_file_abs_path>

To resolve all requests on our remote browsers and mobile devices through your proxy, add --force-proxy and --force-local flags to the command. Without these flags, Local binary tries to connect directly for better performance.

If you’re using the browserstack-local node package

You can pass the above --pac-file flag even when you are using the browserstack-local node package to run your tests as shown below:

const BS_LOCAL_ARGS = {
    'key': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
    'pac-file': '<pac_file_abs_path>'
};
bsLocal.start(BS_LOCAL_ARGS, testFn);  // testFn is the actual function that contains the test