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:

<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

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:

1. Download the BrowserStack Local binary for your system
   • OS X (10.7 and above)
   • Linux 32-bit
   • Linux 64-bit
   • Windows (XP and above)

   Note: The download links are secure. The binaries are digitally signed, identifying the publisher as 'BrowserStack Limited' for Mac users, and 'BrowserStack Inc.,' for Windows.

2. Unzip the binary to a folder/directory on your machine.
3. Open your command-line interface and navigate to the folder containing the Local binary.
4. Run the binary using the following command:
• OS X & Linux
• Windows

./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.

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:

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.

Once you’ve identified the proxy type and settings, follow the steps below to set up Local Testing.

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"");

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");

./BrowserStackLocal --key ACCESS_KEY --proxy-host <proxy_host> --proxy-port <proxy_port>

./BrowserStackLocal --key ACCESS_KEY --proxy-host <proxy_host> --proxy-port <proxy_port> --proxy-user --proxy-pass

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"");

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");

./BrowserStackLocal --key ACCESS_KEY --local-proxy-host <proxy_host> --local-proxy-port <proxy_port> --local-proxy-user <proxy_user> --local-proxy-pass <proxy_pass>

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>");

./BrowserStackLocal --key ACCESS_KEY --pac-file <pac_file_abs_path>

function FindProxyForURL(url, host) {
if (isPlainHostName(host))
  return "DIRECT";
else
  return "PROXY proxy:80";
}

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.