selenium-webdriver 3.0.1 → 3.5.0

package/firefox/index.js

@@ -26,28 +26,31 @@
  *
  * __Customizing the Firefox Profile__
  *
- * The {@link Profile} class may be used to configure the browser profile used
- * with WebDriver, with functions to install additional
+ * The {@linkplain Profile} class may be used to configure the browser profile
+ * used with WebDriver, with functions to install additional
  * {@linkplain Profile#addExtension extensions}, configure browser
  * {@linkplain Profile#setPreference preferences}, and more. For example, you
  * may wish to include Firebug:
  *
- *     var firefox = require('selenium-webdriver/firefox');
+ *     const {Builder} = require('selenium-webdriver');
+ *     const firefox = require('selenium-webdriver/firefox');
  *
- *     var profile = new firefox.Profile();
+ *     let profile = new firefox.Profile();
  *     profile.addExtension('/path/to/firebug.xpi');
  *     profile.setPreference('extensions.firebug.showChromeErrors', true);
  *
- *     var options = new firefox.Options().setProfile(profile);
- *     var driver = new firefox.Driver(options);
+ *     let options = new firefox.Options().setProfile(profile);
+ *     let driver = new Builder()
+ *         .forBrowser('firefox')
+ *         .setFirefoxOptions(options)
+ *         .build();
  *
- * The {@link Profile} class may also be used to configure WebDriver based on a
- * pre-existing browser profile:
+ * The {@linkplain Profile} class may also be used to configure WebDriver based
+ * on a pre-existing browser profile:
  *
- *     var profile = new firefox.Profile(
+ *     let profile = new firefox.Profile(
  *         '/usr/local/home/bob/.mozilla/firefox/3fgog75h.testing');
- *     var options = new firefox.Options().setProfile(profile);
- *     var driver = new firefox.Driver(options);
+ *     let options = new firefox.Options().setProfile(profile);
  *
  * The FirefoxDriver will _never_ modify a pre-existing profile; instead it will
  * create a copy for it to modify. By extension, there are certain browser
@@ -56,21 +59,35 @@
  *
  * __Using a Custom Firefox Binary__
  *
- * On Windows and OSX, the FirefoxDriver will search for Firefox in its
+ * On Windows and MacOS, the FirefoxDriver will search for Firefox in its
  * default installation location:
  *
- * * Windows: C:\Program Files and C:\Program Files (x86).
- * * Mac OS X: /Applications/Firefox.app
+ * - Windows: C:\Program Files and C:\Program Files (x86).
+ * - MacOS: /Applications/Firefox.app
  *
- * For Linux, Firefox will be located on the PATH: `$(where firefox)`.
+ * For Linux, Firefox will always be located on the PATH: `$(where firefox)`.
  *
- * You can configure WebDriver to start use a custom Firefox installation with
- * the {@link Binary} class:
+ * Several methods are provided for starting Firefox with a custom executable.
+ * First, on Windows and MacOS, you may configure WebDriver to check the default
+ * install location for a non-release channel. If the requested channel cannot
+ * be found in its default location, WebDriver will fallback to searching your
+ * PATH. _Note:_ on Linux, Firefox is _always_ located on your path, regardless
+ * of the requested channel.
  *
- *     var firefox = require('selenium-webdriver/firefox');
- *     var binary = new firefox.Binary('/my/firefox/install/dir/firefox-bin');
- *     var options = new firefox.Options().setBinary(binary);
- *     var driver = new firefox.Driver(options);
+ *     const {Builder} = require('selenium-webdriver');
+ *     const firefox = require('selenium-webdriver/firefox');
+ *
+ *     let options = new firefox.Options().setBinary(firefox.Channel.NIGHTLY);
+ *     let driver = new Builder()
+ *         .forBrowser('firefox')
+ *         .setFirefoxOptions(options)
+ *         .build();
+ *
+ * On all platforms, you may configrue WebDriver to use a Firefox specific
+ * executable:
+ *
+ *     let options = new firefox.Options()
+ *         .setBinary('/my/firefox/install/dir/firefox-bin');
  *
  * __Remote Testing__
  *
@@ -84,27 +101,19 @@
  * binaries are never copied to remote machines and must be referenced by
  * installation path.
  *
- *     var options = new firefox.Options()
+ *     const {Builder} = require('selenium-webdriver');
+ *     const firefox = require('selenium-webdriver/firefox');
+ *
+ *     let options = new firefox.Options()
  *         .setProfile('/profile/path/on/remote/host')
  *         .setBinary('/install/dir/on/remote/host/firefox-bin');
  *
- *     var driver = new (require('selenium-webdriver')).Builder()
+ *     let driver = new Builder()
  *         .forBrowser('firefox')
  *         .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
  */
@@ -113,7 +122,7 @@
 
 const url = require('url');
 
-const Binary = require('./binary').Binary,
+const {Binary, Channel} = require('./binary'),
     Profile = require('./profile').Profile,
     decodeProfile = require('./profile').decode,
     http = require('../http'),
@@ -144,8 +153,8 @@ const Capability = {
   BINARY: 'firefox_binary',
 
   /**
-   * Specifies whether to use Mozilla's Marionette, or the legacy FirefoxDriver
-   * from the Selenium project. Defaults to false.
+   * @deprecated This will be removed in a future release. There is no
+   *     replacement.
    */
   MARIONETTE: 'marionette',
 
@@ -174,9 +183,6 @@ class Options {
 
     /** @private {?capabilities.ProxyConfig} */
     this.proxy_ = null;
-
-    /** @private {boolean} */
-    this.marionette_ = true;
   }
 
   /**
@@ -196,16 +202,24 @@ class Options {
   }
 
   /**
-   * Sets the binary to use. The binary may be specified as the path to a Firefox
-   * executable, or as a {@link Binary} object.
+   * Sets the binary to use. The binary may be specified as the path to a
+   * Firefox executable, a specific {@link Channel}, or as a {@link Binary}
+   * object.
    *
-   * @param {(string|!Binary)} binary The binary to use.
+   * @param {(string|!Binary|!Channel)} binary The binary to use.
    * @return {!Options} A self reference.
+   * @throws {TypeError} If `binary` is an invalid type.
    */
   setBinary(binary) {
-    if (typeof binary === 'string') {
+    if (typeof binary === 'string' || binary instanceof Channel) {
       binary = new Binary(binary);
     }
+
+    if (!(binary instanceof Binary)) {
+      throw TypeError(
+          'binary must be a string path, Channel, or Binary object');
+    }
+
     this.binary_ = binary;
     return this;
   }
@@ -232,14 +246,10 @@ class Options {
   }
 
   /**
-   * Sets whether to use Mozilla's geckodriver to drive the browser. This option
-   * is enabled by default and required for Firefox 47+.
-   *
-   * @param {boolean} enable Whether to enable the geckodriver.
-   * @see https://github.com/mozilla/geckodriver
+   * @deprecated This method has been deprecated and will be removed in the next
+   *     release. It is a no-op.
    */
   useGeckoDriver(enable) {
-    this.marionette_ = enable;
     return this;
   }
 
@@ -262,7 +272,6 @@ class Options {
     if (this.profile_) {
       caps.set(Capability.PROFILE, this.profile_);
     }
-    caps.set(Capability.MARIONETTE, this.marionette_);
     return caps;
   }
 }
@@ -298,33 +307,13 @@ function findGeckoDriver() {
     throw Error(
       'The ' + GECKO_DRIVER_EXE + ' executable could not be found on the current ' +
       'PATH. Please download the latest version from ' +
-      'https://github.com/mozilla/geckodriver/releases/' +
-      'WebDriver and ensure it can be found on your PATH.');
+      'https://github.com/mozilla/geckodriver/releases/ ' +
+      'and ensure it can be found on your PATH.');
   }
   return exe;
 }
 
 
-/**
- * @param {(Profile|string)} profile The profile to prepare.
- * @param {number} port The port the FirefoxDriver should listen on.
- * @return {!Promise<string>} a promise for the path to the profile directory.
- */
-function prepareProfile(profile, port) {
-  if (typeof profile === 'string') {
-    return decodeProfile(/** @type {string} */(profile)).then(dir => {
-      profile = new Profile(dir);
-      profile.setPreference('webdriver_firefox_port', port);
-      return profile.writeToDisk();
-    });
-  }
-
-  profile = profile || new Profile;
-  profile.setPreference('webdriver_firefox_port', port);
-  return profile.writeToDisk();
-}
-
-
 function normalizeProxyConfiguration(config) {
   if ('manual' === config.proxyType) {
     if (config.ftpProxy && !config.ftpProxyPort) {
@@ -457,7 +446,7 @@ var DriverSpec;
  * @return {DriverSpec}
  */
 function createGeckoDriver(executor, caps, profile, binary) {
-  let firefoxOptions = {};
+  let firefoxOptions = caps.get('moz:firefoxOptions') || {};
   caps.set('moz:firefoxOptions', firefoxOptions);
 
   if (binary) {
@@ -529,47 +518,6 @@ function createGeckoDriver(executor, caps, profile, binary) {
 }
 
 
-/**
- * @param {!capabilities.Capabilities} caps
- * @param {Profile} profile
- * @param {!Binary} binary
- * @return {DriverSpec}
- */
-function createLegacyDriver(caps, profile, binary, flow) {
-  profile = profile || new Profile;
-
-  let freePort = portprober.findFreePort();
-  let preparedProfile =
-      freePort.then(port => prepareProfile(profile, port));
-  let command = preparedProfile.then(dir => binary.launch(dir));
-
-  let serverUrl = command.then(() => freePort)
-      .then(function(/** number */port) {
-        let serverUrl = url.format({
-          protocol: 'http',
-          hostname: net.getLoopbackAddress(),
-          port: port + '',
-          pathname: '/hub'
-        });
-        let ready = httpUtil.waitForServer(serverUrl, 45 * 1000);
-        return ready.then(() => serverUrl);
-      });
-
-  return {
-    executor: createExecutor(serverUrl),
-    capabilities: caps,
-    onQuit: function() {
-      return command.then(command => {
-        command.kill();
-        return preparedProfile.then(io.rmDir)
-            .then(() => command.result(),
-                  () => command.result());
-      });
-    }
-  };
-}
-
-
 /**
  * A WebDriver client for Firefox.
  */
@@ -619,26 +567,9 @@ class Driver extends webdriver.WebDriver {
       caps.delete(Capability.PROFILE);
     }
 
-    // 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;
-
-    let spec;
-    if (useMarionette) {
-      spec = createGeckoDriver(opt_executor, caps, profile, binary);
-    } else {
-      if (opt_executor) {
-        throw Error('You may not use a custom command executor with the legacy'
-            + ' FirefoxDriver');
-      }
-      spec = createLegacyDriver(caps, profile, binary, opt_flow);
-    }
-
-    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
-        spec.executor, spec.capabilities, opt_flow, this, spec.onQuit));
+    let spec = createGeckoDriver(opt_executor, caps, profile, binary);
+    return /** @type {!Driver} */(super.createSession(
+        spec.executor, spec.capabilities, opt_flow, spec.onQuit));
   }
 
   /**
@@ -687,6 +618,7 @@ class Driver extends webdriver.WebDriver {
 
 
 exports.Binary = Binary;
+exports.Channel = Channel;
 exports.Context = Context;
 exports.Driver = Driver;
 exports.Options = Options;

package/firefox/profile.js

@@ -22,14 +22,14 @@
 
 'use strict';
 
-const AdmZip = require('adm-zip'),
-    fs = require('fs'),
+const fs = require('fs'),
     path = require('path'),
     vm = require('vm');
 
 const isDevMode = require('../lib/devmode'),
     Symbols = require('../lib/symbols'),
     io = require('../io'),
+    {Zip, unzip} = require('../io/zip'),
     extension = require('./extension');
 
 
@@ -38,17 +38,6 @@ const WEBDRIVER_PREFERENCES_PATH = isDevMode
     ? path.join(__dirname, '../../../firefox-driver/webdriver.json')
     : path.join(__dirname, '../lib/firefox/webdriver.json');
 
-/** @const */
-const WEBDRIVER_EXTENSION_PATH = isDevMode
-    ? path.join(__dirname,
-        '../../../../build/javascript/firefox-driver/webdriver.xpi')
-    : path.join(__dirname, '../lib/firefox/webdriver.xpi');
-
-/** @const */
-const WEBDRIVER_EXTENSION_NAME = 'fxdriver@googlecode.com';
-
-
-
 /** @type {Object} */
 var defaultPreferences = null;
 
@@ -130,13 +119,10 @@ function writeUserPrefs(prefs, dir) {
  * @param {!Array.<string>} extensions The extensions to install, as a
  *     path to an unpacked extension directory or a path to a xpi file.
  * @param {string} dir The profile directory to install to.
- * @param {boolean=} opt_excludeWebDriverExt Whether to skip installation of
- *     the default WebDriver extension.
  * @return {!Promise<string>} A promise for the main profile directory
  *     once all extensions have been installed.
  */
-function installExtensions(extensions, dir, opt_excludeWebDriverExt) {
-  var hasWebDriver = !!opt_excludeWebDriverExt;
+function installExtensions(extensions, dir) {
   var next = 0;
   var extensionDir = path.join(dir, 'extensions');
 
@@ -145,11 +131,7 @@ function installExtensions(extensions, dir, opt_excludeWebDriverExt) {
 
     function installNext() {
       if (next >= extensions.length) {
-        if (hasWebDriver) {
-          fulfill(dir);
-        } else {
-          install(WEBDRIVER_EXTENSION_PATH);
-        }
+        fulfill(dir);
       } else {
         install(extensions[next++]);
       }
@@ -157,7 +139,6 @@ function installExtensions(extensions, dir, opt_excludeWebDriverExt) {
 
     function install(ext) {
       extension.install(ext, extensionDir).then(function(id) {
-        hasWebDriver = hasWebDriver || (id === WEBDRIVER_EXTENSION_NAME);
         installNext();
       }, reject);
     }
@@ -173,14 +154,10 @@ function installExtensions(extensions, dir, opt_excludeWebDriverExt) {
  */
 function decode(data) {
   return io.tmpFile().then(function(file) {
-    var buf = new Buffer(data, 'base64');
+    let buf = new Buffer(data, 'base64');
     return io.write(file, buf)
         .then(io.tmpDir)
-        .then(function(dir) {
-          var zip = new AdmZip(file);
-          zip.extractAllTo(dir);  // Sync only? Why?? :-(
-          return dir;
-        });
+        .then(dir => unzip(file, dir));
   });
 }
 
@@ -353,14 +330,10 @@ class Profile {
 
   /**
    * Writes this profile to disk.
-   * @param {boolean=} opt_excludeWebDriverExt Whether to exclude the WebDriver
-   *     extension from the generated profile. Used to reduce the size of an
-   *     {@link #encode() encoded profile} since the server will always install
-   *     the extension itself.
    * @return {!Promise<string>} A promise for the path to the new profile
    *     directory.
    */
-  writeToDisk(opt_excludeWebDriverExt) {
+  writeToDisk() {
     var profileDir = io.tmpDir();
     if (this.template_) {
       profileDir = profileDir.then(function(dir) {
@@ -382,7 +355,7 @@ class Profile {
     return profileDir.then(function(dir) {
       return writeUserPrefs(prefs, dir);
     }).then(function(dir) {
-      return installExtensions(extensions, dir, !!opt_excludeWebDriverExt);
+      return installExtensions(extensions, dir);
     });
   }
 
@@ -395,20 +368,11 @@ class Profile {
    *
    */
   encode() {
-    return this.writeToDisk(true).then(function(dir) {
-      var zip = new AdmZip();
-      zip.addLocalFolder(dir, '');
-      // Stored compression, see https://en.wikipedia.org/wiki/Zip_(file_format)
-      zip.getEntries().forEach(function(entry) {
-        entry.header.method = 0;
-      });
-
-      return io.tmpFile().then(function(file) {
-        zip.writeZip(file);  // Sync! Why oh why :-(
-        return io.read(file);
-      });
-    }).then(function(data) {
-      return data.toString('base64');
+    return this.writeToDisk().then(function(dir) {
+      let zip = new Zip;
+      return zip.addDir(dir)
+          .then(() => zip.toBuffer())
+          .then(buf => buf.toString('base64'));
     });
   }
 

package/ie.js

@@ -420,8 +420,8 @@ class Driver extends webdriver.WebDriver {
     var client = service.start().then(url => new http.HttpClient(url));
     var executor = new http.Executor(client);
 
-    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
-        executor, caps, opt_flow, this, () => service.kill()));
+    return /** @type {!Driver} */(super.createSession(
+        executor, caps, opt_flow, () => service.kill()));
   }
 
   /**

package/index.js

@@ -58,7 +58,7 @@ var seleniumServer;
  * Starts an instance of the Selenium server if not yet running.
  * @param {string} jar Path to the server jar to use.
  * @return {!Promise<string>} A promise for the server's
- *     addrss once started.
+ *     address once started.
  */
 function startSeleniumServer(jar) {
   if (!seleniumServer) {
@@ -131,7 +131,10 @@ const THENABLE_DRIVERS = new Map;
 function createDriver(ctor, ...args) {
   let thenableWebDriverProxy = THENABLE_DRIVERS.get(ctor);
   if (!thenableWebDriverProxy) {
-    /** @implements {ThenableWebDriver} */
+    /**
+     * @extends {WebDriver}  // Needed since `ctor` is dynamically typed.
+     * @implements {ThenableWebDriver}
+     */
     thenableWebDriverProxy = class extends ctor {
       /**
        * @param {!IThenable<!Session>} session
@@ -160,7 +163,7 @@ function createDriver(ctor, ...args) {
         /** @override */
         this.catch = pd.then.bind(pd);
       }
-    }
+    };
     promise.CancellableThenable.addImplementation(thenableWebDriverProxy);
     THENABLE_DRIVERS.set(ctor, thenableWebDriverProxy);
   }

package/io/index.js

@@ -298,3 +298,62 @@ exports.mkdir = function(aPath) {
     });
   });
 };
+
+
+/**
+ * Recursively creates a directory and any ancestors that do not yet exist.
+ *
+ * @param {string} dir The directory path to create.
+ * @return {!Promise<string>} A promise that will resolve with the path of the
+ *     created directory.
+ */
+exports.mkdirp = function mkdirp(dir) {
+  return checkedCall(callback => {
+    fs.mkdir(dir, undefined, err => {
+      if (!err) {
+        callback(null, dir);
+        return;
+      }
+
+      switch (err.code) {
+        case 'EEXIST':
+          callback(null, dir);
+          return;
+        case 'ENOENT':
+          return mkdirp(path.dirname(dir))
+              .then(() => mkdirp(dir))
+              .then(() => callback(null, dir), err => callback(err));
+        default:
+          callback(err);
+          return;
+      }
+    });
+  });
+};
+
+
+/**
+ * Recursively walks a directory, returning a promise that will resolve with
+ * a list of all files/directories seen.
+ *
+ * @param {string} rootPath the directory to walk.
+ * @return {!Promise<!Array<{path: string, dir: boolean}>>} a promise that will
+ *     resolve with a list of entries seen. For each entry, the recorded path
+ *     will be relative to `rootPath`.
+ */
+exports.walkDir = function(rootPath) {
+  let seen = [];
+  return (function walk(dir) {
+    return checkedCall(callback => fs.readdir(dir, callback))
+        .then(files => Promise.all(files.map(file => {
+          file = path.join(dir, file);
+          return checkedCall(cb => fs.stat(file, cb)).then(stats => {
+            seen.push({
+              path: path.relative(rootPath, file),
+              dir: stats.isDirectory()
+            });
+            return stats.isDirectory() && walk(file);
+          });
+        })));
+  })(rootPath).then(() => seen);
+};