Merge pull request #97 from jzaefferer/optimize-console-output

Optimize console output
browserstack · Oct 21, 2014 · 438b5d6 · 438b5d6
2 parents 7514603 + bb6b3d3
commit 438b5d6
Show file tree

Hide file tree

Showing 15 changed files with 379 additions and 355 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,12 @@
+# This file is for unifying the coding style for different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
diff --git a/.jshintrc b/.jshintrc
@@ -0,0 +1,16 @@
+{
+  "boss": true,
+  "curly": true,
+  "eqeqeq": true,
+  "eqnull": true,
+  "expr": true,
+  "immed": true,
+  "noarg": true,
+  "node": true,
+  "quotmark": "single",
+  "smarttabs": true,
+  "sub": true,
+  "trailing": true,
+  "undef": true,
+  "unused": true
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+## Contributing to browserstack-runner
+
+Your help improving this project is welcome!
+
+## Got a question or problem? Found an issue?
+
+If you have questions about how to use this tool, or you found a bug in the source code or a mistake in the documentation, [file an issue](https://github.com/browserstack/browserstack-runner/issues/new).
+
+## Want to contribute code?
+
+If you found an issue and want to contribute a fix or implement a new feature, send a pull request!
+
+To make changes: [Fork the repo, clone it locally](https://help.github.com/articles/fork-a-repo/), make a branch for your change, then implement it.
+
+Install some dependencies:
+
+    npm install
+
+Then run tests with:
+
+    npm test
+
+This runs some unit tests (consider adding more to `tests/unit`) and runs some other tools like jshint. Make sure to fix lint issues it finds.
+
+To test your change with another project where you use the tool, use `npm-link`:
+
+    # in your browserstack-runner checkout
+    npm link
+    # in your project
+    npm link browserstack-runner
+
+Or do a local install:
+
+    # in your project
+    npm install /path/to/checkout/browserstack-runner
+
+Once done, commit, push the branch to your repo and [create a pull request](https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request).
diff --git a/README.md b/README.md
@@ -1,178 +1,124 @@
 A command line interface to run browser tests over BrowserStack.
 
-## Install
-Go to the `browserstack-runner` directory.
-Install browserstack-runner
+## Usage
 
-    npm -g install
+Install globally:
 
-or
+    npm -g install browserstack-runner
 
+Then, after setting up the configuration, run tests with:
 
-For development,
+    browserstack-runner
 
-    npm link
+You can also install locally and run the local binary:
 
-## Configuration
-To run browser tests on BrowserStack infrastructure, you need to
-create a `browserstack.json` file in project's root directory (the
-directory from which tests are run), by running this command:
-
-    browserstack-runner init [preset]
-
-If nothing is provided as `preset` **default** is used.
-
-> Currently only one preset is present: **default**
+    npm install browserstack-runner
+    node_modules/.bin/browserstack-runner
 
-### Parameters
-
- - *username*: BrowserStack username
-   (Alternatively: use `BROWSERSTACK_USERNAME` environment variable)
-
- - *key*: BrowserStack key
-   (Alternatively: use `BROWSERSTACK_KEY` environment variable)
+## Configuration
 
- - *test_path*: Path to the which will execute the tests when opened
-   in a browser.
+To run browser tests on BrowserStack infrastructure, you need to create a `browserstack.json` file in project's root directory (the directory from which tests are run), by running this command:
 
- - *test_framework*: Specify test framework which will execute the tests.
-    We support qunit, jasmine, jasmine 2.0 and mocha.
+    browserstack-runner init
 
- - *timeout*: Specify worker timeout with BrowserStack.
+### Parameters for `browserstack.json`
 
- - *browsers*: A list of browsers on which tests are to be run.
+ * `username`: BrowserStack username (Or `BROWSERSTACK_USERNAME` environment variable)
+ * `key`: BrowserStack [access key](https://www.browserstack.com/accounts/local-testing) (Or `BROWSERSTACK_KEY` environment variable)
+ * `test_path`: Path to the test page which will run the tests when opened in a browser.
+ * `test_framework`: Specify test framework which will run the tests. Currently supporting qunit, jasmine, jasmine2 and mocha.
+ * `timeout`: Specify worker timeout with BrowserStack.
+ * `browsers`: A list of browsers on which tests are to be run. Find a [list of all supported browsers and platforms on browerstack.com](http://www.browserstack.com/list-of-browsers-and-platforms?product=live).
+ * `proxy`: Specify a proxy to use for the local tunnel. Object with `host`, `port`, `username` and `password` properties.
 
-A sample configuration file (list: http://www.browserstack.com/list-of-browsers-and-platforms?product=live):
+A sample configuration file:
 
 ```json
 {
   "username": "<username>",
-  "key": "<key>",
-  "test_framework": "qunit/jasmine/jasmine2/mocha",
+  "key": "<access key>",
+  "test_framework": "qunit|jasmine|jasmine2|mocha",
   "test_path": ["relative/path/to/test/page1", "relative/path/to/test/page2"],
-  "browsers":   [{
-    "browser": "firefox",
-    "browser_version": "15.0",
-    "device": null,
-    "os": "OS X",
-    "os_version": "Snow Leopard"
-  },
-  {
-    "browser": "firefox",
-    "browser_version": "16.0",
-    "device": null,
-    "os": "Windows",
-    "os_version": "7"
-  },
-  {
-    "browser": "firefox",
-    "browser_version": "17.0",
-    "device": null,
-    "os": "Windows",
-    "os_version": "8"
-  },
-  {
-    "browser": "ie",
-    "browser_version": "8.0",
-    "device": null,
-    "os": "Windows",
-    "os_version": "7"
-  },
-  {
-    "browser": "ie",
-    "browser_version": "9.0",
-    "device": null,
-    "os": "Windows",
-    "os_version": "7"
-  },
-  {
-    "os": "android",
-    "os_version": "4.0",
-    "device": "Samsung Galaxy Nexus"
-  },
-  {
-    "os": "ios",
-    "os_version": "7.0",
-    "device": "iPhone 5S"
-  },
-  {
-    "browser": "ie",
-    "browser_version": "10.0",
-    "device": null,
-    "os": "Windows",
-    "os_version": "8"
-  }]
-}
-```
-
-#### Compact `browsers` configuration
-
-Alternatively, if `os` and `os_version` granularity is not desired, following configuration can be used:
-- *browser*_current or *browser*_latest: will assign the latest version of the *browser*.
-- *browser*_previous: will assign the previous version of the *browser*.
-- *browser*_*version*: will assign the *version* specificed of the *browser*. Minor versions can be concatinated with underscore.
-
-Example:
-```json
-"browsers": [
-    "chrome_previous",
-    "chrome_latest",
-    "firefox_previous",
-    "firefox_latest",
-    "ie_6",
-    "ie_11",
-    "opera_12_1",
-    "safari_5_1",
+  "browsers": [
     {
       "browser": "ie",
       "browser_version": "10.0",
       "device": null,
       "os": "Windows",
       "os_version": "8"
+    },
+    {
+      "os": "android",
+      "os_version": "4.0",
+      "device": "Samsung Galaxy Nexus"
+    },
+    {
+      "os": "ios",
+      "os_version": "7.0",
+      "device": "iPhone 5S"
     }
-]
+  ]
+}
 ```
 
-### Enviroment variables
-
-* `BROWSERSTACK_USERNAME`:
-BrowserStack user name.
+#### Compact `browsers` configuration
 
-* `BROWSERSTACK_KEY`:
-BrowserStack key.
+When `os` and `os_version` granularity is not desired, following configuration can be used:
+ * `[browser]_current` or *browser*_latest: will assign the latest version of the *browser*.
+ * `[browser]_previous`: will assign the previous version of the *browser*.
+ * `[browser]_[version]`: will assign the *version* specificed of the *browser*. Minor versions can be concatinated with underscores.
 
-* `TUNNEL_ID`:
-Identifier for the current instance of the tunnel process. In `TRAVIS` setup `TRAVIS_JOB_ID` will be the default identifier.
+This can also be mixed with fine-grained configuration.
 
-* `BROWSERSTACK_JSON`:
-Path to the browserstack.json file. If null, `browserstack.json` in the root directory will be used.
+Example:
+```json
+{
+  "browsers": [
+      "chrome_previous",
+      "chrome_latest",
+      "firefox_previous",
+      "firefox_latest",
+      "ie_6",
+      "ie_11",
+      "opera_12_1",
+      "safari_5_1",
+      {
+        "browser": "ie",
+        "browser_version": "10.0",
+        "device": null,
+        "os": "Windows",
+        "os_version": "8"
+      }
+  ]
+}
+```
 
 ### Proxy support for BrowserStack local
+
 Add the following in `browserstack.json`
 ```json
-...
-"proxy": {
-    "host": "localhost",
-    "port": 3128,
-    "username": "foo",
-    "password": "bar"
+{
+  "proxy": {
+      "host": "localhost",
+      "port": 3128,
+      "username": "foo",
+      "password": "bar"
+  }
 }
-...
 ```
 
-### Secure Information
+### Supported environment variables
+
+To avoid duplication of system or user specific information across several configuration files, use these environment variables:
 
-To prevent checking in the BrowserStack `username` and `key` in your
-source control, the corresponding environment variables can be used.
+* `BROWSERSTACK_USERNAME`: BrowserStack user name.
+* `BROWSERSTACK_KEY`: BrowserStack key.
+* `TUNNEL_ID`: Identifier for the current instance of the tunnel process. In `TRAVIS` setup `TRAVIS_JOB_ID` will be the default identifier.
+* `BROWSERSTACK_JSON`: Path to the browserstack.json file. If null, `browserstack.json` in the root directory will be used.
 
-The environment variables then can be safely provided in the build
-configuration. For example, with travis-ci you can follow:
 
-http://about.travis-ci.org/docs/user/build-configuration/#Secure-environment-variables
+### Secure Information
 
-## Running tests
-Run `browserstack-runner` to run the tests on all the browsers mentioned
-in the configuration.
+To avoid checking in the BrowserStack `username` and `key` in your source control system, the corresponding environment variables can be used.
 
-You can include this in your test script to automatically run cross
-browser tests on every build.
+These can also be provided by a build server, for example [using secure environment variables on Travis CI](http://about.travis-ci.org/docs/user/build-configuration/#Secure-environment-variables).