selenium-webdriver 2.47.0 → 2.52.0

package/lib/{webdriver/command.js → command.js}

@@ -19,80 +19,67 @@
  * @fileoverview Contains several classes for handling commands.
  */
 
-goog.provide('webdriver.Command');
-goog.provide('webdriver.CommandExecutor');
-goog.provide('webdriver.CommandName');
+'use strict';
 
+const promise = require('./promise');
 
 
 /**
- * Describes a command to be executed by the WebDriverJS framework.
- * @param {!webdriver.CommandName} name The name of this command.
- * @constructor
+ * Describes a command to execute.
+ * @final
  */
-webdriver.Command = function(name) {
+class Command {
+  /** @param {string} name The name of this command. */
+  constructor(name) {
+    /** @private {string} */
+    this.name_ = name;
+
+    /** @private {!Object<*>} */
+    this.parameters_ = {};
+  }
+
+  /** @return {string} This command's name. */
+  getName() {
+    return this.name_;
+  }
 
   /**
-   * The name of this command.
-   * @private {!webdriver.CommandName}
+   * Sets a parameter to send with this command.
+   * @param {string} name The parameter name.
+   * @param {*} value The parameter value.
+   * @return {!Command} A self reference.
    */
-  this.name_ = name;
+  setParameter(name, value) {
+    this.parameters_[name] = value;
+    return this;
+  }
 
   /**
-   * The parameters to this command.
-   * @private {!Object.<*>}
+   * Sets the parameters for this command.
+   * @param {!Object<*>} parameters The command parameters.
+   * @return {!Command} A self reference.
    */
-  this.parameters_ = {};
-};
-
-
-/**
- * @return {!webdriver.CommandName} This command's name.
- */
-webdriver.Command.prototype.getName = function() {
-  return this.name_;
-};
-
-
-/**
- * Sets a parameter to send with this command.
- * @param {string} name The parameter name.
- * @param {*} value The parameter value.
- * @return {!webdriver.Command} A self reference.
- */
-webdriver.Command.prototype.setParameter = function(name, value) {
-  this.parameters_[name] = value;
-  return this;
-};
-
-
-/**
- * Sets the parameters for this command.
- * @param {!Object.<*>} parameters The command parameters.
- * @return {!webdriver.Command} A self reference.
- */
-webdriver.Command.prototype.setParameters = function(parameters) {
-  this.parameters_ = parameters;
-  return this;
-};
-
-
-/**
- * Returns a named command parameter.
- * @param {string} key The parameter key to look up.
- * @return {*} The parameter value, or undefined if it has not been set.
- */
-webdriver.Command.prototype.getParameter = function(key) {
-  return this.parameters_[key];
-};
+  setParameters(parameters) {
+    this.parameters_ = parameters;
+    return this;
+  }
 
+  /**
+   * Returns a named command parameter.
+   * @param {string} key The parameter key to look up.
+   * @return {*} The parameter value, or undefined if it has not been set.
+   */
+  getParameter(key) {
+    return this.parameters_[key];
+  }
 
-/**
- * @return {!Object.<*>} The parameters to send with this command.
- */
-webdriver.Command.prototype.getParameters = function() {
-  return this.parameters_;
-};
+  /**
+   * @return {!Object<*>} The parameters to send with this command.
+   */
+  getParameters() {
+    return this.parameters_;
+  }
+}
 
 
 /**
@@ -101,7 +88,7 @@ webdriver.Command.prototype.getParameters = function() {
  * @enum {string}
  */
 // TODO: Delete obsolete command names.
-webdriver.CommandName = {
+const Name = {
   GET_SERVER_STATUS: 'getStatus',
 
   NEW_SESSION: 'newSession',
@@ -163,6 +150,7 @@ webdriver.CommandName = {
   ELEMENT_EQUALS: 'elementEquals',
 
   SCREENSHOT: 'screenshot',
+  TAKE_ELEMENT_SCREENSHOT: 'takeElementScreenshot',
   IMPLICITLY_WAIT: 'implicitlyWait',
   SET_SCRIPT_TIMEOUT: 'setScriptTimeout',
   SET_TIMEOUT: 'setTimeout',
@@ -228,19 +216,48 @@ webdriver.CommandName = {
 
 
 /**
- * Handles the execution of WebDriver {@link webdriver.Command commands}.
+ * Handles the execution of WebDriver {@link Command commands}.
  * @interface
  */
-webdriver.CommandExecutor = function() {};
+class Executor {
+  /**
+   * Executes the given {@code command}. If there is an error executing the
+   * command, the provided callback will be invoked with the offending error.
+   * Otherwise, the callback will be invoked with a null Error and non-null
+   * response object.
+   *
+   * @param {!Command} command The command to execute.
+   * @return {!promise.Promise<!Object>} A promise that will be fulfilled with
+   *     the command result.
+   */
+  execute(command) {}
+}
 
 
 /**
- * Executes the given {@code command}. If there is an error executing the
- * command, the provided callback will be invoked with the offending error.
- * Otherwise, the callback will be invoked with a null Error and non-null
- * {@link bot.response.ResponseObject} object.
- * @param {!webdriver.Command} command The command to execute.
- * @param {function(Error, !bot.response.ResponseObject=)} callback the function
- *     to invoke when the command response is ready.
+ * Wraps a promised {@link Executor}, ensuring no commands are executed until
+ * the wrapped executor has been fully resolved.
+ * @implements {Executor}
  */
-webdriver.CommandExecutor.prototype.execute = goog.abstractMethod;
+class DeferredExecutor {
+  /**
+   * @param {!promise.Promise<Executor>} delegate The promised delegate, which
+   *     may be provided by any promise-like thenable object.
+   */
+  constructor(delegate) {
+    /** @override */
+    this.execute = function(command) {
+      return delegate.then(executor => executor.execute(command));
+    };
+  }
+}
+
+
+
+// PUBLIC API
+
+
+exports.Command = Command;
+exports.Name = Name;
+exports.Executor = Executor;
+exports.DeferredExecutor = DeferredExecutor;

package/lib/{webdriver/button.js → devmode.js}

@@ -15,15 +15,20 @@
 // specific language governing permissions and limitations
 // under the License.
 
-goog.provide('webdriver.Button');
+/**
+ * @fileoverview Module used to detect if scripts are loaded from the Selenium
+ * project repo instead of from a deployed package.
+ */
+
+'use strict';
 
+const fs = require('fs');
+const path = require('path');
 
 /**
- * Enumeration of the buttons used in the advanced interactions API.
- * @enum {number}
+ * @const {boolean}
  */
-webdriver.Button = {
-  LEFT: 0,
-  MIDDLE: 1,
-  RIGHT: 2
-};
+module.exports = (function() {
+  let buildDescFile = path.join(__dirname, '..', '..', 'build.desc');
+  return fs.existsSync(buildDescFile);
+})();

package/lib/events.js

@@ -0,0 +1,210 @@
+// 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';
+
+/**
+ * Describes an event listener registered on an {@linkplain EventEmitter}.
+ */
+class Listener {
+  /**
+   * @param {!Function} fn The acutal listener function.
+   * @param {(Object|undefined)} scope The object in whose scope to invoke the
+   *     listener.
+   * @param {boolean} oneshot Whether this listener should only be used once.
+   */
+  constructor(fn, scope, oneshot) {
+    Object.defineProperties(this, {
+      fn: {value: fn},
+      scope: {value: scope},
+      oneshot: {value: oneshot}
+    });
+  }
+}
+
+
+/** @type {!WeakMap<!EventEmitter, !Map<string, !Set<!Listener>>>} */
+const EVENTS = new WeakMap;
+
+
+/**
+ * Object that can emit events for others to listen for.
+ */
+class EventEmitter {
+  /**
+   * Fires an event and calls all listeners.
+   * @param {string} type The type of event to emit.
+   * @param {...*} var_args Any arguments to pass to each listener.
+   */
+  emit(type, var_args) {
+    let events = EVENTS.get(this);
+    if (!events) {
+      return;
+    }
+
+    let args = Array.prototype.slice.call(arguments, 1);
+
+    let listeners = events.get(type);
+    if (listeners) {
+      for (let listener of listeners) {
+        listener.fn.apply(listener.scope, args);
+        if (listener.oneshot) {
+          listeners.delete(listener);
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns a mutable list of listeners for a specific type of event.
+   * @param {string} type The type of event to retrieve the listeners for.
+   * @return {!Set<!Listener>} The registered listeners for the given event
+   *     type.
+   */
+  listeners(type) {
+    let events = EVENTS.get(this);
+    if (!events) {
+      events = new Map;
+      EVENTS.set(this, events);
+    }
+
+    let listeners = events.get(type);
+    if (!listeners) {
+      listeners = new Set;
+      events.set(type, listeners);
+    }
+    return listeners;
+  }
+
+  /**
+   * Registers a listener.
+   * @param {string} type The type of event to listen for.
+   * @param {!Function} fn The function to invoke when the event is fired.
+   * @param {Object=} opt_self The object in whose scope to invoke the listener.
+   * @param {boolean=} opt_oneshot Whether the listener should b (e removed after
+   *    the first event is fired.
+   * @return {!EventEmitter} A self reference.
+   * @private
+   */
+  addListener_(type, fn, opt_self, opt_oneshot) {
+    let listeners = this.listeners(type);
+    for (let listener of listeners) {
+      if (listener.fn === fn) {
+        return this;
+      }
+    }
+    listeners.add(new Listener(fn, opt_self || undefined, !!opt_oneshot));
+    return this;
+  }
+
+  /**
+   * Registers a listener.
+   * @param {string} type The type of event to listen for.
+   * @param {!Function} fn The function to invoke when the event is fired.
+   * @param {Object=} opt_self The object in whose scope to invoke the listener.
+   * @return {!EventEmitter} A self reference.
+   */
+  addListener(type, fn, opt_self) {
+    return this.addListener_(type, fn, opt_self, false);
+  }
+
+  /**
+   * Registers a one-time listener which will be called only the first time an
+   * event is emitted, after which it will be removed.
+   * @param {string} type The type of event to listen for.
+   * @param {!Function} fn The function to invoke when the event is fired.
+   * @param {Object=} opt_self The object in whose scope to invoke the listener.
+   * @return {!EventEmitter} A self reference.
+   */
+  once(type, fn, opt_self) {
+    return this.addListener_(type, fn, opt_self, true);
+  }
+
+  /**
+   * An alias for {@link #addListener() addListener()}.
+   * @param {string} type The type of event to listen for.
+   * @param {!Function} fn The function to invoke when the event is fired.
+   * @param {Object=} opt_self The object in whose scope to invoke the listener.
+   * @return {!EventEmitter} A self reference.
+   */
+  on(type, fn, opt_self) {
+    return this.addListener(type, fn, opt_self);
+  }
+
+  /**
+   * Removes a previously registered event listener.
+   * @param {string} type The type of event to unregister.
+   * @param {!Function} listenerFn The handler function to remove.
+   * @return {!EventEmitter} A self reference.
+   */
+  removeListener(type, listenerFn) {
+    if (typeof type !== 'string' || typeof listenerFn !== 'function') {
+      throw TypeError('invalid args: expected (string, function), got ('
+          + (typeof type) + ', ' + (typeof listenerFn) + ')');
+    }
+
+    let events = EVENTS.get(this);
+    if (!events) {
+      return this;
+    }
+
+    let listeners = events.get(type);
+    if (!listeners) {
+      return this;
+    }
+
+    let match;
+    for (let listener of listeners) {
+      if (listener.fn === listenerFn) {
+        match = listener;
+        break;
+      }
+    }
+    if (match) {
+      listeners.delete(match);
+      if (!listeners.size) {
+        events.delete(type);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Removes all listeners for a specific type of event. If no event is
+   * specified, all listeners across all types will be removed.
+   * @param {string=} opt_type The type of event to remove listeners from.
+   * @return {!EventEmitter} A self reference.
+   */
+  removeAllListeners(opt_type) {
+    let events = EVENTS.get(this);
+    if (events) {
+      if (typeof opt_type === 'string') {
+        events.delete(opt_type);
+      } else {
+        EVENTS.delete(this);
+      }
+    }
+    return this;
+  }
+}
+
+
+// PUBLIC API
+
+
+exports.EventEmitter = EventEmitter;
+exports.Listener = Listener;

package/lib/firefox/webdriver.json

@@ -28,6 +28,7 @@
     "dom.disable_open_during_load": false,
     "extensions.autoDisableScopes": 10,
     "extensions.blocklist.enabled": false,
+    "extensions.checkCompatibility.nightly": false,
     "extensions.logging.enabled": true,
     "extensions.update.enabled": false,
     "extensions.update.notifyUser": false,
@@ -53,20 +54,24 @@
     "toolkit.telemetry.prompted": 2,
     "toolkit.telemetry.enabled": false,
     "toolkit.telemetry.rejected": true,
-    "xpinstall.signatures.required": false
+    "xpinstall.signatures.required": false,
+    "xpinstall.whitelist.required": false
   },
   "mutable": {
     "browser.dom.window.dump.enabled": true,
+    "browser.laterrun.enabled": false,
     "browser.newtab.url": "about:blank",
     "browser.newtabpage.enabled": false,
     "browser.startup.page": 0,
     "browser.startup.homepage": "about:blank",
+    "browser.usedOnWindows10.introURL": "about:blank",
     "dom.max_chrome_script_run_time": 30,
     "dom.max_script_run_time": 30,
     "dom.report_all_js_exceptions": true,
     "javascript.options.showInConsole": true,
     "network.http.max-connections-per-server": 10,
     "startup.homepage_welcome_url": "about:blank",
+    "startup.homepage_welcome_url.additional": "about:blank",
     "webdriver_accept_untrusted_certs": true,
     "webdriver_assume_untrusted_issuer": true
   }

package/lib/{webdriver/key.js → input.js}

@@ -15,7 +15,25 @@
 // specific language governing permissions and limitations
 // under the License.
 
-goog.provide('webdriver.Key');
+'use strict';
+
+/**
+ * @fileoverview Defines types related to user input with the WebDriver API.
+ */
+
+const promise = require('./promise');
+
+
+/**
+ * Enumeration of the buttons used in the advanced interactions API.
+ * @enum {number}
+ */
+const Button = {
+  LEFT: 0,
+  MIDDLE: 1,
+  RIGHT: 2
+};
+
 
 
 /**
@@ -25,7 +43,7 @@ goog.provide('webdriver.Key');
  *
  * @enum {string}
  */
-webdriver.Key = {
+const Key = {
   NULL:         '\uE000',
   CANCEL:       '\uE001',  // ^break
   HELP:         '\uE002',
@@ -90,3 +108,65 @@ webdriver.Key = {
   COMMAND:      '\uE03D',  // Apple command key
   META:         '\uE03D'   // alias for Windows key
 };
+
+
+/**
+ * Simulate pressing many keys at once in a "chord". Takes a sequence of
+ * {@linkplain Key keys} or strings, appends each of the values to a string,
+ * adds the chord termination key ({@link Key.NULL}) and returns the resulting
+ * string.
+ *
+ * Note: when the low-level webdriver key handlers see Keys.NULL, active
+ * modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event.
+ *
+ * @param {...string} var_args The key sequence to concatenate.
+ * @return {string} The null-terminated key sequence.
+ */
+Key.chord = function(var_args) {
+  return Array.prototype.slice.call(arguments, 0).join('') + Key.NULL;
+};
+
+
+/**
+ * Used with {@link ./webelement.WebElement#sendKeys WebElement#sendKeys} on
+ * file input elements (`<input type="file">`) to detect when the entered key
+ * sequence defines the path to a file.
+ *
+ * By default, {@linkplain ./webelement.WebElement WebElement's} will enter all
+ * key sequences exactly as entered. You may set a
+ * {@linkplain ./webdriver.WebDriver#setFileDetector file detector} on the
+ * parent WebDriver instance to define custom behavior for handling file
+ * elements. Of particular note is the
+ * {@link selenium-webdriver/remote.FileDetector}, which should be used when
+ * running against a remote
+ * [Selenium Server](http://docs.seleniumhq.org/download/).
+ */
+class FileDetector {
+
+  /**
+   * Handles the file specified by the given path, preparing it for use with
+   * the current browser. If the path does not refer to a valid file, it will
+   * be returned unchanged, otherwisee a path suitable for use with the current
+   * browser will be returned.
+   *
+   * This default implementation is a no-op. Subtypes may override this function
+   * for custom tailored file handling.
+   *
+   * @param {!./webdriver.WebDriver} driver The driver for the current browser.
+   * @param {string} path The path to process.
+   * @return {!./promise.Promise<string>} A promise for the processed file
+   *     path.
+   * @package
+   */
+  handleFile(driver, path) {
+    return promise.fulfilled(path);
+  }
+}
+
+
+// PUBLIC API
+
+
+exports.Button = Button;
+exports.Key = Key;
+exports.FileDetector = FileDetector;