Search logo Open Menu Close Menu

Home Local Testing App Automate

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:

  1. Establishing a Local Testing connection.
  2. 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()

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

Refer to the following GitHub Repository for more details

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

    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:
    5. ./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");

Note: The binary connection needs to be established before creating a test session, and disconnected only after test execution is complete.

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.

Note: Due to security restrictions in Safari (on iOS 10 and above), localhost URLs will automatically change to http://bs-local.com. This lets us load your website assets properly and does not affect your test scripts. Remember to configure your local server to serve requests from bs-local.com.

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.

Note: For Local Testing to work correctly, bypass traffic for bs-local.com in your proxy server.

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>

Note: We do not support authentication with PAC file at the moment.

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

Note: Not using the --local-identifier flag (for each Local Testing connection) will cut off the existing connection and create a new one.

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.

We use cookies to enhance user experience, analyze site usage, and assist in our marketing efforts. By continuing to browse or closing this banner, you acknowledge that you have read and agree to our Cookie Policy, Privacy Policy and Terms of Service.

Got it