Merge pull request #9 from browserstack/custom_commands

Support for Custom Commands

Author: suryart

README.md

@@ -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.
@@ -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": [
       {
@@ -53,30 +55,31 @@ This will create a sample browserstack.json file. This file can be used to confi
       }
     ],
     "run_settings": {
-      "specs": ["folder_path_with_files/*.js"],
-      "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 |
-| 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                                                              |
-| 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.
@@ -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
@@ -97,7 +100,9 @@ Output :
 [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.
 ```
 
 ### Getting build information
@@ -175,19 +180,18 @@ 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.
-- `baseUrl` is not supported at the moment.
-- Environment variables and configuration files are not supported yet.
-- 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
 
 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.
 
 # 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.

bin/commands/runs.js

@@ -21,7 +21,7 @@ function runCypress(args) {
   capabilityHelper.validate(bsConfig).then(function (validated) {
     logger.log(validated);
     // Archive the spec files
-    archiver.archive(bsConfig.run_settings.specs, config.fileName).then(function (data) {
+    archiver.archive(bsConfig.run_settings, config.fileName).then(function (data) {
       // Uploaded zip file
       zipUploader.zipUpload(bsConfig, config.fileName).then(function (zip) {
         // Create build

bin/helpers/archiver.js

@@ -1,15 +1,14 @@
 
-var fs = require('fs');
-var archiver = require('archiver');
-var request = require('request')
-var config = require('./config');
-var logger = require("./logger")
+const fs = require('fs'),
+  archiver = require('archiver'),
+  logger = require("./logger");
 
-
-const archiveSpecs = (specs, filePath) => {
+const archiveSpecs = (runSettings, filePath) => {
   return new Promise(function (resolve, reject) {
     var output = fs.createWriteStream(filePath);
 
+    var cypressFolderPath = runSettings.cypress_proj_dir
+
     var archive = archiver('zip', {
       zlib: { level: 9 } // Sets the compression level.
     });
@@ -36,10 +35,7 @@ const archiveSpecs = (specs, filePath) => {
 
     archive.pipe(output);
 
-    specs.forEach(function (item, index) {
-      logger.log("Adding  " + item + " to zip");
-      archive.glob(item);
-    });
+    archive.directory(cypressFolderPath, false);
 
     archive.finalize();
   });

bin/helpers/capabilityHelper.js

@@ -1,5 +1,6 @@
-var logger = require("./logger");
-const Constants = require('./constants');
+const logger = require("./logger"),
+  Constants = require('./constants'),
+  glob = require("glob");
 
 const caps = (bsConfig, zip) => {
   return new Promise(function (resolve, reject) {
@@ -67,12 +68,51 @@ const validate = (bsConfig) => {
 
     if (!bsConfig.run_settings) reject(Constants.validationMessages.EMPTY_RUN_SETTINGS);
 
-    if(!bsConfig.run_settings.specs || bsConfig.run_settings.specs.length === 0) reject(Constants.validationMessages.EMPTY_SPEC_FILES);
+    if(!bsConfig.run_settings.cypress_proj_dir) reject(Constants.validationMessages.EMPTY_SPEC_FILES);
+
+    if(invalidFiles(bsConfig.run_settings.cypress_proj_dir)) reject(Constants.validationMessages.INVALID_EXTENSION);
 
     resolve(Constants.validationMessages.VALIDATED);
   });
 }
 
+const invalidFiles = (testFolder)=> {
+  var options = {
+    dot: true
+  }
+  files  = glob.sync(testFolder + "/**/*", options)
+  var invalidFiles = []
+  files.forEach(file => {
+    if(isHiddenPath(file) || invalidExtension(file)){
+      invalidFiles.push(file)
+    }
+  });
+
+  if(invalidFiles.length > 0) {
+    logger.log("These files are not valid: " + invalidFiles.toString())
+    return true
+  } else {
+    return false
+  }
+}
+
+var isHiddenPath = (path) => {
+  return (/(^|\/)\.[^\/\.]/g).test(path);
+};
+
+var invalidExtension = (file) => {
+  let ext = file.split('.').pop();
+  if (isFile(file) && !["js", "json", "txt"].includes(ext)) {
+    return true;
+  }
+
+  return false;
+}
+
+var isFile = (path) => {
+  return path.split('/').pop().indexOf('.') > -1;
+}
+
 module.exports = {
   caps,
   validate

bin/helpers/constants.js

@@ -20,7 +20,8 @@ const validationMessages = {
     EMPTY_RUN_SETTINGS: "Empty run settings",
     EMPTY_SPEC_FILES: "No spec files specified in run_settings",
     VALIDATED: "browserstack.json file is validated",
-    NOT_VALID: "browerstack.json is not valid"
+    NOT_VALID: "browerstack.json is not valid",
+    INVALID_EXTENSION: "Invalid files, please remove these files and try again."
 };
 const cliMessages = {
     VERSION: {

bin/templates/configTemplate.js

@@ -12,7 +12,7 @@ module.exports = function () {
       }
     ],
     "run_settings": {
-      "specs": ["folder_path_with_files/*.js"],
+      "cypress_proj_dir" : "/path/to/cypress.json",
       "project": "project-name",
       "customBuildName": "build-name"
     },