Skip to content

Update README.md to reflect custom command support #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 8, 2020
Merged

Update README.md to reflect custom command support #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 31 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,14 @@
- [License](#license)

# BrowserStack Cypress CLI
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.
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:


| Windows 10 | OS X Mojave | OS X Catalina |
|---------------------|:---------------------:|--------------------:|
| chrome 66.0 to 79.0 | chrome 66.0 to 79.0 | chrome 66.0 to 79.0 |
| edge 80.0 | edge 80.0 | edge 80.0 |
| firefox 60.0 to 72.0| firefox 60.0 to 72.0 | firefox 60.0 to 72.0|
|:---------------------:|:---------------------:|:--------------------:|
| Chrome 66.0 to 79.0 | Chrome 66.0 to 79.0 | Chrome 66.0 to 79.0 |
| Edge 80.0 | Edge 80.0 | Edge 80.0 |
| Firefox 60.0 to 72.0| Firefox 60.0 to 72.0 | Firefox 60.0 to 72.0|


We are actively working on supporting other browsers and will start adding other browsers to this list.
Expand All @@ -26,24 +26,26 @@ We are actively working on supporting other browsers and will start adding other

### Installing browserstack-cypress
```bash
# Install cypress(ignore if already done)
# Install cypress (ignore if already done)
$ npm install -g [email protected]
# Install dependencies

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

### Configuring your tests
```bash
# create a sample configuration file for configurations and capabiltiies
# create a sample configuration file for configurations and capabilities
$ browserstack-cypress init
```
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.

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.

```json
{
"auth": {
"username": "<username>",
"access_key": "<access-key>"
"username": "<your-browserstack-username>",
"access_key": "<your-browserstack-access-key>"
},
"browsers": [
{
Expand All @@ -53,30 +55,31 @@ This will create a sample browserstack.json file. This file can be used to confi
}
],
"run_settings": {
"cypress": "/path/to/directory-of-<cypress.json>-file",
"project": "test",
"customBuildName": "cypress build"
"cypress_proj_dir": "/path/to/directory-that-contains-<cypress.json>-file",
"project": "my first project",
"customBuildName": "build 1"
},
"connection_settings": {
"local": false
}
}
```

The following table provides a reference for all the options that can be provided in browserstack.json shown above.
The following table provides a reference for all the options that can be provided in `browserstack.json` shown above.


| Option | Description | Possible values |
|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| 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/) | - |
| 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/) | - |
| 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" |
| browser (case-sensitive) | The browser in which you want to run your tests on. | Right now only "chrome", "firefox", and "edge" are supported. We are actively working on supporting other browsers. |
| 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 |
| cypress | Path to the folder which contains `cypress.json` file. This path will be considered as the root path of the project. |- |
| project | Name of the project | A string providing the name of the project |
| customBuildName | Helps in providing a custom name for the build | A string providing the name of the build |
| 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. |
| `username` | This is your BrowserStack username. You can find this in your [Automate dashboard](https://automate.browserstack.com/) | - |
| `access_key` | This is your BrowserStack access key. You can find this in your [Automate dashboard](https://automate.browserstack.com/) | - |
| `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` |
| `browser` <br/> (case-sensitive) | The browser on which you want to run your tests. | `chrome`, <br/> `firefox`, and <br/> `edge` |
| `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 |
| `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 |
| `cypress_proj_dir` | Path to the folder which contains `cypress.json` file. This path will be considered as the root path of the project. |- |
| `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 |
| `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 |
| `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. |

### Running the tests
You can start running your test build using the following command.
Expand All @@ -85,7 +88,7 @@ You can start running your test build using the following command.
$ browserstack-cypress run
```

Output :
Sample output :

```bash
[2/20/2020, 2:58:31 PM] Reading browserstack.json from /browserstack.json
Expand Down Expand Up @@ -177,12 +180,12 @@ Output:
}
```

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

### Limitations

- `exec` and `task` are not allowed.
- While using local, please make sure to create /etc/hosts entry pointing to a URL. The `localhost` is not working at the moment.
- 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.
- Installing custom npm packages are not supported at this moment.

# Accessing test results
Expand All @@ -191,4 +194,4 @@ You can access your test results in [BrowserStack Automate dashboard](https://au

# License

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