Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

browserstack-cypress-cli

Package Overview
Dependencies
Maintainers
1
Versions
75
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

browserstack-cypress-cli

BrowserStack Cypress CLI for Cypress integration with BrowserStack's remote devices.

  • 1.1.6
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
16K
decreased by-52.65%
Maintainers
1
Weekly downloads
 
Created
Source

BrowserStack Cypress CLI

npm version

The browserstack-cypress-cli is BrowserStack's command-line interface (CLI) which allows you to run your Cypress tests on BrowserStack.

Quick Start

First, install the CLI:

# Install the BrowserStack Cypress CLI
$ npm install -g browserstack-cypress-cli

Note that we run tests that are written using Cypress 4.0 and above. Update to a newer version if you are using an older version of Cypress and update your tests if required.

Next, set up your BrowserStack credentials and configure the browsers that you want to run your tests on. Use the init command to generate a sample browserstack.json file, or alternatively create one from scratch.

# Create a sample configuration file for configurations and capabilities
$ browserstack-cypress init

Fill in the auth, browsers, run_settings values to be able to run your tests. Refer to the configuration options to learn more about all the options you can use in browserstack.json and the possible values.

Make sure you specify the npm packages that your tests need to run using the npm_dependencies option in run_settings.

Then, run your tests on BrowserStack:

$ browserstack-cypress run

You can access the test results on the BrowserStack Automate dashboard.

Configuration Options

The init command will create a sample browserstack.json file. This file can be used to configure your test runs on BrowserStack. Below is the sample file that is generated for your reference.

You can also specify --path <path-to-folder-where-you-need-init-to-run> flag along with the init command to generate browserstack.json file in the specified folder.

{
    "auth": {
      "username": "<your-browserstack-username>",
      "access_key": "<your-browserstack-access-key>"
    },
    "browsers": [
      {
        "browser": "chrome",
        "os": "Windows 10",
        "versions": ["79","78"]
      }
    ],
    "run_settings": {
      "cypress_proj_dir": "/path/to/directory-that-contains-<cypress.json>-file",
      "project_name": "my first project",
      "build_name": "build 1",
      "npm_dependencies": {
        "npm-package-you-need-to-run-tests-1": "^1.2.1",
        "npm-package-you-need-to-run-tests-2": "^7.1.6-beta.13",
      }
    },
    "connection_settings": {
      "local": false,
      "local_identifier": null
    },
    "disable_usage_reporting": "false"
}

Here are all the options that you can provide in the browserstack.json:

Authentication

You can use the auth option to specify your username and access keys. You can find them in your Automate dashboard

OptionDescriptionPossible values
usernameYour BrowserStack username.-
access_keyYour BrowserStack access key.-

Example:

{
  "auth": {
    "username": "<your-browserstack-username>",
    "access_key": "<your-browserstack-access-key>"
  }
}

Specify Browsers

You can use the browsers option to specify the list of OS, browser and browser versions. Each browser combination should contain the following details:

OptionDescriptionPossible values
osOperating system you want to run the tests on.Windows 10
browserBrowser you want to run the tests on.chrome, firefox and edge
versionsA list of supported browser versions.Chrome: 66 to 81
Firefox: 60 to 75
Edge: 80 & 81

Example:

{
  "browsers": [{
      "os": "Windows 10",
      "browser": "chrome",
      "versions": ["79", "78"]
    },
    {
      "os": "Windows 10",
      "browser": "firefox",
      "versions": ["69", "66"]
    }
  ]
}

Configure Test Runs

You can use run_settings option to specify the settings to run your tests on BrowserStack.

OptionDescriptionPossible values
cypress_proj_dirPath to the folder which contains cypress.json file.-
project_nameName of your project. You'll be able to search & filter your tests on the dashboard using this.-
build_nameName of your build / CI run. You'll be able to search & filter your tests on the dashboard using this. username.-
npm_dependenciesA list of NPM packages that are required to run your Cypress tests along with their version numbers.-

Example:

{
  "run_settings": {
    "cypress_proj_dir": "/path/to/directory-that-contains-<cypress.json>-file",
    "project_name": "my first project",
    "build_name": "build 1",
    "npm_dependencies": {
      "npm-package-you-need-to-run-tests-1": "^1.2.1",
      "npm-package-you-need-to-run-tests-2": "^7.1.6-beta.13",
    }
  }
}

Configure Connection Settings

You can use the connection_settings option to specify the Local connection settings. This helps you in testing websites that cannot be accessed on the public network. You can download the Local Testing binary and establish a local connection first before you run the tests (you can learn how to do so here)

OptionDescriptionPossible values
localHelps in testing private web applications.-
local_identifierThe BrowserStack Local tunnel that should be used to resolve requests.-

Note that the local_identifier is applicable only when you start a Local binary with a local identifier. Your tests might fail if you use an invalid local identifier. This option will be ignored if local option is set to false.

Example:

{
  "connection_settings": {
    "local": false,
    "local_identifier": null
  }
}

Disable Usage Reporting

The CLI collects anonymized usage data including the command-line arguments used, system details and errors that you get so that we can improve the way you run your Cypress tests on BrowserStack. Usage reporting is enabled by default - you can disable usage reporting by using the disable_usage_reporting option as follows:

Example:

{
  "disable_usage_reporting": "false"
}

Deprecated Options

The following options are deprecated in favour of the new improved options to make your testing better, flexible and have a consistent way of specifying options.

Deprecated optionNew favoured optionRemarks
specscypress_proj_dirUsed in run_settings
projectproject_nameUsed in run_settings
customBuildNamebuild_nameUsed in run_settings
localIdentifierlocal_identifierUsed in connection_settings

CLI Arguments & Flags

Run the Tests

You can start running your test build using the following command.

$ browserstack-cypress run

By default, the CLI uses the browserstack.json in the directory where the run command is issued. If you need to use a different config file, or are running from a different directory, you can use the --cf or the --config-file option while using run. For example,

$ browserstack-cypress --cf <path-to-browserstack.json> run

# Or
$ browserstack-cypress --config-file <path-to-browserstack.json> run

Sample output :

[2/20/2020, 2:58:31 PM]  Reading browserstack.json from /browserstack.json
[2/20/2020, 2:58:31 PM]  browserstack.json file is validated
[2/20/2020, 2:58:31 PM]  Adding  tests/*.js to zip
[2/20/2020, 2:58:34 PM]  Zip uploaded with url: bs://15f90b540b8cbc47929782f35bb7db20fe1c4709
[2/20/2020, 2:58:34 PM]  File deleted successfully
[2/20/2020, 2:58:34 PM]  Browser list: OS X Catalina-chrome69,OS X Catalina-chrome66
[2/20/2020, 2:58:34 PM]  Test suite: bs://15f90b540b8cbc47929782f35bb7db20fe1c4709
[2/20/2020, 2:58:34 PM]  Local is set to: false
[2/20/2020, 2:58:34 PM]  Build name is: cypress build
[2/20/2020, 2:58:34 PM]  Success
[2/20/2020, 2:58:36 PM]  Build created with build id: 06f28ce423d10314b32e98bb6f68e10b0d02a49a
[2/20/2020, 2:58:36 PM]  File deleted successfully.

Get the Build Information

In case you want to get information on the build you can use the following command

$ browserstack-cypress build-info <buildId>

By default, the CLI uses the browserstack.json in the directory where the build-info command is issued. If you need to use a different config file, or are running the command from a different directory, you can use the --cf or the --config-file option while using build-info. For example,

$ browserstack-cypress --cf <path-to-browserstack.json> build-info <buildId>

# Or
$ browserstack-cypress --config-file <path-to-browserstack.json> build-info <buildId>

Example

$ browserstack-cypress build-info 06f28ce423d10314b32e98bb6f68e10b0d02a49a

Sample output:

[2/20/2020, 3:01:52 PM]  Getting information for buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
[2/20/2020, 3:01:52 PM]  Reading browserstack.json from /browserstack.json
[2/20/2020, 3:01:54 PM]  Build info for build id:
 {
  "build_id": "06f28ce423d10314b32e98bb6f68e10b0d02a49a",
  "framework": "cypress",
  "status": "done",
  "input_capabilities": {
    "devices": [
      "OS X Catalina-chrome69",
      "OS X Catalina-chrome66"
    ],
    "testSuite": "15f90b540b8cbc47929782f35bb7db20fe1c4709",
    "customBuildName": "cypress build",
    "local": false,
    "localIdentifier": null,
    "callbackURL": null,
    "projectNotifyURL": null,
    "project": "test"
  },
  "start_time": "2020-02-20 09:28:35 UTC",
  "device_statuses": {
    "success": {
      "OS X Catalina-chrome69": "Success",
      "OS X Catalina-chrome66": "Success"
    },
    "error": {}
  },
  "test_suite_details": {
    "url": "bs://15f90b540b8cbc47929782f35bb7db20fe1c4709",
    "name": "tests.zip",
    "size": 354
  },
  "duration": "33 seconds",
  "devices": {
    "OS X Catalina-chrome69": {
      "session_id": "3b4038cbbc55d34c1b33c930f3417c7c534c25dd",
      "status": "done",
      "test_status": {
        "failed": 0,
        "success": 3,
        "queued": 0,
        "ignored": 0
      }
    },
    "OS X Catalina-chrome66": {
      "session_id": "fbda8eb5a9eeb7823a9ef7be1a42213c568197e8",
      "status": "done",
      "test_status": {
        "failed": 0,
        "success": 3,
        "queued": 0,
        "ignored": 0
      }
    }
  }
}

Note: Each browser version represents a session. It is advised to validate your account's parallel limit before running multiple versions.

Stop a Running Build

In case you want to stop a running build, you can use the following command

$ browserstack-cypress build-stop <buildId>

By default, the CLI uses the browserstack.json in the directory where the build-stop command is issued. If you need to use a different config file, or are running the command from a different directory, you can use the --cf or the --config-file option while using build-stop. For example,

$ browserstack-cypress --cf <path-to-browserstack.json> build-stop <buildId>

# Or
$ browserstack-cypress --config-file <path-to-browserstack.json> build-stop <buildId>

Example

$ browserstack-cypress build-stop 06f28ce423d10314b32e98bb6f68e10b0d02a49a

Sample output:

[3/24/2020, 2:31:11 PM]  Stopping build with given buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
[3/24/2020, 2:31:12 PM]  Reading config from /browserstack.json
[3/24/2020, 2:31:14 PM]  {
  "message": "stopped 1 sessions",
  "stopped_session_count": 1
}

Disable CLI Usage Reporting

The CLI collects anonymized usage data including the command-line arguments used, system details and errors that you get so that we can improve the way you run your Cypress tests on BrowserStack. Usage reporting is enabled by default - you can disable usage reporting by using the --disable-usage-reporting flag. You can also do this by setting the disable_usage_reporting option to "true" in browserstack.json.

$ browserstack-cypress --disable-usage-reporting <your-commands>

Limitations

  • exec and task are not allowed.
  • While using local, please make sure to create /etc/hosts entry pointing to some URL, and use that URL in the tests. The localhost URI doesn't work at the moment. You can use http://bs-local.com instead, to replace localhost
  • Installing npm packages using npm_dependencies is not supported for tests running on macOS.

License

This project is released under MIT License. Please refer the LICENSE.md for more details.

FAQs

Package last updated on 21 May 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc