[js] Make geckodriver the default for firefox

- Look for geckodriver, not wires

Close #2189

Author: jleyba

javascript/node/selenium-webdriver/CHANGES.md

@@ -9,13 +9,17 @@
 * Internal cleanup replacing uses of managed promises with native promises
 * Removed the mandatory use of Firefox Dev Edition, when using Marionette driver
 * Fixed timeouts' URL
+
+### API Changes
+
 * `promise.Deferred` is no longer a thenable object.
 * `Options#addCookie()` now takes a record object instead of 7 individual
   parameters. A TypeError will be thrown if addCookie() is called with invalid
   arguments.
 * When adding cookies, the desired expiry must be provided as a Date or in
   _seconds_ since epoch. When retrieving cookies, the expiration is always
   returned in seconds.
+*  Renamed `firefox.Options#useMarionette` to `firefox.Options#useGeckoDriver`
 * Removed deprecated modules:
    - `selenium-webdriver/error` (use `selenium-webdriver/lib/error`,\
      or the `error` property exported by `selenium-webdriver`)

javascript/node/selenium-webdriver/README.md

@@ -10,20 +10,23 @@ Selenium may be installed via npm with
 
     npm install selenium-webdriver
 
-Out of the box, Selenium includes everything you need to work with Firefox. You
-will need to download additional components to work with the other major
-browsers. The drivers for Chrome, PhantomJS, Opera, and Microsoft's IE and Edge
-web browsers are all standalone executables that should be available on your
-[PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29). The SafariDriver
-browser extension should be installed in your browser before using Selenium; we
-recommend disabling the extension when using the browser without Selenium or
-installing the extension in a profile only used for testing.
+You will need to download additional components to work with each of the major
+browsers. The drivers for Chrome, Firefox, PhantomJS, Opera, and 
+Microsoft's IE and Edge web browsers are all standalone executables that should
+be placed on your system [PATH]. The SafariDriverbrowser extension should be
+installed in your browser before using Selenium; we recommend disabling the
+extension when using the browser without Selenium or installing the extension in
+a profile only used for testing.
+
+> **NOTE:**  Mozilla's [geckodriver] is only required for Firefox 47+.
+> Everything you need for Firefox 38-46 is included with this package.
 
 | Browser           | Component                          |
 | ----------------- | ---------------------------------- |
 | Chrome            | [chromedriver(.exe)][chrome]       |
 | Internet Explorer | [IEDriverServer.exe][release]      |
 | Edge              | [MicrosoftWebDriver.msi][edge]     |
+| Firefox 47+       | [geckodriver(.exe)][geckodriver]   |
 | PhantomJS         | [phantomjs(.exe)][phantomjs]       |
 | Opera             | [operadriver(.exe)][opera]         |
 | Safari            | [SafariDriver.safariextz][release] |
@@ -213,6 +216,7 @@ specific language governing permissions and limitations
 under the License.
 
 [LTS]: https://github.com/nodejs/LTS
+[PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
 [api]: http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/
 [cla]: http://goo.gl/qC50R
 [chrome]: http://chromedriver.storage.googleapis.com/index.html
@@ -221,6 +225,7 @@ under the License.
 [opera]: https://github.com/operasoftware/operachromiumdriver/releases
 [phantomjs]: http://phantomjs.org/
 [edge]: http://go.microsoft.com/fwlink/?LinkId=619687
+[geckodriver]: https://github.com/mozilla/geckodriver/releases/
 [reduction]: http://www.webkit.org/quality/reduction.html
 [release]: http://selenium-release.storage.googleapis.com/index.html
 [users]: https://groups.google.com/forum/#!forum/selenium-users

javascript/node/selenium-webdriver/firefox/index.js

@@ -17,6 +17,9 @@
 
 /**
  * @fileoverview Defines the {@linkplain Driver WebDriver} client for Firefox.
+ * Before using this module, you must download the latest
+ * [geckodriver release] and ensure it can be found on your system [PATH].
+ *
  * Each FirefoxDriver instance will be created with an anonymous profile,
  * ensuring browser historys do not share session data (cookies, history, cache,
  * offline storage, etc.)
@@ -90,6 +93,20 @@
  *         .usingServer('http://127.0.0.1:4444/wd/hub')
  *         .setFirefoxOptions(options)
  *         .build();
+ *
+ * __Testing Older Versions of Firefox__
+ *
+ * To test versions of Firefox prior to Firefox 47, you must disable the use of
+ * the geckodriver using the {@link Options} class.
+ *
+ *     var options = new firefox.Options().useGeckoDriver(false);
+ *     var driver = new firefox.Driver(options);
+ *
+ * Alternatively, you may disable the geckodriver at runtime by setting the
+ * environment variable `SELENIUM_MARIONETTE=false`.
+ *
+ * [geckodriver release]: https://github.com/mozilla/geckodriver/releases/
+ * [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
  */
 
 'use strict';
@@ -158,7 +175,7 @@ class Options {
     this.proxy_ = null;
 
     /** @private {boolean} */
-    this.marionette_ = false;
+    this.marionette_ = true;
   }
 
   /**
@@ -214,12 +231,14 @@ class Options {
   }
 
   /**
-   * Sets whether to use Mozilla's Marionette to drive the browser.
+   * Sets whether to use Mozilla's geckodriver to drive the browser. This option
+   * is enabled by default and required for Firefox 47+.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver
+   * @param {boolean} enable Whether to enable the geckodriver.
+   * @see https://github.com/mozilla/geckodriver
    */
-  useMarionette(marionette) {
-    this.marionette_ = marionette;
+  useGeckoDriver(enable) {
+    this.marionette_ = enable;
     return this;
   }
 
@@ -247,10 +266,8 @@ class Options {
   }
 }
 
-// TODO: Wires is the old name of GeckoDriver. Rename to geckodriver, once the
-// first renamed version is out at
-// https://github.com/mozilla/geckodriver/releases
-const GECKO_DRIVER_EXE = process.platform === 'win32' ? 'wires.exe' : 'wires';
+const GECKO_DRIVER_EXE =
+    process.platform === 'win32' ? 'geckodriver.exe' : 'geckodriver';
 
 
 /**
@@ -263,7 +280,7 @@ function findGeckoDriver() {
     throw Error(
       'The ' + GECKO_DRIVER_EXE + ' executable could not be found on the current ' +
       'PATH. Please download the latest version from ' +
-      'https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/' +
+      'https://github.com/mozilla/geckodriver/releases/' +
       'WebDriver and ensure it can be found on your PATH.');
   }
   return exe;
@@ -339,8 +356,14 @@ class Driver extends webdriver.WebDriver {
 
     let serverUrl, onQuit;
 
-    if (caps.get(Capability.MARIONETTE)
-        || /^1|true$/i.test(process.env['SELENIUM_MARIONETTE'])) {
+    // Users must now explicitly disable marionette to use the legacy
+    // FirefoxDriver.
+    let noMarionette =
+        caps.get(Capability.MARIONETTE) === false
+            || /^0|false$/i.test(process.env['SELENIUM_MARIONETTE']);
+    let useMarionette = !noMarionette;
+
+    if (useMarionette) {
       let service = createGeckoDriverService(binary);
       serverUrl = service.start();
       onQuit = () => service.kill();

javascript/node/selenium-webdriver/lib/test/index.js

@@ -28,6 +28,9 @@ var build = require('./build'),
     fileserver = require('./fileserver');
 
 
+const LEGACY_FIREFOX = 'legacy-' + webdriver.Browser.FIREFOX;
+
+
 /**
  * Browsers with native support.
  * @type {!Array.<webdriver.Browser>}
@@ -36,6 +39,7 @@ var NATIVE_BROWSERS = [
   webdriver.Browser.CHROME,
   webdriver.Browser.EDGE,
   webdriver.Browser.FIREFOX,
+  LEGACY_FIREFOX,
   webdriver.Browser.IE,
   webdriver.Browser.OPERA,
   webdriver.Browser.PHANTOM_JS,
@@ -46,10 +50,10 @@ var NATIVE_BROWSERS = [
 var serverJar = process.env['SELENIUM_SERVER_JAR'];
 var remoteUrl = process.env['SELENIUM_REMOTE_URL'];
 var useLoopback = process.env['SELENIUM_USE_LOOP_BACK'] == '1';
+var noMarionette = /^0|false$/i.test(process.env['SELENIUM_GECKODRIVER']);
 var startServer = !!serverJar && !remoteUrl;
 var nativeRun = !serverJar && !remoteUrl;
 
-
 var browsersToTest = (function() {
   var permitRemoteBrowsers = !!remoteUrl || !!serverJar;
   var permitUnknownBrowsers = !nativeRun;
@@ -63,14 +67,22 @@ var browsersToTest = (function() {
     if (parts[0] === 'edge') {
       parts[0] = webdriver.Browser.EDGE;
     }
+    if (noMarionette && parts[0] === webdriver.Browser.FIREFOX) {
+      parts[0] = LEGACY_FIREFOX;
+    }
     return parts.join(':');
   });
+
   browsers.forEach(function(browser) {
     var parts = browser.split(/:/, 3);
     if (parts[0] === 'ie') {
       parts[0] = webdriver.Browser.IE;
     }
 
+    if (parts[0] === LEGACY_FIREFOX) {
+      return;
+    }
+
     if (NATIVE_BROWSERS.indexOf(parts[0]) == -1 && !permitRemoteBrowsers) {
       throw Error('Browser ' + parts[0] + ' requires a WebDriver server and ' +
           'neither the SELENIUM_REMOTE_URL nor the SELENIUM_SERVER_JAR ' +
@@ -145,6 +157,11 @@ function TestEnvironment(browserName, server) {
 
     builder.build = function() {
       var parts = browserName.split(/:/, 3);
+
+      if (parts[0] === LEGACY_FIREFOX) {
+        parts[0] = webdriver.Browser.FIREFOX;
+      }
+
       builder.forBrowser(parts[0], parts[1], parts[2]);
       if (server) {
         builder.usingServer(server.address());
@@ -199,7 +216,7 @@ function suite(fn, opt_options) {
       testing.describe('[' + browser + ']', function() {
 
         if (isDevMode && nativeRun) {
-          if (browser === webdriver.Browser.FIREFOX) {
+          if (browser === LEGACY_FIREFOX) {
             testing.before(function() {
               return build.of('//javascript/firefox-driver:webdriver')
                   .onlyOnce().go();

javascript/node/selenium-webdriver/test/fingerprint_test.js

@@ -53,5 +53,5 @@ test.suite(function(env) {
     });
   });
 
-// Currently only implemented in firefox.
-}, {browsers: ['firefox']});
+// Currently only implemented in legacy firefox.
+}, {browsers: ['legacy-firefox']});