Skip to content

Commit 2f6f73e

Browse files
SreyanthSreyanth
committed
Update README to include quick start, disable usage reporting and npm dependencies
1 parent ee3be8e commit 2f6f73e

File tree

1 file changed

+191
-56
lines changed

1 file changed

+191
-56
lines changed

‎README.md

Lines changed: 191 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,64 @@
1-
- [BrowserStack Cypress CLI](#browserstack-cypress-cli)
2-
- [Using BrowserStack-Cypress CLI:](#using-browserstack-cypress-cli)
3-
- [Installing browserstack-cypress](#installing-browserstack-cypress)
4-
- [Configuring your tests](#configuring-your-tests)
5-
- [Running the tests](#running-the-tests)
6-
- [Getting build information](#getting-build-information)
7-
- [Limitations](#limitations)
8-
- [Accessing test results](#accessing-test-results)
9-
- [License](#license)
10-
111
# BrowserStack Cypress CLI
12-
You can now run your Cypress tests in BrowserStack using our `browserstack-cypress-cli`. BrowserStack currently supports Cypress 4 and you can start testing on the following browser combinations:
13-
142

15-
| Windows 10 | OS X Mojave | OS X Catalina |
16-
|:---------------------:|:---------------------:|:--------------------:|
17-
| Chrome 66.0 to 79.0 | Chrome 66.0 to 79.0 | Chrome 66.0 to 79.0 |
18-
| Edge 80.0 | Edge 80.0 | Edge 80.0 |
19-
| Firefox 60.0 to 72.0| Firefox 60.0 to 72.0 | Firefox 60.0 to 72.0|
3+
[![npm version](https://badge.fury.io/js/browserstack-cypress-cli.svg)](https://badge.fury.io/js/browserstack-cypress-cli)
204

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

22-
We are actively working on supporting other browsers and will start adding other browsers to this list.
8+
- [Quick Start](#quick-start)
9+
- [Configuration Options](#configuration-options)
10+
- [Authentication](#authentication)
11+
- [Specify Browsers](#specify-browsers)
12+
- [Configure Test Runs](#configure-test-runs)
13+
- [Configure Connection Settings](#configure-connection-settings)
14+
- [Disable Usage Reporting](#disable-usage-reporting)
15+
- [CLI Arguments & Flags](#cli-arguments-flags)
16+
- [Running the Tests](#running-the-tests)
17+
- [Getting the Build Information](#getting-the-build-information)
18+
- [Stopping a Running Build](#stopping-a-running-build)
19+
- [Limitations](#limitations)
20+
- [License](#license)
2321

24-
## Using BrowserStack-Cypress CLI:
22+
## Quick Start
2523

24+
First, install the CLI:
2625

27-
### Installing browserstack-cypress
2826
```bash
29-
# Install cypress (ignore if already done)
30-
$ npm install -g [email protected]
31-
3227
# Install the BrowserStack Cypress CLI
3328
$ npm install -g browserstack-cypress-cli
3429
```
3530

36-
### Configuring your tests
31+
Note that we run tests that are written using Cypress 4.0 and above. Update to
32+
a newer version if you are using an older version of Cypress and update your
33+
tests if required.
34+
35+
Next, set up your BrowserStack credentials and configure the browsers that you
36+
want to run your tests on. Use the `init` command to generate a sample
37+
`browserstack.json` file, or alternatively create one from scratch.
38+
3739
```bash
38-
# create a sample configuration file for configurations and capabilities
40+
# Create a sample configuration file for configurations and capabilities
3941
$ browserstack-cypress init
4042
```
4143

42-
This 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.
44+
Fill in the `auth`, `browsers`, `run_settings` values to be able to run your
45+
tests. Refer to the [configuration options](#configuration-options) to learn
46+
more about all the options you can use in `browserstack.json` and the possible
47+
values.
48+
49+
Then, run your tests on BrowserStack:
50+
51+
```bash
52+
$ browserstack-cypress run
53+
```
54+
55+
You can access the test results on the [BrowserStack Automate dashboard](https://automate.browserstack.com/).
56+
57+
## Configuration Options
58+
59+
The `init` command will create a sample `browserstack.json` file. This file can
60+
be used to configure your test runs on BrowserStack. Below is the sample file
61+
that is generated for your reference.
4362

4463
```json
4564
{
@@ -57,33 +76,149 @@ This will create a sample `browserstack.json` file. This file can be used to con
5776
"run_settings": {
5877
"cypress_proj_dir": "/path/to/directory-that-contains-<cypress.json>-file",
5978
"project": "my first project",
60-
"customBuildName": "build 1"
79+
"custom_build_name": "build 1",
80+
"npm_dependencies": [
81+
"npm-package-you-need-to-run-tests-1",
82+
"[email protected]"
83+
]
6184
},
6285
"connection_settings": {
6386
"local": false,
64-
"localIdentifier": null
87+
"local_identifier": null
88+
},
89+
"disable_usage_reporting": "false"
90+
}
91+
```
92+
93+
Here are all the options that you can provide in the `browserstack.json`:
94+
95+
### Authentication
96+
97+
You can use the `auth` option to specify your username and access keys. You
98+
can find them in your [Automate dashboard](https://automate.browserstack.com/)
99+
100+
| Option | Description | Possible values |
101+
| ------------ | ----------------------------- | --------------- |
102+
| `username` | Your BrowserStack username. | - |
103+
| `access_key` | Your BrowserStack access key. | - |
104+
105+
Example:
106+
107+
```json
108+
{
109+
"auth": {
110+
"username": "<your-browserstack-username>",
111+
"access_key": "<your-browserstack-access-key>"
112+
}
113+
}
114+
```
115+
116+
### Specify Browsers
117+
118+
You can use the `browsers` option to specify the list of OS, browser and browser
119+
versions. Each browser combination should contain the following details:
120+
121+
| Option | Description | Possible values |
122+
| ---------- | ---------------------------------------------- | -------------------------------------------------------------- |
123+
| `os` | Operating system you want to run the tests on. | `Windows 10`, `OS X Mojave` and `OS X Catalina` |
124+
| `browser` | Browser you want to run the tests on. | `chrome`, `firefox` and `edge` |
125+
| `versions` | A list of supported browser versions. | Chrome: `66` to `80` <br/>Firefox: `60` to `72`<br/>Edge: `80` |
126+
127+
Example:
128+
129+
```json
130+
{
131+
"browsers": [{
132+
"os": "Windows 10",
133+
"browser": "chrome",
134+
"versions": ["69", "66"]
135+
},
136+
{
137+
"os": "OS X Mojave",
138+
"browser": "firefox",
139+
"versions": ["69", "66"]
65140
}
141+
]
142+
}
143+
```
144+
145+
### Configure Test Runs
146+
147+
You can use `run_settings` option to specify the settings to run your tests on
148+
BrowserStack.
149+
150+
| Option | Description | Possible values |
151+
| ------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------- |
152+
| `cypress_proj_dir` | Path to the folder which contains `cypress.json` file. | - |
153+
| `project` | Name of your project. You'll be able to search & filter your tests on the dashboard using this. | - |
154+
| `custom_build_name` | Name of your build / CI run. You'll be able to search & filter your tests on the dashboard using this. username. | - |
155+
| `npm_dependencies` | A list of NPM packages to be able to run your Cypress tests. | - |
156+
157+
Example:
158+
159+
```json
160+
{
161+
"run_settings": {
162+
"cypress_proj_dir": "/path/to/directory-that-contains-<cypress.json>-file",
163+
"project": "my first project",
164+
"custom_build_name": "build 1",
165+
"npm_dependencies": [
166+
"npm-package-you-need-to-run-tests-1",
167+
"[email protected]"
168+
]
169+
}
170+
}
171+
```
172+
173+
### Configure Connection Settings
174+
175+
You can use the `connection_settings` option to specify the Local connection
176+
settings. This helps you in testing websites that cannot be accessed on the
177+
public network. You can download the Local Testing binary and establish a local
178+
connection first before you run the tests (you can learn how to do so
179+
[here](https://www.browserstack.com/local-testing/automate#command-line))
180+
181+
| Option | Description | Possible values |
182+
| ------------------ | ---------------------------------------------------------------------- | --------------- |
183+
| `local` | Helps in testing private web applications. | - |
184+
| `local_identifier` | The BrowserStack Local tunnel that should be used to resolve requests. | - |
185+
186+
Note that the `local_identifier` is applicable only when you start a Local
187+
binary with a local identifier. Your tests might fail if you use an invalid
188+
local identifier. This option will be ignored if `local` option is set to
189+
`false`.
190+
191+
Example:
192+
193+
```json
194+
{
195+
"connection_settings": {
196+
"local": false,
197+
"local_identifier": null
198+
}
66199
}
67200
```
68201

69-
The following table provides a reference for all the options that can be provided in `browserstack.json` shown above.
202+
### Disable Usage Reporting
70203

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

72-
| Option | Description | Possible values |
73-
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
74-
| `username` | This is your BrowserStack username. You can find this in your [Automate dashboard](https://automate.browserstack.com/) | - |
75-
| `access_key` | This is your BrowserStack access key. You can find this in your [Automate dashboard](https://automate.browserstack.com/) | - |
76-
| `os` <br/> (_case-sensitive_) | The operating system on which you want to run your test. | `OS X Mojave`, <br/> `OS X Catalina`, and <br/> `Windows 10` |
77-
| `browser` <br/> (case-sensitive) | The browser on which you want to run your tests. | `chrome`, <br/> `firefox`, and <br/> `edge` |
78-
| `versions` | A list of browser versions that you want to run your tests on. <br/><br/> **Example:** To run on versions 69, 67 and 65 provide `["69", "67", "65"]` | Right now edge 80 and all chrome versions from 66 to 78 are supported |
79-
| `specs` <br/> (_deprecated_) | This param is deprecated in favour of a more complete `cypress_proj_dir` param. The path to the spec files that need to be run on BrowserStack | Takes a list of strings that point to location of the spec files |
80-
| `cypress_proj_dir` | Path to the folder which contains `cypress.json` file. This path will be considered as the root path of the project. |- |
81-
| `project` | Name of your project. This will be displayed in your Automate dashboard, and you'll be able to search & filter your tests based on the project name. | A string providing the name of the project |
82-
| `customBuildName` | Helps in providing a custom name for the build. This will be displayed in your Automate dashboard, and you'll be able to search & filter your tests based on the build name. | A string providing the name of the build |
83-
| `local` | Helps in testing websites that cannot be accessed in public network. If you set this to `true`, please download the Local binary and establish a local connection first (you can learn how to do so [here](https://www.browserstack.com/local-testing/automate#command-line)) | Boolean: `true` / `false`. Set this to `true` if you need to test a local website. Set this to `false` if the website is accessible publicly. |
84-
| `localIdentifier` | The BrowserStack Local tunnel that should be used to resolve requests. This 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`. | A string if a tunnel identified by the Local identifier should be used (should be same as the one used to start the Local binary). Set this to `null` (default value) to resolve requests using Local without a Local identifier. |
210+
Example:
211+
212+
```json
213+
{
214+
"disable_usage_reporting": "false"
215+
}
216+
```
217+
218+
## CLI Arguments & Flags
219+
220+
### Running the Tests
85221

86-
### Running the tests
87222
You can start running your test build using the following command.
88223

89224
```bash
@@ -107,7 +242,8 @@ Sample output :
107242
[2/20/2020, 2:58:36 PM] File deleted successfully.
108243
```
109244

110-
### Getting build information
245+
### Getting the Build Information
246+
111247
In case you want to get information on the build you can use the following command
112248

113249
```bash
@@ -120,7 +256,7 @@ Example
120256
browserstack-cypress build-info 06f28ce423d10314b32e98bb6f68e10b0d02a49a
121257
```
122258

123-
Output:
259+
Sample output:
124260

125261
```bash
126262
[2/20/2020, 3:01:52 PM] Getting information for buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
@@ -184,7 +320,8 @@ Output:
184320

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

187-
### Stopping a running build
323+
### Stopping a Running Build
324+
188325
In case you want to stop a running build, you can use the following command
189326

190327
```bash
@@ -197,7 +334,7 @@ Example
197334
browserstack-cypress build-stop 06f28ce423d10314b32e98bb6f68e10b0d02a49a
198335
```
199336

200-
Output:
337+
Sample output:
201338

202339
```bash
203340
[3/24/2020, 2:31:11 PM] Stopping build with given buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
@@ -208,16 +345,14 @@ Output:
208345
}
209346
```
210347

211-
### Limitations
212-
213-
- `exec` and `task` are not allowed.
214-
- 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.
215-
- Installing custom npm packages are not supported at this moment.
216-
217-
# Accessing test results
348+
## Limitations
218349

219-
You can access your test results in [BrowserStack Automate dashboard](https://automate.browserstack.com/). The dashboard provides test details along with video, console logs and screenshots to help you debug any issues.
350+
- `exec` and `task` are not allowed.
351+
- While using local, please make sure to create `/etc/hosts` entry pointing to
352+
some URL, and use that URL in the tests. The `localhost` URI doesn't work at
353+
the moment. You can use `http://bs-local.com` instead, to replace `localhost`
354+
- Installing custom npm packages are not supported at this moment on macOS.
220355

221-
# License
356+
## License
222357

223358
This project is released under MIT License. Please refer the [LICENSE.md](LICENSE.md) for more details.

0 commit comments

Comments
 (0)