Local Testing with App Automate
This guide shows you how to set up and use Local Testing with BrowserStack App Automate.
Introduction
Enabling Local Testing with App Automate is a simple two-step process:
- Establishing a Local Testing connection.
- Configuring test scripts so they run through the Local Testing connection.
This page will guide you through enabling Local Testing for App Automate sessions, and then using it to test apps that retrieve data from servers on your local machine, CI/CD machines/nodes, and other private network configurations.
Enabling Local Testing with App Automate
Establishing a Local Testing connection
You can establish Local Testing connection in one of two ways: via language bindings, or via the command-line interface.
Via language bindings:
Within your test scripts, you can add a snippet that will automatically start and end the Local Testing connection.
To do this, you’ll need bindings for your programming language. Select the language and follow the steps below:
Installation:
<dependency> <groupId>com.browserstack</groupId> <artifactId>browserstack-local-java</artifactId> <version>1.0.3</version> </dependency>
npm install browserstack-local
pip install browserstack-local
// 1. Open the solution file 'BrowserStack/BrowserStack.sln' in Visual Studio. The projects are Visual Studio 2015 compatible. // 2. You will need to resolve the references from the Solution Explorer. Visual Studio with automatically download the references from NuGet.
# Installation is possible using Composer. # If you don't already use Composer, you can download the composer.phar binary: curl -sS https://getcomposer.org/installer | php # Then install the library: php composer.phar require browserstack/local:dev-master # Install all the dependencies: php composer.phar install # Test the installation by running a simple test file, check out example.php in the main repository.
gem install browserstack-local
perl Makefile.PL make make install
Example:
import com.browserstack.local.Local; # creates an instance of Local Local bsLocal = new Local(); # replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". HashMap<String, String> bsLocalArgs = new HashMap<String, String>(); bsLocalArgs.put("key", "<browserstack-accesskey>"); # starts the Local instance with the required arguments bsLocal.start(bsLocalArgs); # check if BrowserStack local instance is running System.out.println(bsLocal.isRunning()); #stop the Local instance bsLocal.stop();
var browserstack = require('browserstack-local'); // creates an instance of Local var bs_local = new browserstack.Local(); // replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". var bs_local_args = { 'key': '<browserstack-accesskey>' }; // starts the Local instance with the required arguments bs_local.start(bs_local_args, function() { console.log("Started BrowserStackLocal"); }); // check if BrowserStack local instance is running console.log(bs_local.isRunning()); // stop the Local instance bs_local.stop(function() { console.log("Stopped BrowserStackLocal"); });
from browserstack.local import Local #creates an instance of Local bs_local = Local() #replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". bs_local_args = { "key": "<browserstack-accesskey>" } #starts the Local instance with the required arguments bs_local.start(**bs_local_args) #check if BrowserStack local instance is running print(bs_local.isRunning()) #stop the Local instance bs_local.stop()
using BrowserStack; # creates an instance of Local Local local = new Local(); # replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". List<KeyValuePair<string, string>> bsLocalArgs = new List<KeyValuePair<string, string>>() { new KeyValuePair<string, string>("key", "<browserstack-accesskey>"), } # starts the Local instance with the required arguments local.start(bsLocalArgs); # check if BrowserStack local instance is running Console.WriteLine(local.isRunning()); # stop the Local instance local.stop();
require_once('vendor/autoload.php'); use BrowserStack\Local; #creates an instance of Local $bs_local = new Local(); #replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". $bs_local_args = array("key" => "<browserstack-accesskey>"); #starts the Local instance with the required arguments $bs_local->start(bs_local_args); #check if BrowserStack local instance is running echo $bs_local->isRunning(); #stop the Local instance $bs_local->stop();
require 'browserstack/local' #creates an instance of Local bs_local = BrowserStack::Local.new #replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". bs_local_args = { "key" => "<browserstack-accesskey>" } #starts the Local instance with the required arguments bs_local.start(bs_local_args) #check if BrowserStack local instance is running puts bs_local.isRunning #stop the Local instance bs_local.stop
use BrowserStack::Local; #creates an instance of Local $bs_local = BrowserStack::Local::new; #replace <browserstack-accesskey> with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY". my %bs_local_args = ("key" => "<browserstack-accesskey>"); #starts the Local instance with the required arguments $bs_local->start(%bs_local_args) #check if BrowserStack local instance is running puts $bs_local->isRunning() #stop the Local instance $bs_local->stop()
Via command-line interface:
You can also start a Local Testing connection through your command-line interface by following the steps below:
- Download the BrowserStack Local binary for your system
- Unzip the binary to a folder/directory on your machine.
- Open your command-line interface and navigate to the folder containing the Local binary.
- Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY
Configuring tests to run with Local Testing connection
After establishing the Local Testing connection, set browserstack.local capability to true by adding the following snippet to your test scripts:
caps.setCapability("browserstack.local", "true");
The Local Testing setup will differ slightly based on your requirements (for example, proxy settings, restricting connections to certain domains, etc.). Refer to our complete list of flags to set up Local Testing for different environments/network configurations.
We cover some common Local Testing setup/usage scenarios in the next section: Using Local Testing with App Automate.
Using Local Testing with App Automate
Here’s how you can set up and use Local Testing with BrowserStack App Automate for various development/private network environments:
Test apps that retrieve data from localhost servers
Once you’ve enabled Local Testing, our remote devices will be able to access apps that retrieve data from your localhost servers.
Use your test scripts to access and interact with your apps. Remember to set browserstack.local capability to true in your test scripts.
Test apps that retrieve data from private or internal servers
You can securely test mobile apps that retrieve data from private or internal servers using --force-local on our remote mobile devices. This option resolves all requests (on our remote devices) through your local machine.
To enable this option, use one of two ways to establish the Local Testing connection:
Via language bindings:
Add the following snippet to your test scripts:
bsLocalArgs.put("forcelocal", "true");
bs_local_args = { 'key': '<browserstack-accesskey>', 'forceLocal': 'true' }
bs_local_args = { "key": "<browserstack-accesskey>" , "forcelocal": "true"}
bsLocalArgs.Add(new KeyValuePair<string, string>("forcelocal", "true"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "forcelocal" => true);
bs_local_args = { "key" => "<browserstack-accesskey>" , "forcelocal" => "true"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "forcelocal" => "true");
Via command-line interface:
Use the --force-local flag while establishing a Local Testing connection.
Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY --force-local
After establishing the Local Testing connection, use your test scripts to access and interact with your internally-hosted website (for example, staging.example.com). Remember to set browserstack.local capability to true in your test scripts.
Test apps that retrieve data from servers behind proxies
If you have correctly set up Local Testing but are still unable to load your app's assets on remote mobile devices, then you are probably behind a proxy.
You can test apps serving content from private or internal servers that are behind proxies—on our remote mobile devices. 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:
- Proxy with no authentication or HTTP Basic Authentication.
- MITM proxy with no authentication or HTTP Basic Authentication.
- PAC (Proxy Auto-Configuration) with no authentication.
Once you’ve identified the proxy type and settings, follow the steps below to set up Local Testing.
Proxy
Proxies are commonly set up for office networks, remote servers, and/or your local machine. Contact your network/IT team to obtain the ‘Proxy Host’ and ‘Proxy Port’ to setup Local Testing for this implementation.
Once you obtain the Host and Port, you can establish a Local Testing connection using one of two ways:
Via language bindings:
Add the following snippet to your test scripts:
bsLocalArgs.put("proxyHost", "127.0.0.1"); bsLocalArgs.put("proxyPort", "8000");
bs_local_args = { 'key': '<browserstack-accesskey>', 'proxyHost': '127.0.0.1', 'proxyPort': '8000' }
bs_local_args = { "key": "<browserstack-accesskey>", "proxyHost": "127.0.0.1", "proxyPort": "8000"}
bsLocalArgs.Add(new KeyValuePair<string, string>("proxyHost", "127.0.0.1")); bsLocalArgs.Add(new KeyValuePair<string, string>("proxyPort", "8000"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000");
bs_local_args = { "key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000"");
If your proxy requires authentication, use the following code snippet:
bsLocalArgs.put("proxyHost", "127.0.0.1"); bsLocalArgs.put("proxyPort", "8000"); bsLocalArgs.put("proxyUser", "user"); bsLocalArgs.put("proxyPass", "password");
bs_local_args = { 'key': '<browserstack-accesskey>', 'proxyHost': '127.0.0.1', 'proxyPort': '8000', 'proxyUser': 'user', 'proxyPass': 'password' }
bs_local_args = { "key": "<browserstack-accesskey>", "proxyHost": "127.0.0.1", "proxyPort": "8000", "proxyUser": "user", "proxyPass": "password"}
bsLocalArgs.Add(new KeyValuePair<string, string>("proxyHost", "127.0.0.1")); bsLocalArgs.Add(new KeyValuePair<string, string>("proxyPort", "8000")); bsLocalArgs.Add(new KeyValuePair<string, string>("proxyUser", "user")); bsLocalArgs.Add(new KeyValuePair<string, string>("proxyPass", "password"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000", "proxyUser" => "user", "proxyPass" => "password");
bs_local_args = { "key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000", "proxyUser" => "user", "proxyPass" => "password"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "proxyPort" => "8000", "proxyUser" => "user", "proxyPass" => "password");
Via command-line interface:
Use the --proxy-host and --proxy-port flags while establishing a Local Testing connection:
Run the binary using the following command:
./BrowserStackLocal --key 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.
Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY --proxy-host <proxy_host> --proxy-port <proxy_port> --proxy-user --proxy-pass
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.
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 using one of two ways:
Via language bindings:
Add the following snippet to your test scripts:
bsLocalArgs.put("localProxyHost", "127.0.0.1"); bsLocalArgs.put("localProxyPort", "8000");
bs_local_args = { 'key': '<browserstack-accesskey>', 'localProxyHost': '127.0.0.1', 'localProxyPort': '8000' }
bs_local_args = { "key": "<browserstack-accesskey>", "localProxyHost": "127.0.0.1", "localProxyPort": "8000"}
bsLocalArgs.Add(new KeyValuePair<string, string>("localProxyHost", "127.0.0.1")); bsLocalArgs.Add(new KeyValuePair<string, string>("localProxyPort", "8000"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "localProxyHost" => "127.0.0.1", "localProxyPort" => "8000");
bs_local_args = { "key" => "<browserstack-accesskey>", "localProxyHost" => "127.0.0.1", "localProxyPort" => "8000"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "localProxyHost" => "127.0.0.1", "localProxyPort" => "8000"");
If your proxy requires authentication, use the following code snippet:
bsLocalArgs.put("localProxyHost", "127.0.0.1"); bsLocalArgs.put("localProxyPort", "8000"); bsLocalArgs.put("-localProxyUser", "user"); bsLocalArgs.put("-localProxyPass", "password");
bs_local_args = { 'key': '<browserstack-accesskey>', 'localProxyHost': '127.0.0.1', 'localProxyPort': '8000', 'localProxyUser': 'user', 'localProxyPass': 'password' }
bs_local_args = { "key": "<browserstack-accesskey>", "localProxyHost": "127.0.0.1", "localProxyPort": "8000", "-localProxyUser": "user", "-localProxyPass": "password"}
bsLocalArgs.Add(new KeyValuePair<string, string>("localProxyHost", "127.0.0.1")); bsLocalArgs.Add(new KeyValuePair<string, string>("localProxyPort", "8000")); bsLocalArgs.Add(new KeyValuePair<string, string>("-localProxyUser", "user")); bsLocalArgs.Add(new KeyValuePair<string, string>("-localProxyPass", "password"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "localProxyHost" => "127.0.0.1", "localProxyPort" => "8000", "-localProxyUser" => "user", "-localProxyPass" => "password");
bs_local_args = { "key" => "<browserstack-accesskey>", "localProxyHost" => "127.0.0.1", "localProxyPort" => "8000", "-localProxyUser" => "user", "-localProxyPass" => "password"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "proxyHost" => "127.0.0.1", "localProxyPort" => "8000", "-localProxyUser" => "user", "-localProxyPass" => "password");
Via command-line interface:
Use the following command to establish the Local Testing connection:
Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY --local-proxy-host <proxy_host> --local-proxy-port <proxy_port> --local-proxy-user <proxy_user> --local-proxy-pass <proxy_pass>
If your local proxy requires authentication, add --local-proxy-user and --local-proxy-pass the command, as shown below:
To resolve all requests on our remote browsers and mobile devices through your local proxy, add --force-proxy and --force-local flags to the command. Without these flags, Local binary tries to connect directly for enhanced performance.
PAC (Proxy auto-config)
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 using one of two ways:
Via language bindings:
Add the following snippet to your test scripts:
bsLocalArgs.put("-pac-file", "<pac_file_abs_path>");
bs_local_args = { 'key': '<browserstack-accesskey>', 'pac-file': '<pac_file_abs_path>' }
bs_local_args = { "key": "<browserstack-accesskey>" , "-pac-file": "<pac_file_abs_path>"}
bsLocalArgs.Add(new KeyValuePair<string, string>("-pac-file", "<pac_file_abs_path>"));
$bs_local_args = array("key" => "<browserstack-accesskey>", "-pac-file"
bs_local_args = { "key" => "<browserstack-accesskey>" , "-pac-file" => "<pac_file_abs_path>"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "-pac-file" => "<pac_file_abs_path>");
Via command-line interface:
Establish the Local Testing connection using --pac-file flag, along with the PAC file’s absolute path.
Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY --pac-file <pac_file_abs_path>
To resolve all requests with Local Testing through your PAC proxy, add --force-proxy and --force-local flags to the command.
Without these flags, Local binary tries to connect directly for enhanced performance.
Sample PAC file
The following function checks to see whether the hostname is localhost, and if so, whether the connection is direct. If the hostname is not localhost, the connection is via proxy.
function FindProxyForURL(url, host) { if (isPlainHostName(host)) return "DIRECT"; else return "PROXY proxy:80"; }
If you don't understand the proxy script or are not authorized to make any changes to it, contact your IT/Network team.
Test apps that retrieve data from servers behind firewall and/or VPNs
With Local Testing, you can test apps that retrieve data/assets from internal servers that are behind firewalls and/or VPNs.
Start by making sure that you can access the app on your machine. Then, set up a Local Testing connection by following the steps listed in Test apps that retrieve data from private or internal servers.
Multiple Local Testing connections
You can test multiple forks and builds at the same time by setting up separate Local Testing connections for each. To do so, establish local testing connections using one of two ways:
Via language bindings:
Add the following snippet to your test scripts:
bsLocalArgs.put("localIdentifier", "randomstring");
bs_local_args = { 'key': '<browserstack-accesskey>', 'localIdentifier': 'randomstring' }
bs_local_args = { "key": "<browserstack-accesskey>" , "localIdentifier": "randomstring"}
bsLocalArgs.Add(new KeyValuePair<string, string>("localIdentifier", "randomstring"));
my %bs_local_args = ("key" => "<browserstack-accesskey>", "localIdentifier" => "randomstring");
bs_local_args = { "key" => "<browserstack-accesskey>" , "localIdentifier" => "randomstring"}
my %bs_local_args = ("key" => "<browserstack-accesskey>", "localIdentifier" => "randomstring");
Via command-line interface
Establish each Local Testing connection using the --local-identifier flag, along with a unique connection name (for instance, Test 123).
Run the binary using the following command:
./BrowserStackLocal --key ACCESS_KEY --local-identifier Test123
After establishing Local Testing connections, configure the test script to run through a specific connection. To do so, set the browserstack.localIdentifier capability in your test scripts—and add the unique connection name as parameter.
caps.setCapability("browserstack.local", "true"); caps.setCapability("browserstack.localIdentifier", "Test123");
Managing multiple Local Testing connections
You can use the Local Testing API to check the status of (or disconnect) active binaries. However, your connections will not show up in the API response unless you establish them using '--enable-logging-for-api' flag, as follows:
./BrowserStackLocal --key ACCESS_KEY --enable-logging-for-api <other_params>
-
Determining the status of Local binaries via API
Check the status of all Local binaries that are currently running.
https://www.browserstack.com/local/v1/list?auth_token=ACCESS_KEY&last=5&state=running
-
Disconnect a Local Testing connection via API
Disconnect an active Local Testing connection through the binary command-line interface.
curl -X DELETE "https://www.browserstack.com/local/v1/QUERTY1?auth_token=ACCESS_KEY
Refer to the Local API for debugging binaries page for more details.
Connection duration and disconnection
The Local Testing connection is persistent. Your machine and BrowserStack Cloud remain connected unless you explicitly end the connection.
In the following scenarios, ensure that you open and close the connection by following the steps:
Language bindings
Write the code to start the local binary before accessing mobile apps that retrieve content from your local or staging servers. Close the connection after test execution is complete.
CI server
Write a script that will establish the Local Testing connection before running a test. Close the connection after test execution is complete.
Binary
Run the Local binary using command-line interface with appropriate flags before triggering your tests. Close the connection after test execution is complete.
What isn't supported?
Currently, Local Testing with App Automate does not support:
- Proxies with advanced authentication like Windows, Digest, etc.
We are working on adding support for the above.