selenium-webdriver 2.48.2 → 2.53.3

package/firefox/index.js

@@ -94,221 +94,314 @@
 
 'use strict';
 
-var url = require('url'),
-    util = require('util');
+const url = require('url');
 
-var Binary = require('./binary').Binary,
+const Binary = require('./binary').Binary,
     Profile = require('./profile').Profile,
     decodeProfile = require('./profile').decode,
-    webdriver = require('..'),
     executors = require('../executors'),
     httpUtil = require('../http/util'),
     io = require('../io'),
+    capabilities = require('../lib/capabilities'),
+    logging = require('../lib/logging'),
+    promise = require('../lib/promise'),
+    webdriver = require('../lib/webdriver'),
     net = require('../net'),
-    portprober = require('../net/portprober');
+    portprober = require('../net/portprober'),
+    remote = require('../remote');
+
+
+/**
+ * Firefox-specific capability keys. Users should use the {@linkplain Options}
+ * class instead of referencing these keys directly. _These keys are considered
+ * implementation details and may be removed or changed at any time._
+ *
+ * @enum {string}
+ */
+const Capability = {
+  /**
+   * Defines the Firefox binary to use. May be set to either a
+   * {@linkplain Binary} instance, or a string path to the Firefox executable.
+   */
+  BINARY: 'firefox_binary',
+
+  /**
+   * Specifies whether to use Mozilla's Marionette, or the legacy FirefoxDriver
+   * from the Selenium project. Defaults to false.
+   */
+  MARIONETTE: 'marionette',
+
+  /**
+   * Defines the Firefox profile to use. May be set to either a
+   * {@linkplain Profile} instance, or to a base-64 encoded zip of a profile
+   * directory.
+   */
+  PROFILE: 'firefox_profile'
+};
 
 
 /**
  * Configuration options for the FirefoxDriver.
- * @constructor
  */
-var Options = function() {
-  /** @private {Profile} */
-  this.profile_ = null;
+class Options {
+  constructor() {
+    /** @private {Profile} */
+    this.profile_ = null;
 
-  /** @private {Binary} */
-  this.binary_ = null;
+    /** @private {Binary} */
+    this.binary_ = null;
 
-  /** @private {webdriver.logging.Preferences} */
-  this.logPrefs_ = null;
+    /** @private {logging.Preferences} */
+    this.logPrefs_ = null;
 
-  /** @private {webdriver.ProxyConfig} */
-  this.proxy_ = null;
-};
+    /** @private {?capabilities.ProxyConfig} */
+    this.proxy_ = null;
 
+    /** @private {boolean} */
+    this.marionette_ = false;
+  }
 
-/**
- * Sets the profile to use. The profile may be specified as a
- * {@link Profile} object or as the path to an existing Firefox profile to use
- * as a template.
- *
- * @param {(string|!Profile)} profile The profile to use.
- * @return {!Options} A self reference.
- */
-Options.prototype.setProfile = function(profile) {
-  if (typeof profile === 'string') {
-    profile = new Profile(profile);
+  /**
+   * Sets the profile to use. The profile may be specified as a
+   * {@link Profile} object or as the path to an existing Firefox profile to use
+   * as a template.
+   *
+   * @param {(string|!Profile)} profile The profile to use.
+   * @return {!Options} A self reference.
+   */
+  setProfile(profile) {
+    if (typeof profile === 'string') {
+      profile = new Profile(profile);
+    }
+    this.profile_ = profile;
+    return this;
   }
-  this.profile_ = profile;
-  return this;
-};
 
+  /**
+   * Sets the binary to use. The binary may be specified as the path to a Firefox
+   * executable, or as a {@link Binary} object.
+   *
+   * @param {(string|!Binary)} binary The binary to use.
+   * @return {!Options} A self reference.
+   */
+  setBinary(binary) {
+    if (typeof binary === 'string') {
+      binary = new Binary(binary);
+    }
+    this.binary_ = binary;
+    return this;
+  }
 
-/**
- * Sets the binary to use. The binary may be specified as the path to a Firefox
- * executable, or as a {@link Binary} object.
- *
- * @param {(string|!Binary)} binary The binary to use.
- * @return {!Options} A self reference.
- */
-Options.prototype.setBinary = function(binary) {
-  if (typeof binary === 'string') {
-    binary = new Binary(binary);
+  /**
+   * Sets the logging preferences for the new session.
+   * @param {logging.Preferences} prefs The logging preferences.
+   * @return {!Options} A self reference.
+   */
+  setLoggingPreferences(prefs) {
+    this.logPrefs_ = prefs;
+    return this;
   }
-  this.binary_ = binary;
-  return this;
-};
 
+  /**
+   * Sets the proxy to use.
+   *
+   * @param {capabilities.ProxyConfig} proxy The proxy configuration to use.
+   * @return {!Options} A self reference.
+   */
+  setProxy(proxy) {
+    this.proxy_ = proxy;
+    return this;
+  }
 
-/**
- * Sets the logging preferences for the new session.
- * @param {webdriver.logging.Preferences} prefs The logging preferences.
- * @return {!Options} A self reference.
- */
-Options.prototype.setLoggingPreferences = function(prefs) {
-  this.logPrefs_ = prefs;
-  return this;
-};
+  /**
+   * Sets whether to use Mozilla's Marionette to drive the browser.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver
+   */
+  useMarionette(marionette) {
+    this.marionette_ = marionette;
+    return this;
+  }
+
+  /**
+   * Converts these options to a {@link capabilities.Capabilities} instance.
+   *
+   * @return {!capabilities.Capabilities} A new capabilities object.
+   */
+  toCapabilities() {
+    var caps = capabilities.Capabilities.firefox();
+    if (this.logPrefs_) {
+      caps.set(capabilities.Capability.LOGGING_PREFS, this.logPrefs_);
+    }
+    if (this.proxy_) {
+      caps.set(capabilities.Capability.PROXY, this.proxy_);
+    }
+    if (this.binary_) {
+      caps.set(Capability.BINARY, this.binary_);
+    }
+    if (this.profile_) {
+      caps.set(Capability.PROFILE, this.profile_);
+    }
+    caps.set(Capability.MARIONETTE, this.marionette_);
+    return caps;
+  }
+}
 
 
-/**
- * Sets the proxy to use.
- *
- * @param {webdriver.ProxyConfig} proxy The proxy configuration to use.
- * @return {!Options} A self reference.
- */
-Options.prototype.setProxy = function(proxy) {
-  this.proxy_ = proxy;
-  return this;
-};
+const WIRES_EXE = process.platform === 'win32' ? 'wires.exe' : 'wires';
 
 
 /**
- * Converts these options to a {@link webdriver.Capabilities} instance.
- *
- * @return {!webdriver.Capabilities} A new capabilities object.
+ * @return {string} .
+ * @throws {Error}
  */
-Options.prototype.toCapabilities = function(opt_remote) {
-  var caps = webdriver.Capabilities.firefox();
-  if (this.logPrefs_) {
-    caps.set(webdriver.Capability.LOGGING_PREFS, this.logPrefs_);
-  }
-  if (this.proxy_) {
-    caps.set(webdriver.Capability.PROXY, this.proxy_);
-  }
-  if (this.binary_) {
-    caps.set('firefox_binary', this.binary_);
+function findWires() {
+  let exe = io.findInPath(WIRES_EXE, true);
+  if (!exe) {
+    throw Error(
+      'The ' + WIRES_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/' +
+      'WebDriver and ensure it can be found on your PATH.');
   }
-  if (this.profile_) {
-    caps.set('firefox_profile', this.profile_);
-  }
-  return caps;
-};
+  return exe;
+}
 
 
 /**
- * A WebDriver client for Firefox.
- *
- * @param {(Options|webdriver.Capabilities|Object)=} opt_config The
- *    configuration options for this driver, specified as either an
- *    {@link Options} or {@link webdriver.Capabilities}, or as a raw hash
- *    object.
- * @param {webdriver.promise.ControlFlow=} opt_flow The flow to
- *     schedule commands through. Defaults to the active flow object.
- * @constructor
- * @extends {webdriver.WebDriver}
+ * @param {(string|!Binary)} binary .
+ * @return {!remote.DriverService} .
  */
-var Driver = function(opt_config, opt_flow) {
-  var caps;
-  if (opt_config instanceof Options) {
-    caps = opt_config.toCapabilities();
+function createWiresService(binary) {
+    // Firefox's Developer Edition is currently required for Marionette.
+  let exe;
+  if (typeof binary === 'string') {
+    exe = Promise.resolve(binary);
   } else {
-    caps = new webdriver.Capabilities(opt_config);
+    binary.useDevEdition();
+    exe = binary.locate();
   }
 
-  var binary = caps.get('firefox_binary') || new Binary();
-  if (typeof binary === 'string') {
-    binary = new Binary(binary);
-  }
+  let wires = findWires();
+  let port =  portprober.findFreePort();
+  return new remote.DriverService(wires, {
+    loopback: true,
+    port: port,
+    args: promise.all([exe, port]).then(args => {
+      return ['-b', args[0], '--webdriver-port', args[1]];
+    })
+    // ,stdio: 'inherit'
+  });
+}
 
-  var profile = caps.get('firefox_profile') || new Profile();
 
-  caps.set('firefox_binary', null);
-  caps.set('firefox_profile', null);
+/**
+ * @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();
+    });
+  }
 
-  /** @private {?string} */
-  this.profilePath_ = null;
+  profile = profile || new Profile;
+  profile.setPreference('webdriver_firefox_port', port);
+  return profile.writeToDisk();
+}
 
-  var self = this;
-  var freePort = portprober.findFreePort();
 
-  /** @private */
-  this.command_ = freePort.then(function(port) {
-    if (typeof profile === 'string') {
-      return decodeProfile(profile).then(function(dir) {
-        var profile = new Profile(dir);
-        profile.setPreference('webdriver_firefox_port', port);
-        return profile.writeToDisk();
-      });
+/**
+ * A WebDriver client for Firefox.
+ */
+class Driver extends webdriver.WebDriver {
+  /**
+   * @param {(Options|capabilities.Capabilities|Object)=} opt_config The
+   *    configuration options for this driver, specified as either an
+   *    {@link Options} or {@link capabilities.Capabilities}, or as a raw hash
+   *    object.
+   * @param {promise.ControlFlow=} opt_flow The flow to
+   *     schedule commands through. Defaults to the active flow object.
+   */
+  constructor(opt_config, opt_flow) {
+    let caps;
+    if (opt_config instanceof Options) {
+      caps = opt_config.toCapabilities();
     } else {
-      profile.setPreference('webdriver_firefox_port', port);
-      return profile.writeToDisk();
+      caps = new capabilities.Capabilities(opt_config);
     }
-  }).then(function(profileDir) {
-    self.profilePath_ = profileDir;
-    return binary.launch(profileDir);
-  });
 
-  var serverUrl = this.command_
-      .then(function() { return freePort; })
-      .then(function(port) {
-        var serverUrl = url.format({
-          protocol: 'http',
-          hostname: net.getLoopbackAddress(),
-          port: port,
-          pathname: '/hub'
-        });
+    let binary = caps.get(Capability.BINARY) || new Binary();
+    caps.delete(Capability.BINARY);
+    if (typeof binary === 'string') {
+      binary = new Binary(binary);
+    }
 
-        return httpUtil.waitForServer(serverUrl, 45 * 1000).then(function() {
-          return serverUrl;
-        });
-      });
+    let profile = new Profile;
+    if (caps.has(Capability.PROFILE)) {
+      profile = caps.get(Capability.PROFILE);
+      caps.delete(Capability.PROFILE);
+    }
 
-  var executor = executors.createExecutor(serverUrl);
-  var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
+    let freePort = portprober.findFreePort();
+    let serverUrl, onQuit;
 
-  webdriver.WebDriver.call(this, driver.getSession(), executor, opt_flow);
-};
-util.inherits(Driver, webdriver.WebDriver);
+    if (caps.get(Capability.MARIONETTE)
+        || /^1|true$/i.test(process.env['SELENIUM_MARIONETTE'])) {
+      let service = createWiresService(binary);
+      serverUrl = service.start();
+      onQuit = () => service.kill();
 
+    } else {
+      let preparedProfile =
+          freePort.then(port => prepareProfile(profile, port));
+      let command = preparedProfile.then(dir => binary.launch(dir));
+
+      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);
+          });
 
-/**
- * This function is a no-op as file detectors are not supported by this
- * implementation.
- * @override
- */
-Driver.prototype.setFileDetector = function() {
-};
+      onQuit = function() {
+        let finishCommand = command.then(command => {
+          command.kill();
+          return command.result();
+        });
+        return finishCommand.finally(() => preparedProfile.then(io.rmDir));
+      };
+    }
 
+    let executor = executors.createExecutor(serverUrl);
+    let driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
+    super(driver.getSession(), executor, driver.controlFlow());
 
-/** @override */
-Driver.prototype.quit = function() {
-  return this.call(function() {
-    var self = this;
-    return Driver.super_.prototype.quit.call(this)
-        .thenFinally(function() {
-          return self.command_.then(function(command) {
-            command.kill();
-            return command.result();
-          });
-        })
-        .thenFinally(function() {
-          if (self.profilePath_) {
-            return io.rmDir(self.profilePath_);
-          }
-        });
-  }, this);
-};
+    let boundQuit = this.quit.bind(this);
+
+    /** @override */
+    this.quit = function() {
+      return boundQuit().thenFinally(onQuit);
+    };
+  }
+
+  /**
+   * This function is a no-op as file detectors are not supported by this
+   * implementation.
+   * @override
+   */
+  setFileDetector() {
+  }
+}
 
 
 // PUBLIC API