Skip to content

Commit 92bf9b5

Browse files
suryartsuryart
committed
Adding CLI usage instructions and License.
- Updated readme with the table of contents. - Updated sections with installation, configuration, and using the cli - Added the License file for release.
1 parent a698cc8 commit 92bf9b5

File tree

3 files changed

+190
-9
lines changed

3 files changed

+190
-9
lines changed

‎LICENSE.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright 2020 BrowserStack
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 180 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,190 @@
1-
# browserstack-cypress-cli
2-
NPM package to run Cypress on Browserstack Infra
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)
310

4-
# Setup
11+
# 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.
513

14+
15+
| Windows 10 | OS X Mojave | OS X Catalina |
16+
|---------------------|:---------------------:|--------------------:|
17+
| chrome 66.0 to 78.0 | chrome 66.0 to 78.0 | chrome 66.0 to 78.0 |
18+
| edge 80.0 | edge 80.0 | edge 80.0 |
19+
20+
21+
We are actively working on supporting other browsers and will start adding other browsers to this list.
22+
23+
## Using BrowserStack-Cypress CLI:
24+
25+
26+
### Installing browserstack-cypress
627
```bash
728
# Install dependencies
8-
$ npm install
9-
$ npm link
29+
$ npm install --save-dev browserstack-cypress-cli
30+
```
1031

32+
### Configuring your tests
33+
```bash
1134
# create a sample configuration file for configurations and capabiltiies
1235
$ browserstack-cypress init
36+
```
37+
This will create a sample browserstack.json file. This file can be used to configure your tests on BrowserStack. Below is the sample file that is generated for your reference.
38+
39+
```JS
40+
{
41+
"auth": {
42+
"username": "<username>",
43+
"access_key": "<access-key>"
44+
},
45+
"browsers": [
46+
{
47+
"browser": "chrome",
48+
"os": "OS X Catalina",
49+
"versions": ["69","66"]
50+
}
51+
],
52+
"run_settings": {
53+
"specs": ["folder_path_with_files/*.js"],
54+
"project": "test",
55+
"customBuildName": "cypress build"
56+
},
57+
"connection_settings": {
58+
"local": false
59+
}
60+
}
61+
```
62+
63+
The following table provides a reference for all the options that can be provided in browserstack.json shown above.
64+
65+
66+
| Option | Description | Possible values |
67+
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
68+
| username | These are the BrowserStack credentials that need to be provided to run a test on BrowserStack. You can find this in your [automate dashboard](https://automate.browserstack.com/) | - |
69+
| access_key | These are the BrowserStack credentials that need to be provided to run a test on BrowserStack. You can find this in your [automate dashboard](https://automate.browserstack.com/) | - |
70+
| os(case-sensitive) | The operating system in which you want to run your test. | The following three strings are supported."OS X Mojave" , "OS X Catalina", "Windows 10" |
71+
| browser(case-sensitive) | The browser in which you want to run your tests on. | Right now only "chrome" and "edge" are supported. We are actively working on supporting other browsers. |
72+
| versions | A list of browser versions that you need to run your tests on | 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 |
73+
| specs | 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 |
74+
| project | Name of the project | A string providing the name of the project |
75+
| customBuildName | Helps in providing a custom name for the build | A string providing the name of the build |
76+
| local(boolean: true/false) | Helps in testing websites that cannot be accessed in public network | Set this to true if you need to test a local website. Set this to false if the website is accessible publically. |
77+
78+
### Running the tests
79+
You can start running your test build using the following command.
1380

14-
# create a cypress build on cypress
81+
```bash
1582
$ browserstack-cypress run
1683
```
84+
85+
Output :
86+
87+
```bash
88+
[2/20/2020, 2:58:31 PM] Reading browserstack.json from /browserstack.json
89+
[2/20/2020, 2:58:31 PM] browserstack.json file is validated
90+
[2/20/2020, 2:58:31 PM] Adding tests/*.js to zip
91+
[2/20/2020, 2:58:34 PM] Zip uploaded with url: bs://15f90b540b8cbc47929782f35bb7db20fe1c4709
92+
[2/20/2020, 2:58:34 PM] File deleted successfully
93+
[2/20/2020, 2:58:34 PM] Browser list: OS X Catalina-chrome69,OS X Catalina-chrome66
94+
[2/20/2020, 2:58:34 PM] Test suite: bs://15f90b540b8cbc47929782f35bb7db20fe1c4709
95+
[2/20/2020, 2:58:34 PM] Local is set to: false
96+
[2/20/2020, 2:58:34 PM] Build name is: cypress build
97+
[2/20/2020, 2:58:36 PM] Build created with build id: 06f28ce423d10314b32e98bb6f68e10b0d02a49a
98+
```
99+
100+
### Getting build information
101+
In case you want to get information on the build you can use the following command
102+
103+
```bash
104+
browserstack-cypress build <buildId>
105+
```
106+
107+
Example
108+
109+
```bash
110+
browserstack-cypress build 06f28ce423d10314b32e98bb6f68e10b0d02a49a
111+
```
112+
113+
Output:
114+
115+
```bash
116+
[2/20/2020, 3:01:52 PM] Getting information for buildId 06f28ce423d10314b32e98bb6f68e10b0d02a49a
117+
[2/20/2020, 3:01:52 PM] Reading browserstack.json from /browserstack.json
118+
[2/20/2020, 3:01:54 PM] Build info for build id:
119+
{
120+
"build_id": "06f28ce423d10314b32e98bb6f68e10b0d02a49a",
121+
"framework": "cypress",
122+
"status": "done",
123+
"input_capabilities": {
124+
"devices": [
125+
"OS X Catalina-chrome69",
126+
"OS X Catalina-chrome66"
127+
],
128+
"testSuite": "15f90b540b8cbc47929782f35bb7db20fe1c4709",
129+
"customBuildName": "cypress build",
130+
"local": false,
131+
"localIdentifier": null,
132+
"callbackURL": null,
133+
"projectNotifyURL": null,
134+
"project": "test"
135+
},
136+
"start_time": "2020-02-20 09:28:35 UTC",
137+
"device_statuses": {
138+
"success": {
139+
"OS X Catalina-chrome69": "Success",
140+
"OS X Catalina-chrome66": "Success"
141+
},
142+
"error": {}
143+
},
144+
"test_suite_details": {
145+
"url": "bs://15f90b540b8cbc47929782f35bb7db20fe1c4709",
146+
"name": "tests.zip",
147+
"size": 354
148+
},
149+
"duration": "33 seconds",
150+
"devices": {
151+
"OS X Catalina-chrome69": {
152+
"session_id": "3b4038cbbc55d34c1b33c930f3417c7c534c25dd",
153+
"status": "done",
154+
"test_status": {
155+
"failed": 0,
156+
"success": 3,
157+
"queued": 0,
158+
"ignored": 0
159+
}
160+
},
161+
"OS X Catalina-chrome66": {
162+
"session_id": "fbda8eb5a9eeb7823a9ef7be1a42213c568197e8",
163+
"status": "done",
164+
"test_status": {
165+
"failed": 0,
166+
"success": 3,
167+
"queued": 0,
168+
"ignored": 0
169+
}
170+
}
171+
}
172+
}
173+
```
174+
175+
**Note** that individual version represents a session. It is advised to validate your account's parallel before running multiple versions.
176+
177+
### Limitations
178+
179+
- `exec` and `task` are not allowed.
180+
- `baseUrl` is not supported at the moment.
181+
- Environment variables and configuration files are not supported yet.
182+
- While using local, please make sure to create /etc/hosts entry pointing to a URL. The `localhost` is not working at the moment.
183+
184+
# Accessing test results
185+
186+
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.
187+
188+
# License
189+
190+
This project is released under MIT License. Please refer the [LICENSE.md](LICENSE.md) for more detail.

‎package.json

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
{
22
"name": "browserstack-cypress-cli",
33
"version": "1.0.0",
4-
"description": "",
4+
"description": "BrowserStack Cypress CLI for Cypress integration with BrowserStack's remote devices.",
55
"main": "index.js",
66
"scripts": {
77
"test": "echo \"Error: no test specified\" && exit 1"
88
},
9-
"author": "",
10-
"license": "ISC",
9+
"author": "BrowserStack",
10+
"license": "MIT",
1111
"bin": {
1212
"browserstack-cypress": "bin/runner.js"
1313
},

0 commit comments

Comments
 (0)