selenium-webdriver 2.47.0 → 2.52.0

package/ie.js

@@ -27,21 +27,19 @@
 
 'use strict';
 
-var fs = require('fs'),
+const fs = require('fs'),
     util = require('util');
 
-var webdriver = require('./index'),
-    executors = require('./executors'),
+const executors = require('./executors'),
     io = require('./io'),
+    capabilities = require('./lib/capabilities'),
+    promise = require('./lib/promise'),
+    webdriver = require('./lib/webdriver'),
     portprober = require('./net/portprober'),
     remote = require('./remote');
 
 
-/**
- * @const
- * @final
- */
-var IEDRIVER_EXE = 'IEDriverServer.exe';
+const IEDRIVER_EXE = 'IEDriverServer.exe';
 
 
 
@@ -49,7 +47,7 @@ var IEDRIVER_EXE = 'IEDriverServer.exe';
  * IEDriverServer logging levels.
  * @enum {string}
  */
-var Level = {
+const Level = {
   FATAL: 'FATAL',
   ERROR: 'ERROR',
   WARN: 'WARN',
@@ -65,7 +63,7 @@ var Level = {
  * https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities#ie-specific
  * @enum {string}
  */
-var Key = {
+const Key = {
   IGNORE_PROTECTED_MODE_SETTINGS: 'ignoreProtectedModeSettings',
   IGNORE_ZOOM_SETTING: 'ignoreZoomSetting',
   INITIAL_BROWSER_URL: 'initialBrowserUrl',
@@ -87,290 +85,271 @@ var Key = {
 
 /**
  * Class for managing IEDriver specific options.
- * @constructor
  */
-var Options = function() {
-  /** @private {!Object<(boolean|number|string)>} */
-  this.options_ = {};
-
-  /** @private {(webdriver.ProxyConfig|null)} */
-  this.proxy_ = null;
-};
-
+class Options {
+  constructor() {
+    /** @private {!Object<(boolean|number|string|!Array<string>)>} */
+    this.options_ = {};
 
+    /** @private {(capabilities.ProxyConfig|null)} */
+    this.proxy_ = null;
+  }
 
-/**
- * Extracts the IEDriver specific options from the given capabilities
- * object.
- * @param {!webdriver.Capabilities} capabilities The capabilities object.
- * @return {!Options} The IEDriver options.
- */
-Options.fromCapabilities = function(capabilities) {
-  var options = new Options();
-  var map = options.options_;
-
-  Object.keys(Key).forEach(function(key) {
-    key = Key[key];
-    if (capabilities.has(key)) {
-      map[key] = capabilities.get(key);
+  /**
+   * Extracts the IEDriver specific options from the given capabilities
+   * object.
+   * @param {!capabilities.Capabilities} caps The capabilities object.
+   * @return {!Options} The IEDriver options.
+   */
+  static fromCapabilities(caps) {
+    var options = new Options();
+    var map = options.options_;
+
+    Object.keys(Key).forEach(function(key) {
+      key = Key[key];
+      if (caps.has(key)) {
+        map[key] = caps.get(key);
+      }
+    });
+
+    if (caps.has(capabilities.Capability.PROXY)) {
+      options.setProxy(caps.get(capabilities.Capability.PROXY));
     }
-  });
 
-  if (capabilities.has(webdriver.Capability.PROXY)) {
-    options.setProxy(capabilities.get(webdriver.Capability.PROXY));
+    return options;
   }
 
-  return options;
-};
-
-
-/**
- * Whether to disable the protected mode settings check when the session is
- * created. Disbling this setting may lead to significant instability as the
- * browser may become unresponsive/hang. Only "best effort" support is provided
- * when using this capability.
- *
- * For more information, refer to the IEDriver's
- * [required system configuration](http://goo.gl/eH0Yi3).
- *
- * @param {boolean} ignoreSettings Whether to ignore protected mode settings.
- * @return {!Options} A self reference.
- */
-Options.prototype.introduceFlakinessByIgnoringProtectedModeSettings =
-    function(ignoreSettings) {
-      this.options_[Key.IGNORE_PROTECTED_MODE_SETTINGS] = !!ignoreSettings;
-      return this;
-    };
-
-
-/**
- * Indicates whether to skip the check that the browser's zoom level is set to
- * 100%.
- *
- * @parm {boolean} ignore Whether to ignore the browser's zoom level settings.
- * @return {!Options} A self reference.
- */
-Options.prototype.ignoreZoomSetting = function(ignore) {
-  this.options_[Key.IGNORE_ZOOM_SETTING] = !!ignore;
-  return this;
-};
-
-
-/**
- * Sets the initial URL loaded when IE starts. This is intended to be used with
- * {@link #ignoreProtectedModeSettings} to allow the user to initialize IE in
- * the proper Protected Mode zone. Setting this option may cause browser
- * instability or flaky and unresponsive code. Only "best effort" support is
- * provided when using this option.
- *
- * @param {string} url The initial browser URL.
- * @return {!Options} A self reference.
- */
-Options.prototype.initialBrowserUrl = function(url) {
-  this.options_[Key.INITIAL_BROWSER_URL] = url;
-  return this;
-};
-
-
-/**
- * Configures whether to enable persistent mouse hovering (true by default).
- * Persistent hovering is achieved by continuously firing mouse over events at
- * the last location the mouse cursor has been moved to.
- *
- * @param {boolean} enable Whether to enable persistent hovering.
- * @return {!Options} A self reference.
- */
-Options.prototype.enablePersistentHover = function(enable) {
-  this.options_[Key.ENABLE_PERSISTENT_HOVER] = !!enable;
-  return this;
-};
-
-
-/**
- * Configures whether the driver should attempt to remove obsolete
- * {@linkplain webdriver.WebElement WebElements} from its internal cache on
- * page navigation (true by default). Disabling this option will cause the
- * driver to run with a larger memory footprint.
- *
- * @param {boolean} enable Whether to enable element reference cleanup.
- * @return {!Options} A self reference.
- */
-Options.prototype.enableElementCacheCleanup = function(enable) {
-  this.options_[Key.ENABLE_ELEMENT_CACHE_CLEANUP] = !!enable;
-  return this;
-};
-
-
-/**
- * Configures whether to require the IE window to have input focus before
- * performing any user interactions (i.e. mouse or keyboard events). This
- * option is disabled by default, but delivers much more accurate interaction
- * events when enabled.
- *
- * @param {boolean} require Whether to require window focus.
- * @return {!Options} A self reference.
- */
-Options.prototype.requireWindowFocus = function(require) {
-  this.options_[Key.REQUIRE_WINDOW_FOCUS] = !!require;
-  return this;
-};
-
-
-/**
- * Configures the timeout, in milliseconds, that the driver will attempt to
- * located and attach to a newly opened instance of Internet Explorer. The
- * default is zero, which indicates waiting indefinitely.
- *
- * @param {number} timeout How long to wait for IE.
- * @return {!Options} A self reference.
- */
-Options.prototype.browserAttachTimeout = function(timeout) {
-  this.options_[Key.BROWSER_ATTACH_TIMEOUT] = Math.max(timeout, 0);
-  return this;
-};
-
-
-/**
- * Configures whether to launch Internet Explorer using the CreateProcess API.
- * If this option is not specified, IE is launched using IELaunchURL, if
- * available. For IE 8 and above, this option requires the TabProcGrowth
- * registry value to be set to 0.
- *
- * @param {boolean} force Whether to use the CreateProcess API.
- * @return {!Options} A self reference.
- */
-Options.prototype.forceCreateProcessApi = function(force) {
-  this.options_[Key.FORCE_CREATE_PROCESS] = !!force;
-  return this;
-};
-
-
-/**
- * Specifies command-line switches to use when launching Internet Explorer.
- * This is only valid when used with {@link #forceCreateProcessApi}.
- *
- * @param {...(string|!Array.<string>)} var_args The arguments to add.
- * @return {!Options} A self reference.
- */
-Options.prototype.addArguments = function(var_args) {
-  var args = this.options_[Key.BROWSER_COMMAND_LINE_SWITCHES] || [];
-  args = args.concat.apply(args, arguments);
-  this.options_[Key.BROWSER_COMMAND_LINE_SWITCHES] = args;
-  return this;
-};
-
+  /**
+   * Whether to disable the protected mode settings check when the session is
+   * created. Disbling this setting may lead to significant instability as the
+   * browser may become unresponsive/hang. Only "best effort" support is provided
+   * when using this capability.
+   *
+   * For more information, refer to the IEDriver's
+   * [required system configuration](http://goo.gl/eH0Yi3).
+   *
+   * @param {boolean} ignoreSettings Whether to ignore protected mode settings.
+   * @return {!Options} A self reference.
+   */
+  introduceFlakinessByIgnoringProtectedModeSettings(ignoreSettings) {
+    this.options_[Key.IGNORE_PROTECTED_MODE_SETTINGS] = !!ignoreSettings;
+    return this;
+  }
 
-/**
- * Configures whether proxies should be configured on a per-process basis. If
- * not set, setting a {@linkplain #setProxy proxy} will configure the system
- * proxy. The default behavior is to use the system proxy.
- *
- * @param {boolean} enable Whether to enable per-process proxy settings.
- * @return {!Options} A self reference.
- */
-Options.prototype.usePerProcessProxy = function(enable) {
-  this.options_[Key.USE_PER_PROCESS_PROXY] = !!enable;
-  return this;
-};
+  /**
+   * Indicates whether to skip the check that the browser's zoom level is set to
+   * 100%.
+   *
+   * @param {boolean} ignore Whether to ignore the browser's zoom level settings.
+   * @return {!Options} A self reference.
+   */
+  ignoreZoomSetting(ignore) {
+    this.options_[Key.IGNORE_ZOOM_SETTING] = !!ignore;
+    return this;
+  }
 
+  /**
+   * Sets the initial URL loaded when IE starts. This is intended to be used with
+   * {@link #ignoreProtectedModeSettings} to allow the user to initialize IE in
+   * the proper Protected Mode zone. Setting this option may cause browser
+   * instability or flaky and unresponsive code. Only "best effort" support is
+   * provided when using this option.
+   *
+   * @param {string} url The initial browser URL.
+   * @return {!Options} A self reference.
+   */
+  initialBrowserUrl(url) {
+    this.options_[Key.INITIAL_BROWSER_URL] = url;
+    return this;
+  }
 
-/**
- * Configures whether to clear the cache, cookies, history, and saved form data
- * before starting the browser. _Using this capability will clear session data
- * for all running instances of Internet Explorer, including those started
- * manually._
- *
- * @param {boolean} cleanSession Whether to clear all session data on startup.
- * @return {!Options} A self reference.
- */
-Options.prototype.ensureCleanSession = function(cleanSession) {
-  this.options_[Key.ENSURE_CLEAN_SESSION] = !!cleanSession;
-  return this;
-};
+  /**
+   * Configures whether to enable persistent mouse hovering (true by default).
+   * Persistent hovering is achieved by continuously firing mouse over events at
+   * the last location the mouse cursor has been moved to.
+   *
+   * @param {boolean} enable Whether to enable persistent hovering.
+   * @return {!Options} A self reference.
+   */
+  enablePersistentHover(enable) {
+    this.options_[Key.ENABLE_PERSISTENT_HOVER] = !!enable;
+    return this;
+  }
 
+  /**
+   * Configures whether the driver should attempt to remove obsolete
+   * {@linkplain webdriver.WebElement WebElements} from its internal cache on
+   * page navigation (true by default). Disabling this option will cause the
+   * driver to run with a larger memory footprint.
+   *
+   * @param {boolean} enable Whether to enable element reference cleanup.
+   * @return {!Options} A self reference.
+   */
+  enableElementCacheCleanup(enable) {
+    this.options_[Key.ENABLE_ELEMENT_CACHE_CLEANUP] = !!enable;
+    return this;
+  }
 
-/**
- * Sets the path to the log file the driver should log to.
- * @param {string} path The log file path.
- * @return {!Options} A self reference.
- */
-Options.prototype.setLogFile = function(file) {
-  this.options_[Key.LOG_FILE] = file;
-  return this;
-};
+  /**
+   * Configures whether to require the IE window to have input focus before
+   * performing any user interactions (i.e. mouse or keyboard events). This
+   * option is disabled by default, but delivers much more accurate interaction
+   * events when enabled.
+   *
+   * @param {boolean} require Whether to require window focus.
+   * @return {!Options} A self reference.
+   */
+  requireWindowFocus(require) {
+    this.options_[Key.REQUIRE_WINDOW_FOCUS] = !!require;
+    return this;
+  }
 
+  /**
+   * Configures the timeout, in milliseconds, that the driver will attempt to
+   * located and attach to a newly opened instance of Internet Explorer. The
+   * default is zero, which indicates waiting indefinitely.
+   *
+   * @param {number} timeout How long to wait for IE.
+   * @return {!Options} A self reference.
+   */
+  browserAttachTimeout(timeout) {
+    this.options_[Key.BROWSER_ATTACH_TIMEOUT] = Math.max(timeout, 0);
+    return this;
+  }
 
-/**
- * Sets the IEDriverServer's logging {@linkplain Level level}.
- * @param {Level} level The logging level.
- * @return {!Options} A self reference.
- */
-Options.prototype.setLogLevel = function(level) {
-  this.options_[Key.LOG_LEVEL] = level;
-  return this;
-};
+  /**
+   * Configures whether to launch Internet Explorer using the CreateProcess API.
+   * If this option is not specified, IE is launched using IELaunchURL, if
+   * available. For IE 8 and above, this option requires the TabProcGrowth
+   * registry value to be set to 0.
+   *
+   * @param {boolean} force Whether to use the CreateProcess API.
+   * @return {!Options} A self reference.
+   */
+  forceCreateProcessApi(force) {
+    this.options_[Key.FORCE_CREATE_PROCESS] = !!force;
+    return this;
+  }
 
+  /**
+   * Specifies command-line switches to use when launching Internet Explorer.
+   * This is only valid when used with {@link #forceCreateProcessApi}.
+   *
+   * @param {...(string|!Array.<string>)} var_args The arguments to add.
+   * @return {!Options} A self reference.
+   */
+  addArguments(var_args) {
+    var args = this.options_[Key.BROWSER_COMMAND_LINE_SWITCHES] || [];
+    args = args.concat.apply(args, arguments);
+    this.options_[Key.BROWSER_COMMAND_LINE_SWITCHES] = args;
+    return this;
+  }
 
-/**
- * Sets the IP address of the driver's host adapter.
- * @param {string} host The IP address to use.
- * @return {!Options} A self reference.
- */
-Options.prototype.setHost = function(host) {
-  this.options_[Key.HOST] = host;
-  return this;
-};
+  /**
+   * Configures whether proxies should be configured on a per-process basis. If
+   * not set, setting a {@linkplain #setProxy proxy} will configure the system
+   * proxy. The default behavior is to use the system proxy.
+   *
+   * @param {boolean} enable Whether to enable per-process proxy settings.
+   * @return {!Options} A self reference.
+   */
+  usePerProcessProxy(enable) {
+    this.options_[Key.USE_PER_PROCESS_PROXY] = !!enable;
+    return this;
+  }
 
+  /**
+   * Configures whether to clear the cache, cookies, history, and saved form data
+   * before starting the browser. _Using this capability will clear session data
+   * for all running instances of Internet Explorer, including those started
+   * manually._
+   *
+   * @param {boolean} cleanSession Whether to clear all session data on startup.
+   * @return {!Options} A self reference.
+   */
+  ensureCleanSession(cleanSession) {
+    this.options_[Key.ENSURE_CLEAN_SESSION] = !!cleanSession;
+    return this;
+  }
 
-/**
- * Sets the path of the temporary data directory to use.
- * @param {string} path The log file path.
- * @return {!Options} A self reference.
- */
-Options.prototype.setExtractPath = function(path) {
-  this.options_[Key.EXTRACT_PATH] = path;
-  return this;
-};
+  /**
+   * Sets the path to the log file the driver should log to.
+   * @param {string} file The log file path.
+   * @return {!Options} A self reference.
+   */
+  setLogFile(file) {
+    this.options_[Key.LOG_FILE] = file;
+    return this;
+  }
 
+  /**
+   * Sets the IEDriverServer's logging {@linkplain Level level}.
+   * @param {Level} level The logging level.
+   * @return {!Options} A self reference.
+   */
+  setLogLevel(level) {
+    this.options_[Key.LOG_LEVEL] = level;
+    return this;
+  }
 
-/**
- * Sets whether the driver should start in silent mode.
- * @param {boolean} silent Whether to run in silent mode.
- * @return {!Options} A self reference.
- */
-Options.prototype.silent = function(silent) {
-  this.options_[Key.SILENT] = silent;
-  return this;
-};
+  /**
+   * Sets the IP address of the driver's host adapter.
+   * @param {string} host The IP address to use.
+   * @return {!Options} A self reference.
+   */
+  setHost(host) {
+    this.options_[Key.HOST] = host;
+    return this;
+  }
 
+  /**
+   * Sets the path of the temporary data directory to use.
+   * @param {string} path The log file path.
+   * @return {!Options} A self reference.
+   */
+  setExtractPath(path) {
+    this.options_[Key.EXTRACT_PATH] = path;
+    return this;
+  }
 
-/**
- * Sets the proxy settings for the new session.
- * @param {webdriver.ProxyConfig} proxy The proxy configuration to use.
- * @return {!Options} A self reference.
- */
-Options.prototype.setProxy = function(proxy) {
-  this.proxy_ = proxy;
-  return this;
-};
+  /**
+   * Sets whether the driver should start in silent mode.
+   * @param {boolean} silent Whether to run in silent mode.
+   * @return {!Options} A self reference.
+   */
+  silent(silent) {
+    this.options_[Key.SILENT] = silent;
+    return this;
+  }
 
+  /**
+   * Sets the proxy settings for the new session.
+   * @param {capabilities.ProxyConfig} proxy The proxy configuration to use.
+   * @return {!Options} A self reference.
+   */
+  setProxy(proxy) {
+    this.proxy_ = proxy;
+    return this;
+  }
 
-/**
- * Converts this options instance to a {@link webdriver.Capabilities} object.
- * @param {webdriver.Capabilities=} opt_capabilities The capabilities to merge
- *     these options into, if any.
- * @return {!webdriver.Capabilities} The capabilities.
- */
-Options.prototype.toCapabilities = function(opt_capabilities) {
-  var capabilities = opt_capabilities || webdriver.Capabilities.ie();
-  if (this.proxy_) {
-    capabilities.set(webdriver.Capability.PROXY, this.proxy_);
+  /**
+   * Converts this options instance to a {@link capabilities.Capabilities}
+   * object.
+   * @param {capabilities.Capabilities=} opt_capabilities The capabilities to
+   *     merge these options into, if any.
+   * @return {!capabilities.Capabilities} The capabilities.
+   */
+  toCapabilities(opt_capabilities) {
+    var caps = opt_capabilities || capabilities.Capabilities.ie();
+    if (this.proxy_) {
+      caps.set(capabilities.Capability.PROXY, this.proxy_);
+    }
+    Object.keys(this.options_).forEach(function(key) {
+      caps.set(key, this.options_[key]);
+    }, this);
+    return caps;
   }
-  Object.keys(this.options_).forEach(function(key) {
-    capabilities.set(key, this.options_[key]);
-  }, this);
-  return capabilities;
-};
+}
 
 
 function createServiceFromCapabilities(capabilities) {
@@ -381,11 +360,15 @@ function createServiceFromCapabilities(capabilities) {
         'WebDriver server?');
   }
 
-  var exe = io.findInPath(IEDRIVER_EXE, true);
-  if (!fs.existsSync(exe)) {
-    throw Error('File does not exist: ' + exe);
+  let exe = io.findInPath(IEDRIVER_EXE, true);
+  if (!exe || !fs.existsSync(exe)) {
+    throw Error(
+        `${IEDRIVER_EXE} could not be found on the current PATH. Please ` +
+        `download the latest version of ${IEDRIVER_EXE} from ` +
+        'http://selenium-release.storage.googleapis.com/index.html and ' +
+        'ensure it can be found on your system PATH.');
   }
- 
+
   var args = [];
   if (capabilities.has(Key.HOST)) {
     args.push('--host=' + capabilities.get(Key.HOST));
@@ -417,44 +400,40 @@ function createServiceFromCapabilities(capabilities) {
 
 /**
  * A WebDriver client for Microsoft's Internet Explorer.
- *
- * @param {(webdriver.Capabilities|Options)=} opt_config The configuration
- *     options.
- * @param {webdriver.promise.ControlFlow=} opt_flow The control flow to use, or
- *     {@code null} to use the currently active flow.
- * @constructor
- * @extends {webdriver.WebDriver}
  */
-var Driver = function(opt_config, opt_flow) {
-  var capabilities = opt_config instanceof Options ? 
-      opt_config.toCapabilities() :
-      (opt_config || webdriver.Capabilities.ie());
-
-  var service = createServiceFromCapabilities(capabilities);
-  var executor = executors.createExecutor(service.start());
-  var driver = webdriver.WebDriver.createSession(
-      executor, capabilities, opt_flow);
-
-  webdriver.WebDriver.call(
-      this, driver.getSession(), executor, driver.controlFlow());
-
-  var boundQuit = this.quit.bind(this);
-
-  /** @override */
-  this.quit = function() {
-    return boundQuit().thenFinally(service.kill.bind(service));
-  };
-};
-util.inherits(Driver, webdriver.WebDriver);
-
+class Driver extends webdriver.WebDriver {
+  /**
+   * @param {(capabilities.Capabilities|Options)=} opt_config The configuration
+   *     options.
+   * @param {promise.ControlFlow=} opt_flow The control flow to use,
+   *     or {@code null} to use the currently active flow.
+   */
+  constructor(opt_config, opt_flow) {
+    var caps = opt_config instanceof Options ?
+        opt_config.toCapabilities() :
+        (opt_config || capabilities.Capabilities.ie());
+
+    var service = createServiceFromCapabilities(caps);
+    var executor = executors.createExecutor(service.start());
+    var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
+
+    super(driver.getSession(), executor, driver.controlFlow());
+
+    let boundQuit = this.quit.bind(this);
+
+    /** @override */
+    this.quit = function() {
+      return boundQuit().thenFinally(service.kill.bind(service));
+    };
+  }
 
-/**
- * This function is a no-op as file detectors are not supported by this
- * implementation.
- * @override
- */
-Driver.prototype.setFileDetector = function() {
-};
+  /**
+   * This function is a no-op as file detectors are not supported by this
+   * implementation.
+   * @override
+   */
+  setFileDetector() {}
+}
 
 
 // PUBLIC API