feat(runner): add a new method of getting browser drivers - directConnect

directConnect as an option on the configuration will replace chromeOnly.
Now, WebDriverJS allows Firefox to be used directly as well, so directConnect
will work for Chrome and Firefox, and throw an error if another browser is used.

This change deprecates but does not remove the chromeOnly option.

Author: juliemr

docs/browser-setup.md

@@ -57,7 +57,6 @@ capabilities: {
   }
 },
 ```
-If running with `chromeOnly` and `chromeOptions` together, chromeOptions.args and chromeOptions.extensions are required due to [Issue 6627](https://code.google.com/p/selenium/issues/detail?id=6627&thanks=6627&ts=1385488060) of selenium-webdriver currently(@2.37.0). So in order to avoid the issue, you may simply set them(or one of them) to an empty array.
 
 Testing Against Multiple Browsers
 ---------------------------------
@@ -170,8 +169,6 @@ exports.config = {
     'basic/*_spec.js'
   ],
 
-  chromeOnly: false,
-
   capabilities: {
     device: 'android',
     'browserName': '',
@@ -225,8 +222,6 @@ exports.config = {
     'basic/*_spec.js'
   ],
 
-  chromeOnly: false,
-
   capabilities: {
     browserName: '',
     device: 'iPhone',
@@ -246,8 +241,6 @@ exports.config = {
     'basic/*_spec.js'
   ],
 
-  chromeOnly: false,
-
   capabilities: {
     browserName: '',
     device: 'iPad',
@@ -321,8 +314,6 @@ exports.config = {
     'basic/*_spec.js'
   ],
 
-  chromeOnly: false,
-
   capabilities: {
     'browserName': 'android'
   },

docs/referenceConf.js

@@ -6,48 +6,47 @@
 
 exports.config = {
   // ---------------------------------------------------------------------------
-  // ----- How to setup Selenium -----------------------------------------------
+  // ----- How to connect to Browser Drivers -----------------------------------
   // ---------------------------------------------------------------------------
   //
-  // There are three ways to use the Selenium Server. Specify one of the
-  // following:
+  // Protractor needs to know how to connect to Drivers for the browsers
+  // it is testing on. This is usually done through a Selenium Server.
+  // There are four options - specify one of the following:
   //
   // 1. seleniumServerJar - to start a standalone Selenium Server locally.
   // 2. seleniumAddress - to connect to a Selenium Server which is already
   //    running.
   // 3. sauceUser/sauceKey - to use remote Selenium Servers via Sauce Labs.
-  //
-  // You can bypass a Selenium Server if you only want to test using Chrome.
-  // Set chromeOnly to true and ChromeDriver will be used directly (from the
-  // location specified in chromeDriver).
+  // 4. directConnect - to connect directly to the browser Drivers.
+  //    This option is only available for Firefox and Chrome.
 
+  // ---- 1. To start a standalone Selenium Server locally ---------------------
   // The location of the standalone Selenium Server jar file, relative
   // to the location of this config. If no other method of starting Selenium
   // Server is found, this will default to
   // node_modules/protractor/selenium/selenium-server...
   seleniumServerJar: null,
   // The port to start the Selenium Server on, or null if the server should
-  // find its own unused port.
+  // find its own unused port. Ignored if seleniumServerJar is null.
   seleniumPort: null,
   // Additional command line options to pass to selenium. For example,
   // if you need to change the browser timeout, use
-  // seleniumArgs: ['-browserTimeout=60'],
+  // seleniumArgs: ['-browserTimeout=60']
+  // Ignored if seleniumServerJar is null.
   seleniumArgs: [],
-  // ChromeDriver location is used to help the standalone Selenium Server
-  // find the chromedriver binary. This will be passed to the Selenium jar as
-  // the system property webdriver.chrome.driver. If null, Selenium will
+  // ChromeDriver location is used to help find the chromedriver binary.
+  // This will be passed to the Selenium jar as the system property
+  // webdriver.chrome.driver. If null, Selenium will
   // attempt to find ChromeDriver using PATH.
   chromeDriver: './selenium/chromedriver',
 
-  // If true, only ChromeDriver will be started, not a Selenium Server.
-  // Tests for browsers other than Chrome will not run.
-  chromeOnly: false,
-
+  // ---- 2. To connect to a Selenium Server which is already running ----------
   // The address of a running Selenium Server. If specified, Protractor will
   // connect to an already running instance of Selenium. This usually looks like
   // seleniumAddress: 'http://localhost:4444/wd/hub'
   seleniumAddress: null,
 
+  // ---- 3. To use remote browsers via Sauce Labs -----------------------------
   // If sauceUser and sauceKey are specified, seleniumServerJar will be ignored.
   // The tests will be run remotely using Sauce Labs.
   sauceUser: null,
@@ -58,6 +57,20 @@ exports.config = {
   // ondemand.saucelabs.com:80/wd/hub
   sauceSeleniumAddress: null,
 
+  // ---- 4. To connect directly to Drivers ------------------------------------
+  // Boolean. If true, Protractor will connect directly to the browser Drivers
+  // at the locations specified by chromeDriver and firefoxPath. Only Chrome
+  // and Firefox are supported for direct connect.
+  directConnect: false,
+  // Path to the firefox application binary. If null, will attempt to find
+  // firefox in the default locations.
+  firefoxPath: null,
+
+  // **DEPRECATED**
+  // If true, only ChromeDriver will be started, not a Selenium Server.
+  // This should be replaced with directConnect.
+  chromeOnly: false,
+
   // ---------------------------------------------------------------------------
   // ----- What tests to run ---------------------------------------------------
   // ---------------------------------------------------------------------------

docs/server-setup.md

@@ -1,9 +1,9 @@
 Setting Up the Selenium Server
 ==============================
 
-When working with Protractor you will most likely use the Selenium Server. The server acts as proxy between your test script (written with the WebDriver API) and the browser driver (controlled by the WebDriver protocols). 
+When working with Protractor, you need to specify how to connect to the browser drivers which will start up and control the browsers you are testing on. You will most likely use the Selenium Server. The server acts as proxy between your test script (written with the WebDriver API) and the browser driver (controlled by the WebDriver protocols).
 
-The server forwards commands from your script to the driver and returns responses from the driver to your script. The server can handle multiple scripts in different languages. The server can startup and manage multiple browsers in different versions and implementations. 
+The server forwards commands from your script to the driver and returns responses from the driver to your script. The server can handle multiple scripts in different languages. The server can startup and manage multiple browsers in different versions and implementations.
 
          [Test Scripts] < ------------ > [Selenium Server] < ------------ > [Browser Drivers]
 
@@ -35,6 +35,9 @@ To install and start the standalone Selenium Server manually, use the webdriver-
 
 3. Leave the server running while you conduct your test sessions.
 
+4. In your config file, set `seleniumAddress` to the address of the running server. This defaults to
+   `http://localhost:4444/wd/hub`.
+
 
 **Starting the Server from a Test Script**
 
@@ -67,13 +70,11 @@ In your config file, set these options:
 Please note that if you set `sauceUser` and `sauceKey`, the settings for `seleniumServerJar`, `seleniumPort` and `seleniumArgs` will be ignored.
 
 
-Selenium Server and the Chrome Browser
+Connecting Directly to Browser Drivers
 --------------------------------------
 
-The Selenium Server is optional when you test against the Chrome browser. In your config file, you can set the chromeOnly option to true or false:
-
- - `chromeOnly: false` -  Your test script communicates with the Selenium Server (running locally or remotely). This is the default setting.
+Protractor can test directly against Chrome and Firefox without using a Selenium Server. To use this, in your config file set `directConnect: true`.
 
- - `chromeOnly: true` -  Your test script communicates directly with the ChromeDriver. The Selenium Server (running locally or remotely) will be ignored.
+ - `directConnect: true` -  Your test script communicates directly Chrome Driver or Firefox Driver, bypassing any Selenium Server. If this is true, settings for `seleniumAddress` and `seleniumServerJar` will be ignored. If you attempt to use a browser other than Chrome or Firefox an error will be thrown.
 
-The advantage of running only with Chrome is that your test scripts will start up and run faster. For more detailed information about chromeOnly, see the [chrome.js source code](https://code.google.com/p/selenium/source/browse/javascript/node/selenium-webdriver/chrome.js).
+The advantage of directly connecting to browser drivers is that your test scripts may start up and run faster.

example/chromeOnlyConf.js

@@ -1,7 +1,6 @@
 // An example configuration file.
 exports.config = {
-  // The address of a running selenium server.
-  seleniumAddress: 'http://localhost:4444/wd/hub',
+  directConnect: true,
 
   // Capabilities to be passed to the webdriver instance.
   capabilities: {

example/conf.js

@@ -141,11 +141,13 @@ ConfigParser.getSpecs = function(config) {
 ConfigParser.prototype.addConfig_ = function(additionalConfig, relativeTo) {
   // All filepaths should be kept relative to the current config location.
   // This will not affect absolute paths.
-  ['seleniumServerJar', 'chromeDriver', 'onPrepare'].forEach(function(name) {
-    if (additionalConfig[name] && typeof additionalConfig[name] === 'string') {
-      additionalConfig[name] =
-          path.resolve(relativeTo, additionalConfig[name]);
-    }
+  ['seleniumServerJar', 'chromeDriver', 'onPrepare', 'firefoxPath'].
+      forEach(function(name) {
+        if (additionalConfig[name] &&
+            typeof additionalConfig[name] === 'string') {
+          additionalConfig[name] =
+              path.resolve(relativeTo, additionalConfig[name]);
+        }
   });
 
   // Make sure they're not trying to add in deprecated config vals.
@@ -154,6 +156,12 @@ ConfigParser.prototype.addConfig_ = function(additionalConfig, relativeTo) {
     throw new Error('Using config.jasmineNodeOpts.specFolders is deprecated ' +
         'since Protractor 0.6.0. Please switch to config.specs.');
   }
+
+  // chromeOnly is deprecated, use directConnect instead.
+  if (additionalConfig.chromeOnly) {
+    console.log('Warning: chromeOnly is deprecated. Use directConnect');
+    additionalConfig.directConnect = true;
+  }
   merge_(this.config_, additionalConfig);
 };