Skip to main content
Transform your testing process with: Real Device Features, Company-wide Licences, & Test Observability

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:

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.

Protip: It is recommended that you upgrade to the latest version of the CLI so that you have access to the latest updates. To ensure that you are using the latest version, use npm i -g browserstack-cypress-cli.

The following code snippet shows the sample configuration file

browserstack.json
...
{
  "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.

Important: If you are behind a corporate proxy, to be able to connect to the internet, the BrowserStack Local binary will also require the proxy configurations that you can specify in config.yml

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:

config.yml
...
# 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>

# 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
...
Note: The config.yml file does not support the local-identifier flag. You can set BROWSERSTACK_LOCAL_IDENTIFIER as an environment variable when using the CLI. However, the browserstack.json configuration file takes precedence over environment variable.

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:

browserstack.json
...
{
  "connection_settings": {
    "local": true,
    "local_mode": "always-on",
    "local_config_file": "/path/to/your/config.yml"
  }
}
...
Warning: Config file is supported in BrowserStack Local binary v8.1 and above. If you have been using an older version of the binary, you will have to delete it so that a latest version is installed and the config parameters can be used.

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.
browserstack.json
...
{
  "connection_settings": {
    "local": true,
    "local_identifier": <your-local-identifier-string>
  }
}
...
Important: If you are already using another Local connection for running your Selenium tests, JS tests or another Cypress build, you must configure Local Testing connection with an identifier.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy