selenium-webdriver 3.5.0 → 4.0.0-alpha.4

package/http/index.js

@@ -59,6 +59,15 @@ function getRequestOptions(aUrl) {
 }
 
 
+/** @const {string} */
+const USER_AGENT = (function() {
+  const version = require('../package.json').version;
+  const platform =
+      ({'darwin': 'mac', 'win32': 'windows'}[process.platform]) || 'linux';
+  return `selenium/${version} (js ${platform})`;
+})();
+
+
 /**
  * A basic HTTP client used to send messages to a remote end.
  *
@@ -93,10 +102,14 @@ class HttpClient {
     let data;
 
     let headers = {};
-    httpRequest.headers.forEach(function(value, name) {
-      headers[name] = value;
-    });
 
+    if (httpRequest.headers) {
+      httpRequest.headers.forEach(function(value, name) {
+        headers[name] = value;
+      });
+    }
+
+    headers['User-Agent'] = USER_AGENT;
     headers['Content-Length'] = 0;
     if (httpRequest.method == 'POST' || httpRequest.method == 'PUT') {
       data = JSON.stringify(httpRequest.data);
@@ -144,8 +157,9 @@ class HttpClient {
  * @param {function(!Error)} onError The function to call if the request fails.
  * @param {?string=} opt_data The data to send with the request.
  * @param {?RequestOptions=} opt_proxy The proxy server to use for the request.
+ * @param {number=} opt_retries The current number of retries.
  */
-function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
+function sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries) {
   var hostname = options.hostname;
   var port = options.port;
 
@@ -161,7 +175,7 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
     // An HTTP/1.1 proxy MUST ensure that any request message it forwards does
     // contain an appropriate Host header field that identifies the service
     // being requested by the proxy.
-    let targetHost = options.hostname
+    let targetHost = options.hostname;
     if (options.port) {
       targetHost += ':' + options.port;
     }
@@ -208,7 +222,8 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
         search: location.search,
         hash: location.hash,
         headers: {
-          'Accept': 'application/json; charset=utf-8'
+          'Accept': 'application/json; charset=utf-8',
+          'User-Agent': USER_AGENT,
         }
       }, onOk, onError, undefined, opt_proxy);
       return;
@@ -220,15 +235,20 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
       var resp = new httpLib.Response(
           /** @type {number} */(response.statusCode),
           /** @type {!Object<string>} */(response.headers),
-          body.join('').replace(/\0/g, ''));
+          Buffer.concat(body).toString('utf8').replace(/\0/g, ''));
       onOk(resp);
     });
   });
 
   request.on('error', function(e) {
-    if (e.code === 'ECONNRESET') {
+    if (typeof opt_retries === 'undefined') {
+      opt_retries = 0;
+    }
+
+    if (shouldRetryRequest(opt_retries, e)) {
+      opt_retries += 1;
       setTimeout(function() {
-        sendRequest(options, onOk, onError, opt_data, opt_proxy);
+        sendRequest(options, onOk, onError, opt_data, opt_proxy, opt_retries);
       }, 15);
     } else {
       var message = e.message;
@@ -247,8 +267,41 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
 }
 
 
+const MAX_RETRIES = 3;
+
+/**
+ * A retry is sometimes needed on Windows where we may quickly run out of
+ * ephemeral ports. A more robust solution is bumping the MaxUserPort setting
+ * as described here: http://msdn.microsoft.com/en-us/library/aa560610%28v=bts.20%29.aspx
+ *
+ * @param {!number} retries
+ * @param {!Error} err
+ * @return {boolean}
+ */
+function shouldRetryRequest(retries, err) {
+  return retries < MAX_RETRIES && isRetryableNetworkError(err);
+}
+
+/**
+ * @param {!Error} err
+ * @return {boolean}
+ */
+function isRetryableNetworkError(err) {
+  if (err && err.code) {
+    return err.code === 'ECONNABORTED' ||
+          err.code === 'ECONNRESET' ||
+          err.code === 'ECONNREFUSED' ||
+          err.code === 'EADDRINUSE' ||
+          err.code === 'EPIPE';
+  }
+
+  return false;
+}
+
+
 // PUBLIC API
 
+exports.Agent = http.Agent;
 exports.Executor = httpLib.Executor;
 exports.HttpClient = HttpClient;
 exports.Request = httpLib.Request;

package/http/util.js

@@ -26,8 +26,7 @@ const Executor = require('./index').Executor,
     HttpRequest = require('./index').Request,
     Command = require('../lib/command').Command,
     CommandName = require('../lib/command').Name,
-    error = require('../lib/error'),
-    promise = require('../lib/promise');
+    error = require('../lib/error');
 
 
 
@@ -45,6 +44,9 @@ function getStatus(url) {
 }
 
 
+class CancellationError {}
+
+
 // PUBLIC API
 
 
@@ -57,13 +59,16 @@ function getStatus(url) {
 exports.getStatus = getStatus;
 
 
+exports.CancellationError = CancellationError;
+
+
 /**
  * Waits for a WebDriver server to be healthy and accepting requests.
  * @param {string} url Base URL of the server to query.
  * @param {number} timeout How long to wait for the server.
  * @param {Promise=} opt_cancelToken A promise used as a cancellation signal:
  *     if resolved before the server is ready, the wait will be terminated
- *     early with a {@link promise.CancellationError}.
+ *     early with a {@link CancellationError}.
  * @return {!Promise} A promise that will resolve when the server is ready, or
  *     if the wait is cancelled.
  */
@@ -82,7 +87,7 @@ exports.waitForServer = function(url, timeout, opt_cancelToken) {
     };
 
     if (opt_cancelToken) {
-      opt_cancelToken.then(_ => reject(new promise.CancellationError));
+      opt_cancelToken.then(_ => reject(new CancellationError));
     }
 
     checkServerStatus();
@@ -119,7 +124,7 @@ exports.waitForServer = function(url, timeout, opt_cancelToken) {
  * @param {number} timeout How long to wait, in milliseconds.
  * @param {Promise=} opt_cancelToken A promise used as a cancellation signal:
  *     if resolved before the a 2xx response is received, the wait will be
- *     terminated early with a {@link promise.CancellationError}.
+ *     terminated early with a {@link CancellationError}.
  * @return {!Promise} A promise that will resolve when a 2xx is received from
  *     the given URL, or if the wait is cancelled.
  */
@@ -140,7 +145,7 @@ exports.waitForUrl = function(url, timeout, opt_cancelToken) {
     };
 
     if (opt_cancelToken) {
-      opt_cancelToken.then(_ => reject(new promise.CancellationError));
+      opt_cancelToken.then(_ => reject(new CancellationError));
     }
 
     testUrl();

package/ie.js

@@ -27,16 +27,16 @@
 
 'use strict';
 
-const fs = require('fs'),
-    util = require('util');
+const fs = require('fs');
+const util = require('util');
 
-const http = require('./http'),
-    io = require('./io'),
-    capabilities = require('./lib/capabilities'),
-    promise = require('./lib/promise'),
-    webdriver = require('./lib/webdriver'),
-    portprober = require('./net/portprober'),
-    remote = require('./remote');
+const http = require('./http');
+const io = require('./io');
+const portprober = require('./net/portprober');
+const promise = require('./lib/promise');
+const remote = require('./remote');
+const webdriver = require('./lib/webdriver');
+const {Browser, Capabilities, Capability} = require('./lib/capabilities');
 
 
 const IEDRIVER_EXE = 'IEDriverServer.exe';
@@ -86,37 +86,14 @@ const Key = {
 /**
  * Class for managing IEDriver specific options.
  */
-class Options {
-  constructor() {
-    /** @private {!Object<(boolean|number|string|!Array<string>)>} */
-    this.options_ = {};
-
-    /** @private {(capabilities.ProxyConfig|null)} */
-    this.proxy_ = null;
-  }
-
+class Options extends Capabilities {
   /**
-   * Extracts the IEDriver specific options from the given capabilities
-   * object.
-   * @param {!capabilities.Capabilities} caps The capabilities object.
-   * @return {!Options} The IEDriver options.
+   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
+   *     capabilities to initialize this instance from.
    */
-  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));
-    }
-
-    return options;
+  constructor(other = undefined) {
+    super(other);
+    this.setBrowserName(Browser.IE);
   }
 
   /**
@@ -132,7 +109,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   introduceFlakinessByIgnoringProtectedModeSettings(ignoreSettings) {
-    this.options_[Key.IGNORE_PROTECTED_MODE_SETTINGS] = !!ignoreSettings;
+    this.set(Key.IGNORE_PROTECTED_MODE_SETTINGS, !!ignoreSettings);
     return this;
   }
 
@@ -144,7 +121,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   ignoreZoomSetting(ignore) {
-    this.options_[Key.IGNORE_ZOOM_SETTING] = !!ignore;
+    this.set(Key.IGNORE_ZOOM_SETTING, !!ignore);
     return this;
   }
 
@@ -159,7 +136,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   initialBrowserUrl(url) {
-    this.options_[Key.INITIAL_BROWSER_URL] = url;
+    this.set(Key.INITIAL_BROWSER_URL, url);
     return this;
   }
 
@@ -172,7 +149,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   enablePersistentHover(enable) {
-    this.options_[Key.ENABLE_PERSISTENT_HOVER] = !!enable;
+    this.set(Key.ENABLE_PERSISTENT_HOVER, !!enable);
     return this;
   }
 
@@ -186,7 +163,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   enableElementCacheCleanup(enable) {
-    this.options_[Key.ENABLE_ELEMENT_CACHE_CLEANUP] = !!enable;
+    this.set(Key.ENABLE_ELEMENT_CACHE_CLEANUP, !!enable);
     return this;
   }
 
@@ -200,7 +177,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   requireWindowFocus(require) {
-    this.options_[Key.REQUIRE_WINDOW_FOCUS] = !!require;
+    this.set(Key.REQUIRE_WINDOW_FOCUS, !!require);
     return this;
   }
 
@@ -213,7 +190,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   browserAttachTimeout(timeout) {
-    this.options_[Key.BROWSER_ATTACH_TIMEOUT] = Math.max(timeout, 0);
+    this.set(Key.BROWSER_ATTACH_TIMEOUT, Math.max(timeout, 0));
     return this;
   }
 
@@ -227,7 +204,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   forceCreateProcessApi(force) {
-    this.options_[Key.FORCE_CREATE_PROCESS] = !!force;
+    this.set(Key.FORCE_CREATE_PROCESS, !!force);
     return this;
   }
 
@@ -235,13 +212,14 @@ class Options {
    * 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.
+   * @param {...(string|!Array.<string>)} 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;
+  addArguments(...args) {
+    let current = this.get(Key.BROWSER_COMMAND_LINE_SWITCHES) || [];
+    this.set(
+        Key.BROWSER_COMMAND_LINE_SWITCHES,
+        current.concat.apply(current, args));
     return this;
   }
 
@@ -254,7 +232,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   usePerProcessProxy(enable) {
-    this.options_[Key.USE_PER_PROCESS_PROXY] = !!enable;
+    this.set(Key.USE_PER_PROCESS_PROXY, !!enable);
     return this;
   }
 
@@ -268,7 +246,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   ensureCleanSession(cleanSession) {
-    this.options_[Key.ENSURE_CLEAN_SESSION] = !!cleanSession;
+    this.set(Key.ENSURE_CLEAN_SESSION, !!cleanSession);
     return this;
   }
 
@@ -278,7 +256,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   setLogFile(file) {
-    this.options_[Key.LOG_FILE] = file;
+    this.set(Key.LOG_FILE, file);
     return this;
   }
 
@@ -288,7 +266,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   setLogLevel(level) {
-    this.options_[Key.LOG_LEVEL] = level;
+    this.set(Key.LOG_LEVEL, level);
     return this;
   }
 
@@ -298,7 +276,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   setHost(host) {
-    this.options_[Key.HOST] = host;
+    this.set(Key.HOST, host);
     return this;
   }
 
@@ -308,7 +286,7 @@ class Options {
    * @return {!Options} A self reference.
    */
   setExtractPath(path) {
-    this.options_[Key.EXTRACT_PATH] = path;
+    this.set(Key.EXTRACT_PATH, path);
     return this;
   }
 
@@ -318,37 +296,21 @@ class Options {
    * @return {!Options} A self reference.
    */
   silent(silent) {
-    this.options_[Key.SILENT] = silent;
+    this.set(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 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;
-  }
+/**
+ * _Synchronously_ attempts to locate the IE driver executable on the current
+ * system.
+ *
+ * @return {?string} the located executable, or `null`.
+ */
+function locateSynchronously() {
+  return process.platform === 'win32'
+      ? io.findInPath(IEDRIVER_EXE, true) : null;
 }
 
 
@@ -360,7 +322,7 @@ function createServiceFromCapabilities(capabilities) {
         'WebDriver server?');
   }
 
-  let exe = io.findInPath(IEDRIVER_EXE, true);
+  let exe = locateSynchronously();
   if (!exe || !fs.existsSync(exe)) {
     throw Error(
         `${IEDRIVER_EXE} could not be found on the current PATH. Please ` +
@@ -398,6 +360,23 @@ function createServiceFromCapabilities(capabilities) {
 }
 
 
+/**
+ * Creates {@link selenium-webdriver/remote.DriverService} instances that manage
+ * an [IEDriverServer](https://github.com/SeleniumHQ/selenium/wiki/InternetExplorerDriver)
+ * server in a child process.
+ */
+class ServiceBuilder extends remote.DriverService.Builder {
+  /**
+   * @param {string=} opt_exe Path to the server executable to use. If omitted,
+   *     the builder will attempt to locate the IEDriverServer on the system PATH.
+   */
+  constructor(opt_exe) {
+    super(opt_exe || IEDRIVER_EXE);
+    this.setLoopback(true);  // Required.
+  }
+}
+
+
 /**
  * A WebDriver client for Microsoft's Internet Explorer.
  */
@@ -405,23 +384,27 @@ class Driver extends webdriver.WebDriver {
   /**
    * Creates a new session for Microsoft's Internet Explorer.
    *
-   * @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.
+   * @param {(Capabilities|Options)=} options The configuration options.
+   * @param {(remote.DriverService)=} opt_service The `DriverService` to use
+   *   to start the IEDriverServer in a child process, optionally.
    * @return {!Driver} A new driver instance.
    */
-  static createSession(opt_config, opt_flow) {
-    var caps = opt_config instanceof Options ?
-        opt_config.toCapabilities() :
-        (opt_config || capabilities.Capabilities.ie());
+  static createSession(options, opt_service) {
+    options = options || new Options();
 
-    var service = createServiceFromCapabilities(caps);
-    var client = service.start().then(url => new http.HttpClient(url));
-    var executor = new http.Executor(client);
+    let service;
+
+    if (opt_service instanceof remote.DriverService) {
+      service = opt_service;
+    } else {
+      service = createServiceFromCapabilities(options);
+    }
+
+    let client = service.start().then(url => new http.HttpClient(url));
+    let executor = new http.Executor(client);
 
     return /** @type {!Driver} */(super.createSession(
-        executor, caps, opt_flow, () => service.kill()));
+        executor, options, () => service.kill()));
   }
 
   /**
@@ -439,3 +422,6 @@ class Driver extends webdriver.WebDriver {
 exports.Driver = Driver;
 exports.Options = Options;
 exports.Level = Level;
+exports.ServiceBuilder = ServiceBuilder;
+exports.locateSynchronously = locateSynchronously;
+