selenium-webdriver 3.4.0 → 3.5.0

package/firefox/index.js

@@ -114,16 +114,6 @@
  *         .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.
- *
- *     let options = new firefox.Options().useGeckoDriver(false);
- *
- * 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
  */
@@ -163,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',
 
@@ -193,9 +183,6 @@ class Options {
 
     /** @private {?capabilities.ProxyConfig} */
     this.proxy_ = null;
-
-    /** @private {boolean} */
-    this.marionette_ = true;
   }
 
   /**
@@ -259,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;
   }
 
@@ -289,7 +272,6 @@ class Options {
     if (this.profile_) {
       caps.set(Capability.PROFILE, this.profile_);
     }
-    caps.set(Capability.MARIONETTE, this.marionette_);
     return caps;
   }
 }
@@ -325,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) {
@@ -484,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) {
@@ -556,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.
  */
@@ -646,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));
   }
 
   /**

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

@@ -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

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);
+};

package/io/zip.js

@@ -0,0 +1,214 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+'use strict';
+
+const jszip = require('jszip');
+const path = require('path');
+
+const io = require('./index');
+const {InvalidArgumentError} = require('../lib/error');
+
+/**
+ * Manages a zip archive.
+ */
+class Zip {
+  constructor() {
+    /** @private @const */
+    this.z_ = new jszip;
+
+    /** @private @const {!Set<!Promise<?>>} */
+    this.pendingAdds_ = new Set;
+  }
+
+  /**
+   * Adds a file to this zip.
+   *
+   * @param {string} filePath path to the file to add.
+   * @param {string=} zipPath path to the file in the zip archive, defaults
+   *     to the basename of `filePath`.
+   * @return {!Promise<?>} a promise that will resolve when added.
+   */
+  addFile(filePath, zipPath = path.basename(filePath)) {
+    let add = io.read(filePath)
+        .then(buffer => this.z_.file(/** @type {string} */(zipPath), buffer));
+    this.pendingAdds_.add(add);
+    return add.then(
+        () => this.pendingAdds_.delete(add),
+        (e) => {
+          this.pendingAdds_.delete(add);
+          throw e;
+        });
+  }
+
+  /**
+   * Recursively adds a directory and all of its contents to this archive.
+   *
+   * @param {string} dirPath path to the directory to add.
+   * @param {string=} zipPath path to the folder in the archive to add the
+   *     directory contents to. Defaults to the root folder.
+   * @return {!Promise<?>} returns a promise that will resolve when the
+   *     the operation is complete.
+   */
+  addDir(dirPath, zipPath = '') {
+    return io.walkDir(dirPath).then(entries => {
+      let archive = this.z_;
+      if (zipPath) {
+        archive = archive.folder(zipPath);
+      }
+
+      let files = [];
+      entries.forEach(spec => {
+        if (spec.dir) {
+          archive.folder(spec.path);
+        } else {
+          files.push(
+              this.addFile(
+                  path.join(dirPath, spec.path),
+                  path.join(zipPath, spec.path)));
+        }
+      });
+
+      return Promise.all(files);
+    });
+  }
+
+  /**
+   * @param {string} path File path to test for within the archive.
+   * @return {boolean} Whether this zip archive contains an entry with the given
+   *     path.
+   */
+  has(path) {
+    return this.z_.file(path) !== null;
+  }
+
+  /**
+   * Returns the contents of the file in this zip archive with the given `path`.
+   * The returned promise will be rejected with an {@link InvalidArgumentError}
+   * if either `path` does not exist within the archive, or if `path` refers
+   * to a directory.
+   *
+   * @param {string} path the path to the file whose contents to return.
+   * @return {!Promise<!Buffer>} a promise that will be resolved with the file's
+   *     contents as a buffer.
+   */
+  getFile(path) {
+    let file = this.z_.file(path);
+    if (!file) {
+      return Promise.reject(
+          new InvalidArgumentError(`No such file in zip archive: ${path}`));
+    }
+
+    if (file.dir) {
+      return Promise.reject(
+          new InvalidArgumentError(
+              `The requested file is a directory: ${path}`));
+    }
+
+    return Promise.resolve(file.async('nodebuffer'));
+  }
+
+  /**
+   * Returns the compressed data for this archive in a buffer. _This method will
+   * not wait for any outstanding {@link #addFile add}
+   * {@link #addDir operations} before encoding the archive._
+   *
+   * @param {string} compression The desired compression.
+   *     Must be `STORE` (the default) or `DEFLATE`.
+   * @return {!Promise<!Buffer>} a promise that will resolve with this archive
+   *     as a buffer.
+   */
+  toBuffer(compression = 'STORE') {
+    if (compression !== 'STORE' && compression !== 'DEFLATE') {
+      return Promise.reject(
+          new InvalidArgumentError(
+              `compression must be one of {STORE, DEFLATE}, got ${compression}`));
+    }
+    return Promise.resolve(
+        this.z_.generateAsync({compression, type: 'nodebuffer'}));
+  }
+}
+
+
+/**
+ * Asynchronously opens a zip archive.
+ *
+ * @param {string} path to the zip archive to load.
+ * @return {!Promise<!Zip>} a promise that will resolve with the opened
+ *     archive.
+ */
+function load(path) {
+  return io.read(path).then(data => {
+    let zip = new Zip;
+    return zip.z_.loadAsync(data).then(() => zip);
+  });
+}
+
+
+/**
+ * Asynchronously unzips an archive file.
+ *
+ * @param {string} src path to the source file to unzip.
+ * @param {string} dst path to the destination directory.
+ * @return {!Promise<string>} a promise that will resolve with `dst` once the
+ *     archive has been unzipped.
+ */
+function unzip(src, dst) {
+  return load(src).then(zip => {
+    let promisedDirs = new Map;
+    let promises = [];
+
+    zip.z_.forEach((relPath, file) => {
+      let p;
+      if (file.dir) {
+        p = createDir(relPath);
+      } else {
+        let dirname = path.dirname(relPath);
+        if (dirname === '.') {
+          p = writeFile(relPath, file);
+        } else {
+          p = createDir(dirname).then(() => writeFile(relPath, file));
+        }
+      }
+      promises.push(p);
+    });
+
+    return Promise.all(promises).then(() => dst);
+
+    function createDir(dir) {
+      let p = promisedDirs.get(dir);
+      if (!p) {
+        p = io.mkdirp(path.join(dst, dir));
+        promisedDirs.set(dir, p);
+      }
+      return p;
+    }
+
+    function writeFile(relPath, file) {
+      return file.async('nodebuffer')
+          .then(buffer => io.write(path.join(dst, relPath), buffer));
+    }
+  });
+}
+
+
+// PUBLIC API
+
+
+exports.Zip = Zip;
+exports.load = load;
+exports.unzip = unzip;