selenium-webdriver 3.0.0-beta-1 → 3.0.1

package/opera.js

@@ -98,7 +98,7 @@ const OPERADRIVER_EXE =
  * [OperaDriver](https://github.com/operasoftware/operachromiumdriver)
  * server in a child process.
  */
-class ServiceBuilder {
+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 operadriver on the current
@@ -116,39 +116,8 @@ class ServiceBuilder {
           'ensure it can be found on your PATH.');
     }
 
-    /** @private {string} */
-    this.exe_ = /** @type {string} */(exe);
-    if (!fs.existsSync(this.exe_)) {
-      throw Error('File does not exist: ' + this.exe_);
-    }
-
-    /** @private {!Array.<string>} */
-    this.args_ = [];
-
-    /** @private {number} */
-    this.port_ = 0;
-
-    /**
-     * @private {(string|!Array<string|number|!stream.Stream|null|undefined>)}
-     */
-    this.stdio_ = 'ignore';
-
-    /** @private {Object.<string, string>} */
-    this.env_ = null;
-  }
-
-  /**
-   * Sets the port to start the OperaDriver on.
-   * @param {number} port The port to use, or 0 for any free port.
-   * @return {!ServiceBuilder} A self reference.
-   * @throws {Error} If the port is invalid.
-   */
-  usingPort(port) {
-    if (port < 0) {
-      throw Error('port must be >= 0: ' + port);
-    }
-    this.port_ = port;
-    return this;
+    super(exe);
+    this.setLoopback(true);
   }
 
   /**
@@ -158,8 +127,7 @@ class ServiceBuilder {
    * @return {!ServiceBuilder} A self reference.
    */
   loggingTo(path) {
-    this.args_.push('--log-path=' + path);
-    return this;
+    return this.addArguments('--log-path=' + path);
   }
 
   /**
@@ -167,8 +135,7 @@ class ServiceBuilder {
    * @return {!ServiceBuilder} A self reference.
    */
   enableVerboseLogging() {
-    this.args_.push('--verbose');
-    return this;
+    return this.addArguments('--verbose');
   }
 
   /**
@@ -176,54 +143,8 @@ class ServiceBuilder {
    * @return {!ServiceBuilder} A self reference.
    */
   silent() {
-    this.args_.push('--silent');
-    return this;
+    return this.addArguments('--silent');
   }
-
-  /**
-   * Defines the stdio configuration for the driver service. See
-   * {@code child_process.spawn} for more information.
-   * @param {(string|!Array<string|number|!stream.Stream|null|undefined>)}
-   *     config The configuration to use.
-   * @return {!ServiceBuilder} A self reference.
-   */
-  setStdio(config) {
-    this.stdio_ = config;
-    return this;
-  }
-
-  /**
-   * Defines the environment to start the server under. This settings will be
-   * inherited by every browser session started by the server.
-   * @param {!Object.<string, string>} env The environment to use.
-   * @return {!ServiceBuilder} A self reference.
-   */
-  withEnvironment(env) {
-    this.env_ = env;
-    return this;
-  }
-
-  /**
-   * Creates a new DriverService using this instance's current configuration.
-   * @return {!remote.DriverService} A new driver service using this instance's
-   *     current configuration.
-   * @throws {Error} If the driver exectuable was not specified and a default
-   *     could not be found on the current PATH.
-   */
-  build() {
-    var port = this.port_ || portprober.findFreePort();
-    var args = this.args_.concat();  // Defensive copy.
-
-    return new remote.DriverService(this.exe_, {
-      loopback: true,
-      port: port,
-      args: Promise.resolve(port).then(function(port) {
-        return args.concat('--port=' + port);
-      }),
-      env: this.env_,
-      stdio: this.stdio_
-    });
-  };
 }
 
 
@@ -427,14 +348,17 @@ class Options {
  */
 class Driver extends webdriver.WebDriver {
   /**
+   * Creates a new session for Opera.
+   *
    * @param {(capabilities.Capabilities|Options)=} opt_config The configuration
    *     options.
    * @param {remote.DriverService=} opt_service The session to use; will use
    *     the {@link getDefaultService default service} by default.
    * @param {promise.ControlFlow=} opt_flow The control flow to use,
    *     or {@code null} to use the currently active flow.
+   * @return {!Driver} A new driver instance.
    */
-  constructor(opt_config, opt_service, opt_flow) {
+  static createSession(opt_config, opt_service, opt_flow) {
     var service = opt_service || getDefaultService();
     var client = service.start().then(url => new http.HttpClient(url));
     var executor = new http.Executor(client);
@@ -458,8 +382,8 @@ class Driver extends webdriver.WebDriver {
       caps = options.toCapabilities(caps);
     }
 
-    var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
-    super(driver.getSession(), executor, driver.controlFlow());
+    return /** @type {!Driver} */(
+        webdriver.WebDriver.createSession(executor, caps, opt_flow, this));
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selenium-webdriver",
-  "version": "3.0.0-beta-1",
+  "version": "3.0.1",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -20,24 +20,23 @@
     "url": "https://github.com/SeleniumHQ/selenium.git"
   },
   "engines": {
-    "node": ">= 4.2.x"
+    "node": ">= 6.9.0"
   },
   "dependencies": {
-    "adm-zip": "0.4.4",
-    "rimraf": "^2.2.8",
-    "tmp": "0.0.24",
-    "ws": "^1.0.1",
-    "xml2js": "0.4.4"
+    "adm-zip": "^0.4.7",
+    "rimraf": "^2.5.4",
+    "tmp": "0.0.30",
+    "xml2js": "^0.4.17"
   },
   "devDependencies": {
-    "express": "^4.11.2",
-    "mocha": ">= 1.21.x",
-    "multer": "^0.1.7",
-    "promises-aplus-tests": "^2.1.0",
-    "serve-index": "^1.6.1",
-    "sinon": "^1.17.2"
+    "express": "^4.14.0",
+    "mocha": "^3.1.2",
+    "multer": "^1.2.0",
+    "promises-aplus-tests": "^2.1.2",
+    "serve-index": "^1.8.0",
+    "sinon": "^1.17.6"
   },
   "scripts": {
-    "test": "mocha --harmony -t 600000 --recursive test"
+    "test": "mocha -t 600000 --recursive test"
   }
 }

package/phantomjs.js

@@ -148,6 +148,8 @@ function createExecutor(url) {
  */
 class Driver extends webdriver.WebDriver {
   /**
+   * Creates a new PhantomJS session.
+   *
    * @param {capabilities.Capabilities=} opt_capabilities The desired
    *     capabilities.
    * @param {promise.ControlFlow=} opt_flow The control flow to use,
@@ -155,8 +157,9 @@ class Driver extends webdriver.WebDriver {
    * @param {string=} opt_logFile Path to the log file for the phantomjs
    *     executable's output. For convenience, this may be set at runtime with
    *     the `SELENIUM_PHANTOMJS_LOG` environment variable.
+   * @return {!Driver} A new driver reference.
    */
-  constructor(opt_capabilities, opt_flow, opt_logFile) {
+  static createSession(opt_capabilities, opt_flow, opt_logFile) {
     // TODO: add an Options class for consistency with the other driver types.
 
     var caps = opt_capabilities || capabilities.Capabilities.phantomjs();
@@ -207,7 +210,6 @@ class Driver extends webdriver.WebDriver {
     var port = portprober.findFreePort();
     var service = new remote.DriverService(exe, {
       port: port,
-      stdio: 'inherit',
       args: Promise.resolve(port).then(function(port) {
         args.push('--webdriver=' + port);
         return args;
@@ -215,17 +217,8 @@ class Driver extends webdriver.WebDriver {
     });
 
     var executor = createExecutor(service.start());
-    var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
-
-    super(driver.getSession(), executor, driver.controlFlow());
-
-    var boundQuit = this.quit.bind(this);
-
-    /** @override */
-    this.quit = function() {
-      let killService = () => service.kill();
-      return boundQuit().then(killService, killService);
-    };
+    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
+        executor, caps, opt_flow, this, () => service.kill()));
   }
 
   /**
@@ -265,7 +258,7 @@ class Driver extends webdriver.WebDriver {
    *
    * @param {(string|!Function)} script The script to execute.
    * @param {...*} var_args The arguments to pass to the script.
-   * @return {!promise.Promise<T>} A promise that resolve to the
+   * @return {!promise.Thenable<T>} A promise that resolve to the
    *     script's return value.
    * @template T
    */

package/remote/index.js

@@ -17,22 +17,33 @@
 
 'use strict';
 
-const AdmZip = require('adm-zip'),
-    fs = require('fs'),
-    path = require('path'),
-    url = require('url'),
-    util = require('util');
+const AdmZip = require('adm-zip');
+const fs = require('fs');
+const path = require('path');
+const url = require('url');
+const util = require('util');
+
+const httpUtil = require('../http/util');
+const io = require('../io');
+const exec = require('../io/exec');
+const cmd = require('../lib/command');
+const input = require('../lib/input');
+const promise = require('../lib/promise');
+const webdriver = require('../lib/webdriver');
+const net = require('../net');
+const portprober = require('../net/portprober');
 
-const httpUtil = require('../http/util'),
-    io = require('../io'),
-    exec = require('../io/exec'),
-    cmd = require('../lib/command'),
-    input = require('../lib/input'),
-    promise = require('../lib/promise'),
-    webdriver = require('../lib/webdriver'),
-    net = require('../net'),
-    portprober = require('../net/portprober');
 
+/**
+ * @typedef {(string|!Array<string|number|!stream.Stream|null|undefined>)}
+ */
+var StdIoOptions;
+
+
+/**
+ * @typedef {(string|!IThenable<string>)}
+ */
+var CommandLineFlag;
 
 
 /**
@@ -70,7 +81,7 @@ ServiceOptions.prototype.port;
  * The arguments to pass to the service. If a promise is provided, the service
  * will wait for it to resolve before starting.
  *
- * @type {!(Array<string>|IThenable<!Array<string>>)}
+ * @type {!(Array<CommandLineFlag>|IThenable<!Array<CommandLineFlag>>)}
  */
 ServiceOptions.prototype.args;
 
@@ -94,8 +105,7 @@ ServiceOptions.prototype.env;
  * IO configuration for the spawned server process. For more information, refer
  * to the documentation of `child_process.spawn`.
  *
- * @type {(string|!Array<string|number|!stream.Stream|null|undefined>|
- *         undefined)}
+ * @type {(StdIoOptions|undefined)}
  * @see https://nodejs.org/dist/latest-v4.x/docs/api/child_process.html#child_process_options_stdio
  */
 ServiceOptions.prototype.stdio;
@@ -128,7 +138,8 @@ class DriverService {
     this.port_ = options.port;
 
     /**
-     * @private {!(Array<string>|IThenable<!Array<string>>)}
+     * @private {!(Array<CommandLineFlag>|
+     *             IThenable<!Array<CommandLineFlag>>)}
      */
     this.args_ = options.args;
 
@@ -199,11 +210,12 @@ class DriverService {
     this.command_ = new Promise(resolve => resolveCommand = resolve);
 
     this.address_ = new Promise((resolveAddress, rejectAddress) => {
-      resolveAddress(Promise.resolve(this.port_).then(function(port) {
+      resolveAddress(Promise.resolve(this.port_).then(port => {
         if (port <= 0) {
           throw Error('Port must be > 0: ' + port);
         }
-        return Promise.resolve(self.args_).then(function(args) {
+
+        return resolveCommandLineFlags(this.args_).then(args => {
           var command = exec(self.executable_, {
             args: args,
             env: self.env_,
@@ -235,15 +247,18 @@ class DriverService {
             pathname: self.path_
           });
 
-          return new Promise(function(fulfill, reject) {
-            var ready = httpUtil.waitForServer(serverUrl, timeout)
-                .then(fulfill, reject);
-            earlyTermination.catch(function(e) {
-              ready.cancel(/** @type {Error} */(e));
-              reject(Error(e.message));
-            });
-          }).then(function() {
-            return serverUrl;
+          return new Promise((fulfill, reject) => {
+            let cancelToken =
+                earlyTermination.catch(e => reject(Error(e.message)));
+
+            httpUtil.waitForServer(serverUrl, timeout, cancelToken)
+                .then(_ => fulfill(serverUrl), err => {
+                  if (err instanceof promise.CancellationError) {
+                    fulfill(serverUrl);
+                  } else {
+                    reject(err);
+                  }
+                });
           });
         });
       }));
@@ -271,7 +286,7 @@ class DriverService {
   /**
    * Schedules a task in the current control flow to stop the server if it is
    * currently running.
-   * @return {!promise.Promise} A promise that will be resolved when
+   * @return {!promise.Thenable} A promise that will be resolved when
    *     the server has been stopped.
    */
   stop() {
@@ -280,6 +295,17 @@ class DriverService {
 }
 
 
+/**
+ * @param {!(Array<CommandLineFlag>|IThenable<!Array<CommandLineFlag>>)} args
+ * @return {!Promise<!Array<string>>}
+ */
+function resolveCommandLineFlags(args) {
+  // Resolve the outer array, then the individual flags.
+  return Promise.resolve(args)
+      .then(/** !Array<CommandLineFlag> */args => Promise.all(args));
+}
+
+
 /**
  * The default amount of time, in milliseconds, to wait for the server to
  * start.
@@ -288,6 +314,151 @@ class DriverService {
 DriverService.DEFAULT_START_TIMEOUT_MS = 30 * 1000;
 
 
+/**
+ * Creates {@link DriverService} objects that manage a WebDriver server in a
+ * child process.
+ */
+DriverService.Builder = class {
+  /**
+   * @param {string} exe Path to the executable to use. This executable must
+   *     accept the `--port` flag for defining the port to start the server on.
+   * @throws {Error} If the provided executable path does not exist.
+   */
+  constructor(exe) {
+    if (!fs.existsSync(exe)) {
+      throw Error(`The specified executable path does not exist: ${exe}`);
+    }
+
+    /** @private @const {string} */
+    this.exe_ = exe;
+
+    /** @private {!ServiceOptions} */
+    this.options_ = {
+      args: [],
+      port: 0,
+      env: null,
+      stdio: 'ignore'
+    };
+  }
+
+  /**
+   * Define additional command line arguments to use when starting the server.
+   *
+   * @param {...CommandLineFlag} var_args The arguments to include.
+   * @return {!THIS} A self reference.
+   * @this {THIS}
+   * @template THIS
+   */
+  addArguments(var_args) {
+    let args = Array.prototype.slice.call(arguments, 0);
+    this.options_.args = this.options_.args.concat(args);
+    return this;
+  }
+
+  /**
+   * Sets the host name to access the server on. If specified, the
+   * {@linkplain #setLoopback() loopback} setting will be ignored.
+   *
+   * @param {string} hostname
+   * @return {!DriverService.Builder} A self reference.
+   */
+  setHostname(hostname) {
+    this.options_.hostname = hostname;
+    return this;
+  }
+
+  /**
+   * Sets whether the service should be accessed at this host's loopback
+   * address.
+   *
+   * @param {boolean} loopback
+   * @return {!DriverService.Builder} A self reference.
+   */
+  setLoopback(loopback) {
+    this.options_.loopback = loopback;
+    return this;
+  }
+
+  /**
+   * Sets the base path for WebDriver REST commands (e.g. "/wd/hub").
+   * By default, the driver will accept commands relative to "/".
+   *
+   * @param {?string} basePath The base path to use, or `null` to use the
+   *     default.
+   * @return {!DriverService.Builder} A self reference.
+   */
+  setPath(basePath) {
+    this.options_.path = basePath;
+    return this;
+  }
+
+  /**
+   * Sets the port to start the server on.
+   *
+   * @param {number} port The port to use, or 0 for any free port.
+   * @return {!DriverService.Builder} A self reference.
+   * @throws {Error} If an invalid port is specified.
+   */
+  setPort(port) {
+    if (port < 0) {
+      throw Error(`port must be >= 0: ${port}`);
+    }
+    this.options_.port = port;
+    return this;
+  }
+
+  /**
+   * Defines the environment to start the server under. This setting will be
+   * inherited by every browser session started by the server. By default, the
+   * server will inherit the enviroment of the current process.
+   *
+   * @param {(Map<string, string>|Object<string, string>|null)} env The desired
+   *     environment to use, or `null` if the server should inherit the
+   *     current environment.
+   * @return {!DriverService.Builder} A self reference.
+   */
+  setEnvironment(env) {
+    if (env instanceof Map) {
+      let tmp = {};
+      env.forEach((value, key) => tmp[key] = value);
+      env = tmp;
+    }
+    this.options_.env = env;
+    return this;
+  }
+
+  /**
+   * IO configuration for the spawned server process. For more information,
+   * refer to the documentation of `child_process.spawn`.
+   *
+   * @param {StdIoOptions} config The desired IO configuration.
+   * @return {!DriverService.Builder} A self reference.
+   * @see https://nodejs.org/dist/latest-v4.x/docs/api/child_process.html#child_process_options_stdio
+   */
+  setStdio(config) {
+    this.options_.stdio = config;
+    return this;
+  }
+
+  /**
+   * Creates a new DriverService using this instance's current configuration.
+   *
+   * @return {!DriverService} A new driver service.
+   */
+  build() {
+    let port = this.options_.port || portprober.findFreePort();
+    let args = Promise.resolve(port).then(port => {
+      return this.options_.args.concat('--port=' + port);
+    });
+
+    let options =
+        /** @type {!ServiceOptions} */
+        (Object.assign({}, this.options_, {args, port}));
+    return new DriverService(this.exe_, options);
+  }
+};
+
+
 /**
  * Manages the life and death of the
  * <a href="http://selenium-release.storage.googleapis.com/index.html">