selenium-webdriver 3.5.0 → 3.6.0

package/firefox/index.js

@@ -124,7 +124,6 @@ const url = require('url');
 
 const {Binary, Channel} = require('./binary'),
     Profile = require('./profile').Profile,
-    decodeProfile = require('./profile').decode,
     http = require('../http'),
     httpUtil = require('../http/util'),
     io = require('../io'),
@@ -138,35 +137,6 @@ const {Binary, Channel} = require('./binary'),
     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',
-
-  /**
-   * @deprecated This will be removed in a future release. There is no
-   *     replacement.
-   */
-  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.
  */
@@ -175,9 +145,12 @@ class Options {
     /** @private {Profile} */
     this.profile_ = null;
 
-    /** @private {Binary} */
+    /** @private {(Binary|Channel|string|null)} */
     this.binary_ = null;
 
+    /** @private {!Array<string>} */
+    this.args_ = [];
+
     /** @private {logging.Preferences} */
     this.logPrefs_ = null;
 
@@ -185,6 +158,47 @@ class Options {
     this.proxy_ = null;
   }
 
+  /**
+   * Specify additional command line arguments that should be used when starting
+   * the Firefox browser.
+   *
+   * @param {...(string|!Array<string>)} args The arguments to include.
+   * @return {!Options} A self reference.
+   */
+  addArguments(...args) {
+    this.args_ = this.args_.concat(...args);
+    return this;
+  }
+
+  /**
+   * Configures the geckodriver to start Firefox in headless mode.
+   *
+   * @return {!Options} A self reference.
+   */
+  headless() {
+    return this.addArguments('-headless');
+  }
+
+  /**
+   * Sets the initial window size when running in
+   * {@linkplain #headless headless} mode.
+   *
+   * @param {{width: number, height: number}} size The desired window size.
+   * @return {!Options} A self reference.
+   * @throws {TypeError} if width or height is unspecified, not a number, or
+   *     less than or equal to 0.
+   */
+  windowSize({width, height}) {
+    function checkArg(arg) {
+      if (typeof arg !== 'number' || arg <= 0) {
+        throw TypeError('Arguments must be {width, height} with numbers > 0');
+      }
+    }
+    checkArg(width);
+    checkArg(height);
+    return this.addArguments(`--window-size=${width},${height}`);
+  }
+
   /**
    * 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
@@ -211,17 +225,14 @@ class Options {
    * @throws {TypeError} If `binary` is an invalid type.
    */
   setBinary(binary) {
-    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');
+    if (binary instanceof Binary
+        || binary instanceof Channel
+        || typeof binary === 'string') {
+      this.binary_ = binary;
+      return this;
     }
-
-    this.binary_ = binary;
-    return this;
+    throw TypeError(
+        'binary must be a string path, Channel, or Binary object');
   }
 
   /**
@@ -245,33 +256,69 @@ class Options {
     return this;
   }
 
-  /**
-   * @deprecated This method has been deprecated and will be removed in the next
-   *     release. It is a no-op.
-   */
-  useGeckoDriver(enable) {
-    return this;
-  }
-
   /**
    * Converts these options to a {@link capabilities.Capabilities} instance.
    *
    * @return {!capabilities.Capabilities} A new capabilities object.
    */
   toCapabilities() {
-    var caps = capabilities.Capabilities.firefox();
+    let caps = capabilities.Capabilities.firefox();
+    let firefoxOptions = {};
+    caps.set('moz:firefoxOptions', firefoxOptions);
+
     if (this.logPrefs_) {
       caps.set(capabilities.Capability.LOGGING_PREFS, this.logPrefs_);
     }
+
     if (this.proxy_) {
       caps.set(capabilities.Capability.PROXY, this.proxy_);
     }
+
+    if (this.args_.length) {
+      firefoxOptions['args'] = this.args_.concat();
+    }
+
     if (this.binary_) {
-      caps.set(Capability.BINARY, this.binary_);
+      if (this.binary_ instanceof Binary) {
+        let exe = this.binary_.getExe();
+        if (exe) {
+          firefoxOptions['binary'] = exe;
+        }
+
+        let args = this.binary_.getArguments();
+        if (args.length) {
+          if (this.args_.length) {
+            throw Error(
+                'You may specify browser arguments with Options.addArguments'
+                    + ' (preferred) or Binary.addArguments, but not both');
+          }
+          firefoxOptions['args'] = args;
+        }
+      } else if (this.binary_ instanceof Channel) {
+        firefoxOptions['binary'] = this.binary_.locate();
+
+      } else if (typeof this.binary_ === 'string') {
+        firefoxOptions['binary'] = this.binary_;
+      }
     }
+
     if (this.profile_) {
-      caps.set(Capability.PROFILE, this.profile_);
+      // If the user specified a template directory or any extensions to
+      // install, we need to encode the profile as a base64 string (which
+      // requires writing it to disk first). Otherwise, if the user just
+      // specified some custom preferences, we can send those directly.
+      let profile = this.profile_;
+      if (profile.getTemplateDir() || profile.getExtensions().length) {
+        firefoxOptions['profile'] = profile.encode();
+
+      } else {
+        let prefs = profile.getPreferences();
+        if (Object.keys(prefs).length) {
+          firefoxOptions['prefs'] = prefs;
+        }
+      }
     }
+
     return caps;
   }
 }
@@ -410,111 +457,6 @@ class ServiceBuilder extends remote.DriverService.Builder {
   enableVerboseLogging(opt_trace) {
     return this.addArguments(opt_trace ? '-vv' : '-v');
   }
-
-  /**
-   * Sets the path to the executable Firefox binary that the geckodriver should
-   * use. If this method is not called, this builder will attempt to locate
-   * Firefox in the default installation location for the current platform.
-   *
-   * @param {(string|!Binary)} binary Path to the executable Firefox binary to use.
-   * @return {!ServiceBuilder} A self reference.
-   * @see Binary#locate()
-   */
-  setFirefoxBinary(binary) {
-    let exe = typeof binary === 'string'
-        ? Promise.resolve(binary) : binary.locate();
-    return this.addArguments('-b', exe);
-  }
-}
-
-
-/**
- * @typedef {{executor: !command.Executor,
- *            capabilities: (!capabilities.Capabilities|
- *                           {desired: (capabilities.Capabilities|undefined),
- *                            required: (capabilities.Capabilities|undefined)}),
- *            onQuit: function(this: void): ?}}
- */
-var DriverSpec;
-
-
-/**
- * @param {(http.Executor|remote.DriverService|undefined)} executor
- * @param {!capabilities.Capabilities} caps
- * @param {Profile} profile
- * @param {Binary} binary
- * @return {DriverSpec}
- */
-function createGeckoDriver(executor, caps, profile, binary) {
-  let firefoxOptions = caps.get('moz:firefoxOptions') || {};
-  caps.set('moz:firefoxOptions', firefoxOptions);
-
-  if (binary) {
-    if (binary.getExe()) {
-      firefoxOptions['binary'] = binary.getExe();
-    }
-
-    let args = binary.getArguments();
-    if (args.length) {
-      firefoxOptions['args'] = args;
-    }
-  }
-
-  if (profile) {
-    // If the user specified a template directory or any extensions to install,
-    // we need to encode the profile as a base64 string (which requires writing
-    // it to disk first). Otherwise, if the user just specified some custom
-    // preferences, we can send those directly.
-    if (profile.getTemplateDir() || profile.getExtensions().length) {
-      firefoxOptions['profile'] = profile.encode();
-
-    } else {
-      let prefs = profile.getPreferences();
-      if (Object.keys(prefs).length) {
-        firefoxOptions['prefs'] = prefs;
-      }
-    }
-  }
-
-  let sessionCaps = caps;
-  if (caps.has(capabilities.Capability.PROXY)) {
-    let proxy = normalizeProxyConfiguration(
-        caps.get(capabilities.Capability.PROXY));
-
-    // Marionette requires proxy settings to be specified as required
-    // capabilities. See mozilla/geckodriver#97
-    let required = new capabilities.Capabilities()
-        .set(capabilities.Capability.PROXY, proxy);
-
-    caps.delete(capabilities.Capability.PROXY);
-    sessionCaps = {required, desired: caps};
-  }
-
-  /** @type {!command.Executor} */
-  let cmdExecutor;
-  let onQuit = function() {};
-
-  if (executor instanceof http.Executor) {
-    configureExecutor(executor);
-    cmdExecutor = executor;
-  } else if (executor instanceof remote.DriverService) {
-    cmdExecutor = createExecutor(executor.start());
-    onQuit = () => executor.kill();
-  } else {
-    let builder = new ServiceBuilder();
-    if (binary) {
-      builder.setFirefoxBinary(binary);
-    }
-    let service = builder.build();
-    cmdExecutor = createExecutor(service.start());
-    onQuit = () => service.kill();
-  }
-
-  return {
-    executor: cmdExecutor,
-    capabilities: sessionCaps,
-    onQuit
-  };
 }
 
 
@@ -555,21 +497,29 @@ class Driver extends webdriver.WebDriver {
       caps = new capabilities.Capabilities(opt_config);
     }
 
-    let binary = caps.get(Capability.BINARY) || new Binary();
-    caps.delete(Capability.BINARY);
-    if (typeof binary === 'string') {
-      binary = new Binary(binary);
+    if (caps.has(capabilities.Capability.PROXY)) {
+      let proxy =
+          normalizeProxyConfiguration(caps.get(capabilities.Capability.PROXY));
+      caps.set(capabilities.Capability.PROXY, proxy);
     }
 
-    let profile;
-    if (caps.has(Capability.PROFILE)) {
-      profile = caps.get(Capability.PROFILE);
-      caps.delete(Capability.PROFILE);
+    let executor;
+    let onQuit;
+
+    if (opt_executor instanceof http.Executor) {
+      executor = opt_executor;
+      configureExecutor(executor);
+    } else if (opt_executor instanceof remote.DriverService) {
+      executor = createExecutor(opt_executor.start());
+      onQuit = () => opt_executor.kill();
+    } else {
+      let service = new ServiceBuilder().build();
+      executor = createExecutor(service.start());
+      onQuit = () => service.kill();
     }
 
-    let spec = createGeckoDriver(opt_executor, caps, profile, binary);
     return /** @type {!Driver} */(super.createSession(
-        spec.executor, spec.capabilities, opt_flow, spec.onQuit));
+        executor, caps, opt_flow, onQuit));
   }
 
   /**

package/firefox/profile.js

@@ -33,28 +33,6 @@ const isDevMode = require('../lib/devmode'),
     extension = require('./extension');
 
 
-/** @const */
-const WEBDRIVER_PREFERENCES_PATH = isDevMode
-    ? path.join(__dirname, '../../../firefox-driver/webdriver.json')
-    : path.join(__dirname, '../lib/firefox/webdriver.json');
-
-/** @type {Object} */
-var defaultPreferences = null;
-
-/**
- * Synchronously loads the default preferences used for the FirefoxDriver.
- * @return {!Object} The default preferences JSON object.
- */
-function getDefaultPreferences() {
-  if (!defaultPreferences) {
-    var contents = /** @type {string} */(
-        fs.readFileSync(WEBDRIVER_PREFERENCES_PATH, 'utf8'));
-    defaultPreferences = /** @type {!Object} */(JSON.parse(contents));
-  }
-  return defaultPreferences;
-}
-
-
 /**
  * Parses a user.js file in a Firefox profile directory.
  * @param {string} f Path to the file to parse.
@@ -96,9 +74,13 @@ function writeUserPrefs(prefs, dir) {
   var userPrefs = path.join(dir, 'user.js');
   return loadUserPrefs(userPrefs).then(function(overrides) {
     Object.assign(prefs, overrides);
-    Object.assign(prefs, getDefaultPreferences()['frozen']);
 
-    var contents = Object.keys(prefs).map(function(key) {
+    let keys = Object.keys(prefs);
+    if (!keys.length) {
+      return dir;
+    }
+
+    let contents = Object.keys(prefs).map(function(key) {
       return 'user_pref(' + JSON.stringify(key) + ', ' +
           JSON.stringify(prefs[key]) + ');';
     }).join('\n');
@@ -146,22 +128,6 @@ function installExtensions(extensions, dir) {
 }
 
 
-/**
- * Decodes a base64 encoded profile.
- * @param {string} data The base64 encoded string.
- * @return {!Promise<string>} A promise for the path to the decoded profile
- *     directory.
- */
-function decode(data) {
-  return io.tmpFile().then(function(file) {
-    let buf = new Buffer(data, 'base64');
-    return io.write(file, buf)
-        .then(io.tmpDir)
-        .then(dir => unzip(file, dir));
-  });
-}
-
-
 
 /**
  * Models a Firefox profile directory for use with the FirefoxDriver. The
@@ -178,15 +144,9 @@ class Profile {
     /** @private {!Object} */
     this.preferences_ = {};
 
-    /** @private {boolean} */
-    this.nativeEventsEnabled_ = true;
-
     /** @private {(string|undefined)} */
     this.template_ = opt_dir;
 
-    /** @private {number} */
-    this.port_ = 0;
-
     /** @private {!Array<string>} */
     this.extensions_ = [];
   }
@@ -222,12 +182,6 @@ class Profile {
    * @throws {Error} If attempting to set a frozen preference.
    */
   setPreference(key, value) {
-    var frozen = getDefaultPreferences()['frozen'];
-    if (frozen.hasOwnProperty(key) && frozen[key] !== value) {
-      throw Error('You may not set ' + key + '=' + JSON.stringify(value)
-          + '; value is frozen for proper WebDriver functionality ('
-          + key + '=' + JSON.stringify(frozen[key]) + ')');
-    }
     this.preferences_[key] = value;
   }
 
@@ -262,23 +216,6 @@ class Profile {
     this.preferences_['webdriver_firefox_allowed_hosts'] = host;
   }
 
-  /**
-   * @return {number} The port this profile is currently configured to use, or
-   *     0 if the port will be selected at random when the profile is written
-   *     to disk.
-   */
-  getPort() {
-    return this.port_;
-  }
-
-  /**
-   * Sets the port to use for the WebDriver extension loaded by this profile.
-   * @param {number} port The desired port, or 0 to use any free port.
-   */
-  setPort(port) {
-    this.port_ = port;
-  }
-
   /**
    * @return {boolean} Whether the FirefoxDriver is configured to automatically
    *     accept untrusted SSL certificates.
@@ -312,22 +249,6 @@ class Profile {
     return !!this.preferences_['webdriver_assume_untrusted_issuer'];
   }
 
-  /**
-   * Sets whether to use native events with this profile.
-   * @param {boolean} enabled .
-   */
-  setNativeEventsEnabled(enabled) {
-    this.nativeEventsEnabled_ = enabled;
-  }
-
-  /**
-   * Returns whether native events are enabled in this profile.
-   * @return {boolean} .
-   */
-  nativeEventsEnabled() {
-    return this.nativeEventsEnabled_;
-  }
-
   /**
    * Writes this profile to disk.
    * @return {!Promise<string>} A promise for the path to the new profile
@@ -344,10 +265,7 @@ class Profile {
     }
 
     // Freeze preferences for async operations.
-    var prefs = {};
-    Object.assign(prefs, getDefaultPreferences()['mutable']);
-    Object.assign(prefs, getDefaultPreferences()['frozen']);
-    Object.assign(prefs, this.preferences_);
+    let prefs = Object.assign({}, this.preferences_);
 
     // Freeze extensions for async operations.
     var extensions = this.extensions_.concat();
@@ -390,5 +308,4 @@ class Profile {
 
 
 exports.Profile = Profile;
-exports.decode = decode;
 exports.loadUserPrefs = loadUserPrefs;

package/lib/capabilities.js

@@ -204,16 +204,19 @@ function toMap(hash) {
 /**
  * Describes a set of capabilities for a WebDriver session.
  */
-class Capabilities extends Map {
+class Capabilities {
   /**
-   * @param {(Capabilities|Map<string, ?>|Object)=} opt_other Another set of
+   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
    *     capabilities to initialize this instance from.
    */
-  constructor(opt_other) {
-    if (opt_other && !(opt_other instanceof Map)) {
-      opt_other = toMap(opt_other);
+  constructor(other = undefined) {
+    if (other instanceof Capabilities) {
+      other = other.map_;
+    } else if (other && !(other instanceof Map)) {
+      other = toMap(other);
     }
-    super(opt_other);
+    /** @private @const {!Map<string, ?>} */
+    this.map_ = new Map(other);
   }
 
   /**
@@ -221,8 +224,7 @@ class Capabilities extends Map {
    */
   static android() {
     return new Capabilities()
-        .set(Capability.BROWSER_NAME, Browser.ANDROID)
-        .set(Capability.PLATFORM, 'ANDROID');
+        .set(Capability.BROWSER_NAME, Browser.ANDROID);
   }
 
   /**
@@ -237,8 +239,7 @@ class Capabilities extends Map {
    */
   static edge() {
     return new Capabilities()
-        .set(Capability.BROWSER_NAME, Browser.EDGE)
-        .set(Capability.PLATFORM, 'WINDOWS');
+        .set(Capability.BROWSER_NAME, Browser.EDGE);
   }
 
   /**
@@ -253,8 +254,7 @@ class Capabilities extends Map {
    */
   static ie() {
     return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.INTERNET_EXPLORER).
-        set(Capability.PLATFORM, 'WINDOWS');
+        set(Capability.BROWSER_NAME, Browser.INTERNET_EXPLORER);
   }
 
   /**
@@ -262,8 +262,7 @@ class Capabilities extends Map {
    */
   static ipad() {
     return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.IPAD).
-        set(Capability.PLATFORM, 'MAC');
+        set(Capability.BROWSER_NAME, Browser.IPAD);
   }
 
   /**
@@ -271,8 +270,7 @@ class Capabilities extends Map {
    */
   static iphone() {
     return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.IPHONE).
-        set(Capability.PLATFORM, 'MAC');
+        set(Capability.BROWSER_NAME, Browser.IPHONE);
   }
 
   /**
@@ -296,8 +294,7 @@ class Capabilities extends Map {
    */
   static safari() {
     return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.SAFARI).
-        set(Capability.PLATFORM, 'MAC');
+        set(Capability.BROWSER_NAME, Browser.SAFARI);
   }
 
   /**
@@ -328,6 +325,35 @@ class Capabilities extends Map {
     return serialize(this);
   }
 
+  /**
+   * @param {string} key the parameter key to get.
+   * @return {T} the stored parameter value.
+   * @template T
+   */
+  get(key) {
+    return this.map_.get(key);
+  }
+
+  /**
+   * @param {string} key the key to test.
+   * @return {boolean} whether this capability set has the specified key.
+   */
+  has(key) {
+    return this.map_.has(key);
+  }
+
+  /**
+   * @return {!Iterator<string>} an iterator of the keys set.
+   */
+  keys() {
+    return this.map_.keys();
+  }
+
+  /** @return {number} The number of capabilities set. */
+  get size() {
+    return this.map_.size;
+  }
+
   /**
    * Merges another set of capabilities into this instance.
    * @param {!(Capabilities|Map<String, ?>|Object<string, ?>)} other The other
@@ -339,7 +365,12 @@ class Capabilities extends Map {
       throw new TypeError('no capabilities provided for merge');
     }
 
-    if (!(other instanceof Map)) {
+    let map;
+    if (other instanceof Capabilities) {
+      map = other.map_;
+    } else if (other instanceof Map) {
+      map = other;
+    } else {
       other = toMap(other);
     }
 
@@ -350,18 +381,26 @@ class Capabilities extends Map {
     return this;
   }
 
+  /**
+   * Deletes an entry from this set of capabilities.
+   *
+   * @param {string} key the capability key to delete.
+   */
+  delete(key) {
+    this.map_.delete(key);
+  }
+
   /**
    * @param {string} key The capability key.
    * @param {*} value The capability value.
    * @return {!Capabilities} A self reference.
    * @throws {TypeError} If the `key` is not a string.
-   * @override
    */
   set(key, value) {
     if (typeof key !== 'string') {
       throw new TypeError('Capability keys must be strings: ' + typeof key);
     }
-    super.set(key, value);
+    this.map_.set(key, value);
     return this;
   }