Run Tests in Dev Environments

Learn how to test localhost and staging websites without publicly hosting them.

Local Testing

BrowserStack enables you to run automated tests on your internal development environments, on localhost, staging setups or from behind a corporate firewall. This feature is called Local Testing.

Local Testing establishes a secure connection between your machine and the BrowserStack cloud. Once you set up Local Testing, all your private URLs work out of the box, including HTTPS URLs and those behind a proxy or firewall.

Setting up Local Testing

Setting up Local testing with BrowserStack (starting with CLI version 1.8.1 and above) is as simple as letting us know that you would like to use this option. If you’re using an older version of the CLI - please consider upgrading! Otherwise, you can refer to the manual setup mentioned below.

You can use local key in the connection_settings option to specify the Local connection settings in the browserstack.json configuration file, like this:

...
{
  "connection_settings": {
    "local": true
  }
}
...

Starting the BrowserStack Local service can take 4-5 seconds in some cases, so you might want to start it once and re-use it for a series of tests. We support two configuration options for this: “always-on” or “on-demand”.

“always-on” will run the binary once and keep it running in the background for any new tests that you might want to spawn. There will only be one instance of the service running on your system, and the next BrowserStack-Cypress test will automatically detect the running service and not start a new one.

By default, the selected mode is “on-demand”, where we will spawn the Local service before a test, and terminate it after the test is done.

You can pass these modes in the following way:

...
{
  "connection_settings": {
    "local": true,
    "local_mode": "always-on"
  }
}
...

If you are an advanced BrowserStack user, or if your test setup is complicated in any way and you need to pass additional parameters to the BrowserStack Local service, you can do so by passing your local_config_file directly to the BrowserStack-Cypress CLI. You can read more about creating a local_config_file under --config-file in our Local Testing documentation.

This is done by the following snippet in browserstack.json:

...
{
  "connection_settings": {
    "local": true,
    "local_mode": "always-on",
    "local_config_file": "/path/to/your/config.yml"
  }
}
...

If you want to manage the Local service by yourself, you can use the next section.

Alternative manual setup (optional)

First, you will need to download the Local binary. Choose one based on the operating system of your machine - OS X | Linux (32-bit) | Linux (64-bit) | Windows

Next, unzip the file that you downloaded, and establish the Local Testing connection using the following command in terminal/command prompt:

./BrowserStackLocal --key YOUR_ACCESS_KEY --local-identifier A_UNIQUE_IDENTIFIER_STRING --enable-logging-for-api

BrowserStackLocal.exe --key YOUR_ACCESS_KEY --local-identifier A_UNIQUE_IDENTIFIER_STRING --enable-logging-for-api

Once the connection is established, you can use local key in the connection_settings option to specify the Local connection settings in the browserstack.json configuration file, like this:

...
{
  "connection_settings": {
    "local": true,
    "local_identifier": <your-local-identifier-string>
  }
}
...

Alternatively, you can set the environment variable BROWSERSTACK_LOCAL to true. Note that the environment variable will override the options in your browserstack.json.

Additional links

• Understand how Local Testing works.
• Learn how to set up Local testing connection from behind a proxy/firewall.
• Read more about the supported args by the Local binary.