selenium-webdriver 3.0.1 → 3.5.0

package/firefox/binary.js

@@ -47,27 +47,17 @@ const NO_FOCUS_LIB_AMD64 = isDevMode ?
 const X_IGNORE_NO_FOCUS_LIB = 'x_ignore_nofocus.so';
 
 
-let foundBinary = null;
-let foundDevBinary = null;
-
-
 /**
- * Checks the default Windows Firefox locations in Program Files.
- *
- * @param {boolean=} opt_dev Whether to find the Developer Edition.
+ * @param {string} file Path to the file to find, relative to the program files
+ *     root.
  * @return {!Promise<?string>} A promise for the located executable.
  *     The promise will resolve to {@code null} if Firefox was not found.
  */
-function defaultWindowsLocation(opt_dev) {
-  var files = [
+function findInProgramFiles(file) {
+  let files = [
     process.env['PROGRAMFILES'] || 'C:\\Program Files',
     process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)'
-  ].map(function(prefix) {
-    if (opt_dev) {
-      return path.join(prefix, 'Firefox Developer Edition\\firefox.exe');
-    }
-    return path.join(prefix, 'Mozilla Firefox\\firefox.exe');
-  });
+  ].map(prefix => path.join(prefix, file));
   return io.exists(files[0]).then(function(exists) {
     return exists ? files[0] : io.exists(files[1]).then(function(exists) {
       return exists ? files[1] : null;
@@ -77,49 +67,104 @@ function defaultWindowsLocation(opt_dev) {
 
 
 /**
- * Locates the Firefox binary for the current system.
+ * Provides methods for locating the executable for a Firefox release channel
+ * on Windows and MacOS. For other systems (i.e. Linux), Firefox will always
+ * be located on the system PATH.
  *
- * @param {boolean=} opt_dev Whether to find the Developer Edition. This only
- *     used on Windows and OSX.
- * @return {!Promise<string>} A promise for the located binary. The promise will
- *     be rejected if Firefox cannot be located.
+ * @final
  */
-function findFirefox(opt_dev) {
-  if (opt_dev && foundDevBinary) {
-    return foundDevBinary;
+class Channel {
+  /**
+   * @param {string} darwin The path to check when running on MacOS.
+   * @param {string} win32 The path to check when running on Windows.
+   */
+  constructor(darwin, win32) {
+    /** @private @const */ this.darwin_ = darwin;
+    /** @private @const */ this.win32_ = win32;
+    /** @private {Promise<string>} */
+    this.found_ = null;
   }
 
-  if (!opt_dev && foundBinary) {
-    return foundBinary;
+  /**
+   * Attempts to locate the Firefox executable for this release channel. This
+   * will first check the default installation location for the channel before
+   * checking the user's PATH. The returned promise will be rejected if Firefox
+   * can not be found.
+   *
+   * @return {!Promise<string>} A promise for the location of the located
+   *     Firefox executable.
+   */
+  locate() {
+    if (this.found_) {
+      return this.found_;
+    }
+
+    let found;
+    switch (process.platform) {
+      case 'darwin':
+        found = io.exists(this.darwin_)
+            .then(exists => exists ? this.darwin_ : io.findInPath('firefox'));
+        break;
+
+      case 'win32':
+        found = findInProgramFiles(this.win32_)
+            .then(found => found || io.findInPath('firefox.exe'));
+        break;
+
+      default:
+        found = Promise.resolve(io.findInPath('firefox'));
+        break;
+    }
+
+    this.found_ = found.then(found => {
+      if (found) {
+        // TODO: verify version info.
+        return found;
+      }
+      throw Error('Could not locate Firefox on the current system');
+    });
+    return this.found_;
   }
+}
 
-  let found;
-  if (process.platform === 'darwin') {
-    let exe = opt_dev
-        ? '/Applications/FirefoxDeveloperEdition.app/Contents/MacOS/firefox-bin'
-        : '/Applications/Firefox.app/Contents/MacOS/firefox-bin';
-    found = io.exists(exe).then(exists => exists ? exe : null);
 
-  } else if (process.platform === 'win32') {
-    found = defaultWindowsLocation(opt_dev);
+/**
+ * Firefox's developer channel.
+ * @const
+ * @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#aurora>
+ */
+Channel.AURORA = new Channel(
+  '/Applications/FirefoxDeveloperEdition.app/Contents/MacOS/firefox-bin',
+  'Firefox Developer Edition\\firefox.exe');
 
-  } else {
-    found = Promise.resolve(io.findInPath('firefox'));
-  }
+/**
+ * Firefox's beta channel. Note this is provided mainly for convenience as
+ * the beta channel has the same installation location as the main release
+ * channel.
+ * @const
+ * @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#beta>
+ */
+Channel.BETA = new Channel(
+  '/Applications/Firefox.app/Contents/MacOS/firefox-bin',
+  'Mozilla Firefox\\firefox.exe');
 
-  found = found.then(found => {
-    if (found) {
-      return found;
-    }
-    throw Error('Could not locate Firefox on the current system');
-  });
+/**
+ * Firefox's release channel.
+ * @const
+ * @see <https://www.mozilla.org/en-US/firefox/desktop/>
+ */
+Channel.RELEASE = new Channel(
+  '/Applications/Firefox.app/Contents/MacOS/firefox-bin',
+  'Mozilla Firefox\\firefox.exe');
 
-  if (opt_dev) {
-    return foundDevBinary = found;
-  } else {
-    return foundBinary = found;
-  }
-}
+/**
+ * Firefox's nightly release channel.
+ * @const
+ * @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly>
+ */
+Channel.NIGHTLY = new Channel(
+  '/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin',
+  'Nightly\\firefox.exe');
 
 
 /**
@@ -151,20 +196,23 @@ function installNoFocusLibs(profileDir) {
  * use with WebDriver.
  *
  * If created _without_ a path for the Firefox binary to use, this class will
- * attempt to find Firefox when {@link #launch()} is called. For OSX and
+ * attempt to find Firefox when {@link #launch()} is called. For MacOS and
  * Windows, this class will look for Firefox in the current platform's default
- * installation location (e.g. /Applications/Firefox.app on OSX). For all other
- * platforms, the Firefox executable must be available on your system `PATH`.
+ * installation location (e.g. /Applications/Firefox.app on MacOS). For all
+ * other platforms, the Firefox executable must be available on your system
+ * `PATH`.
  *
  * @final
  */
 class Binary {
   /**
-   * @param {string=} opt_exe Path to the Firefox binary to use.
+   * @param {?(string|Channel)=} opt_exeOrChannel Either the path to a specific
+   *     Firefox binary to use, or a {@link Channel} instance that describes
+   *     how to locate the desired Firefox version.
    */
-  constructor(opt_exe) {
-    /** @private {(string|undefined)} */
-    this.exe_ = opt_exe;
+  constructor(opt_exeOrChannel) {
+    /** @private {?(string|Channel)} */
+    this.exe_ = opt_exeOrChannel || null;
 
     /** @private {!Array.<string>} */
     this.args_ = [];
@@ -187,7 +235,7 @@ class Binary {
    *     on the current system.
    */
   getExe() {
-    return this.exe_;
+    return typeof this.exe_ === 'string' ? this.exe_ : undefined;
   }
 
   /**
@@ -223,6 +271,8 @@ class Binary {
    *
    * @param {boolean=} opt_use Whether to use the developer edition. Defaults to
    *     true.
+   * @deprecated Use the {@link Channel} class to indicate the desired Firefox
+   *     version when creating a new binary: `new Binary(Channel.AURORA)`.
    */
   useDevEdition(opt_use) {
     this.devEdition_ = opt_use === undefined || !!opt_use;
@@ -238,7 +288,13 @@ class Binary {
    *     used by this instance.
    */
   locate() {
-    return Promise.resolve(this.exe_ || findFirefox(this.devEdition_));
+    if (typeof this.exe_ === 'string') {
+      return Promise.resolve(this.exe_);
+    } else if (this.exe_ instanceof Channel) {
+      return this.exe_.locate();
+    }
+    let channel = this.devEdition_ ? Channel.AURORA : Channel.RELEASE;
+    return channel.locate();
   }
 
   /**
@@ -284,4 +340,5 @@ class Binary {
 
 
 exports.Binary = Binary;
+exports.Channel = Channel;
 

package/firefox/extension.js

@@ -19,12 +19,12 @@
 
 'use strict';
 
-const AdmZip = require('adm-zip'),
-    fs = require('fs'),
+const fs = require('fs'),
     path = require('path'),
     xml = require('xml2js');
 
 const io = require('../io');
+const zip = require('../io/zip');
 
 
 /**
@@ -56,11 +56,7 @@ function install(extension, dir) {
       if (!details.unpack) {
         return io.copy(extension, dst + '.xpi').then(() => details.id);
       } else {
-        return Promise.resolve().then(function() {
-          // TODO: find an async library for inflating a zip archive.
-          new AdmZip(extension).extractAllTo(dst, true);
-          return details.id;
-        });
+        return zip.unzip(extension, dst).then(() => details.id);
       }
     } else {
       return io.copyDir(extension, dst).then(() => details.id);
@@ -79,105 +75,146 @@ var AddonDetails;
 var RdfRoot;
 
 
-
 /**
  * Extracts the details needed to install an add-on.
  * @param {string} addonPath Path to the extension directory.
  * @return {!Promise<!AddonDetails>} A promise for the add-on details.
  */
 function getDetails(addonPath) {
-  return readManifest(addonPath).then(function(doc) {
-    var em = getNamespaceId(doc, 'http://www.mozilla.org/2004/em-rdf#');
-    var rdf = getNamespaceId(
-        doc, 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
-
-    var description = doc[rdf + 'RDF'][rdf + 'Description'][0];
-    var details = {
-      id: getNodeText(description, em + 'id'),
-      name: getNodeText(description, em + 'name'),
-      version: getNodeText(description, em + 'version'),
-      unpack: getNodeText(description, em + 'unpack') || false
-    };
-
-    if (typeof details.unpack === 'string') {
-      details.unpack = details.unpack.toLowerCase() === 'true';
+  return io.stat(addonPath).then((stats) => {
+    if (stats.isDirectory()) {
+      return parseDirectory(addonPath);
+    } else if (addonPath.slice(-4) === '.xpi') {
+      return parseXpiFile(addonPath);
+    } else {
+      throw Error('Add-on path is not an xpi or a directory: ' + addonPath);
     }
+  });
 
-    if (!details.id) {
-      throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
-    }
+  /**
+   * Parse an install.rdf for a Firefox add-on.
+   * @param {string} rdf The contents of install.rdf for the add-on.
+   * @return {!Promise<!AddonDetails>} A promise for the add-on details.
+   */
+  function parseInstallRdf(rdf) {
+    return parseXml(rdf).then(function(doc) {
+      var em = getNamespaceId(doc, 'http://www.mozilla.org/2004/em-rdf#');
+      var rdf = getNamespaceId(
+          doc, 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+
+      var description = doc[rdf + 'RDF'][rdf + 'Description'][0];
+      var details = {
+        id: getNodeText(description, em + 'id'),
+        name: getNodeText(description, em + 'name'),
+        version: getNodeText(description, em + 'version'),
+        unpack: getNodeText(description, em + 'unpack') || false
+      };
+
+      if (typeof details.unpack === 'string') {
+        details.unpack = details.unpack.toLowerCase() === 'true';
+      }
 
-    return details;
-  });
+      if (!details.id) {
+        throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
+      }
 
-  function getNodeText(node, name) {
-    return node[name] && node[name][0] || '';
-  }
+      return details;
+    });
 
-  function getNamespaceId(doc, url) {
-    var keys = Object.keys(doc);
-    if (keys.length !== 1) {
-      throw new AddonFormatError('Malformed manifest for add-on ' + addonPath);
+    function parseXml(text) {
+      return new Promise((resolve, reject) => {
+        xml.parseString(text, (err, data) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve(data);
+          }
+        });
+      });
     }
 
-    var namespaces = /** @type {!RdfRoot} */(doc[keys[0]]).$;
-    var id = '';
-    Object.keys(namespaces).some(function(ns) {
-      if (namespaces[ns] !== url) {
-        return false;
-      }
+    function getNodeText(node, name) {
+      return node[name] && node[name][0] || '';
+    }
 
-      if (ns.indexOf(':') != -1) {
-        id = ns.split(':')[1] + ':';
+    function getNamespaceId(doc, url) {
+      var keys = Object.keys(doc);
+      if (keys.length !== 1) {
+        throw new AddonFormatError('Malformed manifest for add-on ' + addonPath);
       }
-      return true;
-    });
-    return id;
-  }
-}
 
+      var namespaces = /** @type {!RdfRoot} */(doc[keys[0]]).$;
+      var id = '';
+      Object.keys(namespaces).some(function(ns) {
+        if (namespaces[ns] !== url) {
+          return false;
+        }
 
-/**
- * Reads the manifest for a Firefox add-on.
- * @param {string} addonPath Path to a Firefox add-on as a xpi or an extension.
- * @return {!Promise<!Object>} A promise for the parsed manifest.
- */
-function readManifest(addonPath) {
-  var manifest;
+        if (ns.indexOf(':') != -1) {
+          id = ns.split(':')[1] + ':';
+        }
+        return true;
+      });
+      return id;
+    }
+  }
+
+  /**
+   * Parse a manifest for a Firefox WebExtension.
+   * @param {{
+   *   name: string,
+   *   version: string,
+   *   applications: {gecko:{id:string}}
+   * }} json JSON representation of the manifest.
+   * @return {!AddonDetails} The add-on details.
+   */
+  function parseManifestJson({name, version, applications}) {
+    if (!(applications && applications.gecko && applications.gecko.id)) {
+      throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
+    }
 
-  if (addonPath.slice(-4) === '.xpi') {
-    manifest = new Promise((resolve, reject) => {
-      let zip = new AdmZip(addonPath);
+    return {id: applications.gecko.id, name, version, unpack: false};
+  }
 
-      if (!zip.getEntry('install.rdf')) {
-        reject(new AddonFormatError(
-            'Could not find install.rdf in ' + addonPath));
-        return;
+  function parseXpiFile(filePath) {
+    return zip.load(filePath).then(archive => {
+      if (archive.has('install.rdf')) {
+        return archive.getFile('install.rdf')
+            .then(buf => parseInstallRdf(buf.toString('utf8')));
       }
 
-      zip.readAsTextAsync('install.rdf', resolve);
-    });
-  } else {
-    manifest = io.stat(addonPath).then(function(stats) {
-      if (!stats.isDirectory()) {
-        throw Error(
-            'Add-on path is niether a xpi nor a directory: ' + addonPath);
+      if (archive.has('manifest.json')) {
+        return archive.getFile('manifest.json')
+            .then(buf => JSON.parse(buf.toString('utf8')))
+            .then(parseManifestJson);
       }
-      return io.read(path.join(addonPath, 'install.rdf'));
+
+      throw new AddonFormatError(
+          `Couldn't find install.rdf or manifest.json in ${filePath}`);
     });
   }
 
-  return manifest.then(function(content) {
-    return new Promise((resolve, reject) => {
-      xml.parseString(content, (err, data) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve(data);
-        }
-      });
-    });
-  });
+  function parseDirectory(dirPath) {
+    const rdfPath = path.join(dirPath, 'install.rdf');
+    const jsonPath = path.join(dirPath, 'manifest.json');
+    return io.exists(rdfPath)
+        .then(rdfExists => {
+          if (rdfExists) {
+            return io.read(rdfPath)
+                .then(buf => parseInstallRdf(buf.toString('utf8')));
+          }
+          return io.exists(jsonPath)
+              .then(jsonExists => {
+                if (jsonExists) {
+                  return io.read(jsonPath)
+                      .then(buf => JSON.parse(buf.toString('utf8')))
+                      .then(parseManifestJson);
+                }
+                throw new AddonFormatError(
+                    `Couldn't find install.rdf or manifest.json in ${dirPath}`);
+              });
+        })
+  }
 }