selenium-webdriver 3.5.0 → 4.0.0-alpha.4

package/index.js

@@ -22,27 +22,23 @@
 
 'use strict';
 
-const chrome = require('./chrome');
-const edge = require('./edge');
-const firefox = require('./firefox');
 const _http = require('./http');
-const ie = require('./ie');
-const actions = require('./lib/actions');
 const by = require('./lib/by');
 const capabilities = require('./lib/capabilities');
+const chrome = require('./chrome');
 const command = require('./lib/command');
+const edge = require('./edge');
 const error = require('./lib/error');
-const events = require('./lib/events');
+const firefox = require('./firefox');
+const ie = require('./ie');
 const input = require('./lib/input');
 const logging = require('./lib/logging');
 const promise = require('./lib/promise');
+const remote = require('./remote');
+const safari = require('./safari');
 const session = require('./lib/session');
 const until = require('./lib/until');
 const webdriver = require('./lib/webdriver');
-const opera = require('./opera');
-const phantomjs = require('./phantomjs');
-const remote = require('./remote');
-const safari = require('./safari');
 
 const Browser = capabilities.Browser;
 const Capabilities = capabilities.Capabilities;
@@ -107,7 +103,7 @@ function ensureFileDetectorsAreEnabled(ctor) {
  * every issued command will fail.
  *
  * @extends {webdriver.IWebDriver}
- * @extends {promise.CancellableThenable<!webdriver.IWebDriver>}
+ * @extends {IThenable<!webdriver.IWebDriver>}
  * @interface
  */
 class ThenableWebDriver {
@@ -147,24 +143,13 @@ function createDriver(ctor, ...args) {
           return new ctor(session, ...rest);
         });
 
-        /**
-         * @param {(string|Error)=} opt_reason
-         * @override
-         */
-        this.cancel = function(opt_reason) {
-          if (promise.CancellableThenable.isImplementation(pd)) {
-            /** @type {!promise.CancellableThenable} */(pd).cancel(opt_reason);
-          }
-        };
-
         /** @override */
         this.then = pd.then.bind(pd);
 
         /** @override */
-        this.catch = pd.then.bind(pd);
+        this.catch = pd.catch.bind(pd);
       }
     };
-    promise.CancellableThenable.addImplementation(thenableWebDriverProxy);
     THENABLE_DRIVERS.set(ctor, thenableWebDriverProxy);
   }
   return thenableWebDriverProxy.createSession(...args);
@@ -215,9 +200,6 @@ class Builder {
     /** @private @const */
     this.log_ = logging.getLogger('webdriver.Builder');
 
-    /** @private {promise.ControlFlow} */
-    this.flow_ = null;
-
     /** @private {string} */
     this.url_ = '';
 
@@ -230,14 +212,20 @@ class Builder {
     /** @private {chrome.Options} */
     this.chromeOptions_ = null;
 
+    /** @private {chrome.ServiceBuilder} */
+    this.chromeService_ = null;
+
     /** @private {firefox.Options} */
     this.firefoxOptions_ = null;
 
-    /** @private {opera.Options} */
-    this.operaOptions_ = null;
+    /** @private {firefox.ServiceBuilder} */
+    this.firefoxService_ = null;
 
     /** @private {ie.Options} */
     this.ieOptions_ = null;
+  
+    /** @private {ie.ServiceBuilder} */
+    this.ieService_ = null;
 
     /** @private {safari.Options} */
     this.safariOptions_ = null;
@@ -245,6 +233,9 @@ class Builder {
     /** @private {edge.Options} */
     this.edgeOptions_ = null;
 
+    /** @private {remote.DriverService.Builder} */
+    this.edgeService_ = null;
+
     /** @private {boolean} */
     this.ignoreEnv_ = false;
 
@@ -358,18 +349,22 @@ class Builder {
    * environment variable. If set, this environment variable should be of the
    * form `browser[:[version][:platform]]`.
    *
-   * @param {(string|Browser)} name The name of the target browser;
+   * @param {(string|!Browser)} name The name of the target browser;
    *     common defaults are available on the {@link webdriver.Browser} enum.
    * @param {string=} opt_version A desired version; may be omitted if any
    *     version should be used.
-   * @param {string=} opt_platform The desired platform; may be omitted if any
-   *     version may be used.
+   * @param {(string|!capabilities.Platform)=} opt_platform
+   *     The desired platform; may be omitted if any platform may be used.
    * @return {!Builder} A self reference.
    */
   forBrowser(name, opt_version, opt_platform) {
-    this.capabilities_.set(Capability.BROWSER_NAME, name);
-    this.capabilities_.set(Capability.VERSION, opt_version || null);
-    this.capabilities_.set(Capability.PLATFORM, opt_platform || null);
+    this.capabilities_.setBrowserName(name);
+    if (opt_version) {
+      this.capabilities_.setBrowserVersion(opt_version);
+    }
+    if (opt_platform) {
+      this.capabilities_.setPlatform(opt_platform);
+    }
     return this;
   }
 
@@ -378,7 +373,7 @@ class Builder {
    * Any calls to {@link #withCapabilities} after this function will
    * overwrite these settings.
    *
-   * @param {!capabilities.ProxyConfig} config The configuration to use.
+   * @param {!./lib/proxy.Config} config The configuration to use.
    * @return {!Builder} A self reference.
    */
   setProxy(config) {
@@ -398,33 +393,13 @@ class Builder {
     return this;
   }
 
-  /**
-   * Sets whether native events should be used.
-   * @param {boolean} enabled Whether to enable native events.
-   * @return {!Builder} A self reference.
-   */
-  setEnableNativeEvents(enabled) {
-    this.capabilities_.setEnableNativeEvents(enabled);
-    return this;
-  }
-
-  /**
-   * Sets how elements should be scrolled into view for interaction.
-   * @param {number} behavior The desired scroll behavior: either 0 to align
-   *     with the top of the viewport or 1 to align with the bottom.
-   * @return {!Builder} A self reference.
-   */
-  setScrollBehavior(behavior) {
-    this.capabilities_.setScrollBehavior(behavior);
-    return this;
-  }
-
   /**
    * Sets the default action to take with an unexpected alert before returning
    * an error.
-   * @param {string} behavior The desired behavior; should be "accept",
-   *     "dismiss", or "ignore". Defaults to "dismiss".
+   *
+   * @param {?capabilities.UserPromptHandler} behavior The desired behavior.
    * @return {!Builder} A self reference.
+   * @see capabilities.Capabilities#setAlertBehavior
    */
   setAlertBehavior(behavior) {
     this.capabilities_.setAlertBehavior(behavior);
@@ -445,6 +420,29 @@ class Builder {
     return this;
   }
 
+  /**
+   * @return {chrome.Options} the Chrome specific options currently configured
+   *     for this builder.
+   */
+  getChromeOptions() {
+    return this.chromeOptions_;
+  }
+
+  /**
+   * Sets the service builder to use for managing the chromedriver child process
+   * when creating new Chrome sessions.
+   *
+   * @param {chrome.ServiceBuilder} service the service to use.
+   * @return {!Builder} A self reference.
+   */
+  setChromeService(service) {
+    if (service && !(service instanceof chrome.ServiceBuilder)) {
+      throw TypeError('not a chrome.ServiceBuilder object');
+    }
+    this.chromeService_ = service;
+    return this;
+  }
+
   /**
    * Sets Firefox specific {@linkplain firefox.Options options} for drivers
    * created by this builder. Any logging or proxy settings defined on the given
@@ -468,16 +466,17 @@ class Builder {
   }
 
   /**
-   * Sets Opera specific {@linkplain opera.Options options} for drivers created
-   * by this builder. Any logging or proxy settings defined on the given options
-   * will take precedence over those set through {@link #setLoggingPrefs} and
-   * {@link #setProxy}, respectively.
+   * Sets the {@link firefox.ServiceBuilder} to use to manage the geckodriver
+   * child process when creating Firefox sessions locally.
    *
-   * @param {!opera.Options} options The OperaDriver options to use.
-   * @return {!Builder} A self reference.
+   * @param {firefox.ServiceBuilder} service the service to use.
+   * @return {!Builder} a self reference.
    */
-  setOperaOptions(options) {
-    this.operaOptions_ = options;
+  setFirefoxService(service) {
+    if (service && !(service instanceof firefox.ServiceBuilder)) {
+      throw TypeError('not a firefox.ServiceBuilder object');
+    }
+    this.firefoxService_ = service;
     return this;
   }
 
@@ -494,6 +493,18 @@ class Builder {
     return this;
   }
 
+  /**
+   * Sets the {@link ie.ServiceBuilder} to use to manage the geckodriver
+   * child process when creating IE sessions locally.
+   *
+   * @param {ie.ServiceBuilder} service the service to use.
+   * @return {!Builder} a self reference.
+   */
+  setIeService(service) {
+    this.ieService_ = service;
+    return this;
+  }
+
   /**
    * Set {@linkplain edge.Options options} specific to Microsoft's Edge browser
    * for drivers created by this builder. Any proxy settings defined on the
@@ -508,6 +519,21 @@ class Builder {
     return this;
   }
 
+  /**
+   * Sets the {@link edge.ServiceBuilder} to use to manage the
+   * MicrosoftEdgeDriver child process when creating sessions locally.
+   *
+   * @param {edge.ServiceBuilder} service the service to use.
+   * @return {!Builder} a self reference.
+   */
+  setEdgeService(service) {
+    if (service && !(service instanceof edge.ServiceBuilder)) {
+      throw TypeError('not a edge.ServiceBuilder object');
+    }
+    this.edgeService_ = service;
+    return this;
+  }
+
   /**
    * Sets Safari specific {@linkplain safari.Options options} for drivers
    * created by this builder. Any logging settings defined on the given options
@@ -529,19 +555,6 @@ class Builder {
     return this.safariOptions_;
   }
 
-  /**
-   * Sets the control flow that created drivers should execute actions in. If
-   * the flow is never set, or is set to {@code null}, it will use the active
-   * flow at the time {@link #build()} is called.
-   * @param {promise.ControlFlow} flow The control flow to use, or
-   *     {@code null} to
-   * @return {!Builder} A self reference.
-   */
-  setControlFlow(flow) {
-    this.flow_ = flow;
-    return this;
-  }
-
   /**
    * Creates a new WebDriver client based on this builder's current
    * configuration.
@@ -564,9 +577,10 @@ class Builder {
     if (!this.ignoreEnv_ && process.env.SELENIUM_BROWSER) {
       this.log_.fine(`SELENIUM_BROWSER=${process.env.SELENIUM_BROWSER}`);
       browser = process.env.SELENIUM_BROWSER.split(/:/, 3);
-      capabilities.set(Capability.BROWSER_NAME, browser[0]);
-      capabilities.set(Capability.VERSION, browser[1] || null);
-      capabilities.set(Capability.PLATFORM, browser[2] || null);
+      capabilities.setBrowserName(browser[0]);
+
+      browser[1] && capabilities.setBrowserVersion(browser[1]);
+      browser[2] && capabilities.setPlatform(browser[2]);
     }
 
     browser = capabilities.get(Capability.BROWSER_NAME);
@@ -583,24 +597,29 @@ class Builder {
 
     // Apply browser specific overrides.
     if (browser === Browser.CHROME && this.chromeOptions_) {
-      capabilities.merge(this.chromeOptions_.toCapabilities());
+      capabilities.merge(this.chromeOptions_);
 
     } else if (browser === Browser.FIREFOX && this.firefoxOptions_) {
-      capabilities.merge(this.firefoxOptions_.toCapabilities());
+      capabilities.merge(this.firefoxOptions_);
 
     } else if (browser === Browser.INTERNET_EXPLORER && this.ieOptions_) {
-      capabilities.merge(this.ieOptions_.toCapabilities());
-
-    } else if (browser === Browser.OPERA && this.operaOptions_) {
-      capabilities.merge(this.operaOptions_.toCapabilities());
+      capabilities.merge(this.ieOptions_);
 
     } else if (browser === Browser.SAFARI && this.safariOptions_) {
-      capabilities.merge(this.safariOptions_.toCapabilities());
+      capabilities.merge(this.safariOptions_);
 
     } else if (browser === Browser.EDGE && this.edgeOptions_) {
-      capabilities.merge(this.edgeOptions_.toCapabilities());
+      capabilities.merge(this.edgeOptions_);
     }
 
+    checkOptions(
+        capabilities, 'chromeOptions', chrome.Options, 'setChromeOptions');
+    checkOptions(
+        capabilities, 'moz:firefoxOptions', firefox.Options,
+        'setFirefoxOptions');
+    checkOptions(
+        capabilities, 'safari.options', safari.Options, 'setSafariOptions');
+
     // Check for a remote browser.
     let url = this.url_;
     if (!this.ignoreEnv_) {
@@ -623,41 +642,51 @@ class Builder {
 
       if (browser === Browser.CHROME) {
         const driver = ensureFileDetectorsAreEnabled(chrome.Driver);
-        return createDriver(
-            driver, capabilities, executor, this.flow_);
+        return createDriver(driver, capabilities, executor);
       }
 
       if (browser === Browser.FIREFOX) {
         const driver = ensureFileDetectorsAreEnabled(firefox.Driver);
-        return createDriver(
-            driver, capabilities, executor, this.flow_);
+        return createDriver(driver, capabilities, executor);
       }
-      return createDriver(
-          WebDriver, executor, capabilities, this.flow_);
+      return createDriver(WebDriver, executor, capabilities);
     }
 
     // Check for a native browser.
     switch (browser) {
-      case Browser.CHROME:
-        return createDriver(chrome.Driver, capabilities, null, this.flow_);
+      case Browser.CHROME: {
+        let service = null;
+        if (this.chromeService_) {
+          service = this.chromeService_.build();
+        }
+        return createDriver(chrome.Driver, capabilities, service);
+      }
 
-      case Browser.FIREFOX:
-        return createDriver(firefox.Driver, capabilities, null, this.flow_);
+      case Browser.FIREFOX: {
+        let service = null;
+        if (this.firefoxService_) {
+          service = this.firefoxService_.build();
+        }
+        return createDriver(firefox.Driver, capabilities, service);
+      }
 
       case Browser.INTERNET_EXPLORER:
-        return createDriver(ie.Driver, capabilities, this.flow_);
-
-      case Browser.EDGE:
-        return createDriver(edge.Driver, capabilities, null, this.flow_);
-
-      case Browser.OPERA:
-        return createDriver(opera.Driver, capabilities, null, this.flow_);
-
-      case Browser.PHANTOM_JS:
-        return createDriver(phantomjs.Driver, capabilities, this.flow_);
+        let service = null;
+        if (this.ieService_) {
+          service = this.ieService_.build();
+        }
+        return createDriver(ie.Driver, capabilities, service);
+
+      case Browser.EDGE: {
+        let service = null;
+        if (this.edgeService_) {
+          service = this.edgeService_.build();
+        }
+        return createDriver(edge.Driver, capabilities, service);
+      }
 
       case Browser.SAFARI:
-        return createDriver(safari.Driver, capabilities, this.flow_);
+        return createDriver(safari.Driver, capabilities);
 
       default:
         throw new Error('Do not know how to build driver: ' + browser
@@ -667,10 +696,66 @@ class Builder {
 }
 
 
+/**
+ * In the 3.x releases, the various browser option classes
+ * (e.g. firefox.Options) had to be manually set as an option using the
+ * Capabilties class:
+ *
+ *     let ffo = new firefox.Options();
+ *     // Configure firefox options...
+ *
+ *     let caps = new Capabilities();
+ *     caps.set('moz:firefoxOptions', ffo);
+ *
+ *     let driver = new Builder()
+ *         .withCapabilities(caps)
+ *         .build();
+ *
+ * The options are now subclasses of Capabilities and can be used directly. A
+ * direct translation of the above is:
+ *
+ *     let ffo = new firefox.Options();
+ *     // Configure firefox options...
+ *
+ *     let driver = new Builder()
+ *         .withCapabilities(ffo)
+ *         .build();
+ *
+ * You can also set the options for various browsers at once and let the builder
+ * choose the correct set at runtime (see Builder docs above):
+ *
+ *     let ffo = new firefox.Options();
+ *     // Configure ...
+ *
+ *     let co = new chrome.Options();
+ *     // Configure ...
+ *
+ *     let driver = new Builder()
+ *         .setChromeOptions(co)
+ *         .setFirefoxOptions(ffo)
+ *         .build();
+ *
+ * @param {!Capabilities} caps
+ * @param {string} key
+ * @param {function(new: Capabilities)} optionType
+ * @param {string} setMethod
+ * @throws {error.InvalidArgumentError}
+ */
+function checkOptions(caps, key, optionType, setMethod) {
+  let val = caps.get(key);
+  if (val instanceof optionType) {
+    throw new error.InvalidArgumentError(
+        'Options class extends Capabilities and should not be set as key '
+            + `"${key}"; set browser-specific options with `
+            + `Builder.${setMethod}(). For more information, see the `
+            + 'documentation attached to the function that threw this error');
+  }
+}
+
+
 // PUBLIC API
 
 
-exports.ActionSequence = actions.ActionSequence;
 exports.Browser = capabilities.Browser;
 exports.Builder = Builder;
 exports.Button = input.Button;
@@ -678,12 +763,11 @@ exports.By = by.By;
 exports.Capabilities = capabilities.Capabilities;
 exports.Capability = capabilities.Capability;
 exports.Condition = webdriver.Condition;
-exports.EventEmitter = events.EventEmitter;
 exports.FileDetector = input.FileDetector;
 exports.Key = input.Key;
+exports.Origin = input.Origin;
 exports.Session = session.Session;
 exports.ThenableWebDriver = ThenableWebDriver;
-exports.TouchSequence = actions.TouchSequence;
 exports.WebDriver = webdriver.WebDriver;
 exports.WebElement = webdriver.WebElement;
 exports.WebElementCondition = webdriver.WebElementCondition;

package/io/exec.js

@@ -21,22 +21,37 @@ const childProcess = require('child_process');
 
 
 /**
- * A hash with configuration options for an executed command.
+ * Options for configuring an executed command.
  *
- * - `args` - Command line arguments.
- * - `env` - Command environment; will inherit from the current process if
- *     missing.
- * - `stdio` - IO configuration for the spawned server process. For more
- *     information, refer to the documentation of `child_process.spawn`.
- *
- * @typedef {{
- *   args: (!Array<string>|undefined),
- *   env: (!Object<string, string>|undefined),
- *   stdio: (string|!Array<string|number|!stream.Stream|null|undefined>|
- *           undefined)
- * }}
+ * @record
  */
-var Options;
+class Options {
+  constructor() {
+    /**
+     * Command line arguments for the child process, if any.
+     * @type (!Array<string>|undefined)
+     */
+    this.args;
+
+    /**
+     * Environment variables for the spawned process. If unspecified, the
+     * child will inherit this process' environment.
+     *
+     * @type {(!Object<string, string>|undefined)}
+     */
+    this.env;
+
+    /**
+     * IO conifguration for the spawned server child process. If unspecified,
+     * the child process' IO output will be ignored.
+     *
+     * @type {(string|!Array<string|number|!stream.Stream|null|undefined>|
+     *           undefined)}
+     * @see <https://nodejs.org/dist/latest-v8.x/docs/api/child_process.html#child_process_options_stdio>
+     */
+    this.stdio;
+  }
+}
 
 
 /**
@@ -148,6 +163,5 @@ module.exports = function exec(command, opt_options) {
 // Exported to improve generated API documentation.
 
 module.exports.Command = Command;
-/** @typedef {!Options} */
 module.exports.Options = Options;
 module.exports.Result = Result;

package/io/index.js

@@ -89,10 +89,10 @@ exports.copy = function(src, dst) {
   return new Promise(function(fulfill, reject) {
     var rs = fs.createReadStream(src);
     rs.on('error', reject);
-    rs.on('end', () => fulfill(dst));
 
     var ws = fs.createWriteStream(dst);
     ws.on('error', reject);
+    ws.on('close', () => fulfill(dst));
 
     rs.pipe(ws);
   });

package/io/zip.js

@@ -45,7 +45,7 @@ class Zip {
    */
   addFile(filePath, zipPath = path.basename(filePath)) {
     let add = io.read(filePath)
-        .then(buffer => this.z_.file(/** @type {string} */(zipPath), buffer));
+        .then(buffer => this.z_.file(/** @type {string} */(zipPath.replace(/\\/g, '/')), buffer));
     this.pendingAdds_.add(add);
     return add.then(
         () => this.pendingAdds_.delete(add),