Test your locally hosted websites

Learn how to run your Cypress tests on your locally hosted and staging websites using BrowserStack Automate.

Introduction

Using Local testing, BrowserStack enables you to run automated tests on your internal development environments, on localhost, staging setups, or from behind a corporate firewall.

Local testing establishes a secure connection between your machine and the BrowserStack cloud. After you set up Local testing, all your private URLs are automatically resolved, including HTTPS URLs and other URLs hosted behind a proxy or firewall.

Local testing can be integrated with your existing CI/CD workflows. Check out how Local testing works to understand how to best integrate it in your setup.

In this guide, you will learn:

• How to set up Local testing
• How to set additional local flags
• How to manage Local binary manually

Set up Local testing

To set up Local testing with BrowserStack, set the local key to true within connections_settings in the browserstack.json file.

The following code snippet shows the sample configuration file

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

The local mode key is set to always-on in the example above, ensuring that the local connection remains active thereby speeding up your tests.

Set additional local flags with a configuration file

This section is optional only if you want to specify additional parameters to your Local binary.

The Local testing binary supports a lot of additional configuration parameters. You can configure advanced flags, such as local identifier, verbose logging, proxy configurations, and so on as per your requirement in the config.yml file.

Check out the list of all supported arguments for Local testing to learn more about creating a local_config_file under --config-file.

The following code snippet shows a sample config.yml file:

...
# Setting additional local flags

# force-local: This flag ensures that, regardless of any other setting, none of the assets are resolved via the public internet and any resolution of URLs that your BrowserStack device does is routed through the Local tunnel. This flag is typically used to ensure compliance with your network policies. 
--force-local

# verbose: This option sets the level of logging required. Set 1 to debug issues related to setting up connections. Set 2 for logs related to network information. Set 3 to forward all communication to local servers for each request and response. The default value for this option is 1.
---verbose <INTEGER_1_2_3>

# local-identifier: If you are running multiple instances of BrowserStackLocal binary (for better performance or other reasons),  specify unique strings for each instance such that BrowserStack  uniquely identifies them. Ensure that you specify the same string in Automate tests as well.
--local-identifier <YOUR_LOCAL_IDENTIFIER_STRING>

# proxy-host: If you are behind the corporate proxy setup, specify your proxy host using this option.
--proxy-host

# proxy-port: If you are behind the corporate proxy setup, specify your proxy port using this option. The default value is 3128.
--proxy-port

# proxy-user: If you are behind a corporate proxy which requires authentication, specify your proxy username using this option. Currently, we support HTTP Basic authentication only.
--proxy-user

# proxy-pass: If you are behind a corporate proxy which requires authentication, specify your proxy password using this option. Currently, we support HTTP Basic authentication only.
--proxy-pass
...

After you set the flags in the configuration file, set the local_config_file key in the browserstack.json file as seen in the following code snippet:

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

If you want to manage the Local binary manually, refer to the next section.

Use an existing local connection

Although we recommend managing Local binary instances using the browerstack.json file, if you want to manually control instantiating Local binary instances, you can use the steps in this section.

To setup the Local binary manually, complete the following steps:

1. Download the Local binary based on your operating system.
   OS X | Linux (32-bit) | Linux (64-bit) | Windows
2. Unzip the downloaded file.
3. In your command line, enter the following command to establish a local connection. In the following code snippet, use your BrowserStack access key and the local_identifier that you have used to start your local connection.
   Note: Ensure that you use the --enable-logging-for-api flag to reuse your existing local connections for your Cypress tests.
   • OS X and Linux

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

   • Windows

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

4. After the connection is established, add the local key and the local_identifier key to the browserstack.json file.
   

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

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.