selenium-webdriver 3.3.0 → 4.0.0-alpha.1

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 {
@@ -131,7 +127,10 @@ const THENABLE_DRIVERS = new Map;
 function createDriver(ctor, ...args) {
   let thenableWebDriverProxy = THENABLE_DRIVERS.get(ctor);
   if (!thenableWebDriverProxy) {
-    /** @implements {ThenableWebDriver} */
+    /**
+     * @extends {WebDriver}  // Needed since `ctor` is dynamically typed.
+     * @implements {ThenableWebDriver}
+     */
     thenableWebDriverProxy = class extends ctor {
       /**
        * @param {!IThenable<!Session>} session
@@ -144,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);
@@ -212,9 +200,6 @@ class Builder {
     /** @private @const */
     this.log_ = logging.getLogger('webdriver.Builder');
 
-    /** @private {promise.ControlFlow} */
-    this.flow_ = null;
-
     /** @private {string} */
     this.url_ = '';
 
@@ -227,11 +212,14 @@ 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;
@@ -242,6 +230,9 @@ class Builder {
     /** @private {edge.Options} */
     this.edgeOptions_ = null;
 
+    /** @private {remote.DriverService.Builder} */
+    this.edgeService_ = null;
+
     /** @private {boolean} */
     this.ignoreEnv_ = false;
 
@@ -355,18 +346,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;
   }
 
@@ -375,7 +370,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) {
@@ -395,33 +390,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);
@@ -442,6 +417,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
@@ -465,16 +463,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;
   }
 
@@ -505,6 +504,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
@@ -526,19 +540,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.
@@ -561,9 +562,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);
@@ -580,24 +582,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_) {
@@ -620,41 +627,47 @@ 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_);
+        return createDriver(ie.Driver, capabilities);
+
+      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
@@ -664,10 +677,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;
@@ -675,12 +744,10 @@ 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.Session = session.Session;
 exports.ThenableWebDriver = ThenableWebDriver;
-exports.TouchSequence = actions.TouchSequence;
 exports.WebDriver = webdriver.WebDriver;
 exports.WebElement = webdriver.WebElement;
 exports.WebElementCondition = webdriver.WebElementCondition;

package/io/index.js

@@ -298,3 +298,62 @@ exports.mkdir = function(aPath) {
     });
   });
 };
+
+
+/**
+ * Recursively creates a directory and any ancestors that do not yet exist.
+ *
+ * @param {string} dir The directory path to create.
+ * @return {!Promise<string>} A promise that will resolve with the path of the
+ *     created directory.
+ */
+exports.mkdirp = function mkdirp(dir) {
+  return checkedCall(callback => {
+    fs.mkdir(dir, undefined, err => {
+      if (!err) {
+        callback(null, dir);
+        return;
+      }
+
+      switch (err.code) {
+        case 'EEXIST':
+          callback(null, dir);
+          return;
+        case 'ENOENT':
+          return mkdirp(path.dirname(dir))
+              .then(() => mkdirp(dir))
+              .then(() => callback(null, dir), err => callback(err));
+        default:
+          callback(err);
+          return;
+      }
+    });
+  });
+};
+
+
+/**
+ * Recursively walks a directory, returning a promise that will resolve with
+ * a list of all files/directories seen.
+ *
+ * @param {string} rootPath the directory to walk.
+ * @return {!Promise<!Array<{path: string, dir: boolean}>>} a promise that will
+ *     resolve with a list of entries seen. For each entry, the recorded path
+ *     will be relative to `rootPath`.
+ */
+exports.walkDir = function(rootPath) {
+  let seen = [];
+  return (function walk(dir) {
+    return checkedCall(callback => fs.readdir(dir, callback))
+        .then(files => Promise.all(files.map(file => {
+          file = path.join(dir, file);
+          return checkedCall(cb => fs.stat(file, cb)).then(stats => {
+            seen.push({
+              path: path.relative(rootPath, file),
+              dir: stats.isDirectory()
+            });
+            return stats.isDirectory() && walk(file);
+          });
+        })));
+  })(rootPath).then(() => seen);
+};