selenium-webdriver 3.5.0 → 4.0.0-alpha.4

package/chrome.js

@@ -39,8 +39,7 @@
  * __Headless Chrome__ <a id="headless"></a>
  *
  * To start Chrome in headless mode, simply call
- * {@linkplain Options#headless Options.headless()}. Note, starting in headless
- * mode currently also disables GPU acceleration.
+ * {@linkplain Options#headless Options.headless()}.
  *
  *     let chrome = require('selenium-webdriver/chrome');
  *     let {Builder} = require('selenium-webdriver');
@@ -133,8 +132,9 @@ const util = require('util');
 
 const http = require('./http');
 const io = require('./io');
-const {Capabilities, Capability} = require('./lib/capabilities');
+const {Browser, Capabilities, Capability} = require('./lib/capabilities');
 const command = require('./lib/command');
+const error = require('./lib/error');
 const logging = require('./lib/logging');
 const promise = require('./lib/promise');
 const Symbols = require('./lib/symbols');
@@ -159,7 +159,8 @@ const CHROMEDRIVER_EXE =
 const Command = {
   LAUNCH_APP: 'launchApp',
   GET_NETWORK_CONDITIONS: 'getNetworkConditions',
-  SET_NETWORK_CONDITIONS: 'setNetworkConditions'
+  SET_NETWORK_CONDITIONS: 'setNetworkConditions',
+  SEND_DEVTOOLS_COMMAND: 'sendDevToolsCommand',
 };
 
 
@@ -169,7 +170,8 @@ const Command = {
  * @return {!command.Executor} The new command executor.
  */
 function createExecutor(url) {
-  let client = url.then(url => new http.HttpClient(url));
+  let agent = new http.Agent({ keepAlive: true });
+  let client = url.then(url => new http.HttpClient(url, agent));
   let executor = new http.Executor(client);
   configureExecutor(executor);
   return executor;
@@ -193,6 +195,21 @@ function configureExecutor(executor) {
       Command.SET_NETWORK_CONDITIONS,
       'POST',
       '/session/:sessionId/chromium/network_conditions');
+  executor.defineCommand(
+      Command.SEND_DEVTOOLS_COMMAND,
+      'POST',
+      '/session/:sessionId/chromium/send_command');
+}
+
+
+/**
+ * _Synchronously_ attempts to locate the chromedriver executable on the current
+ * system.
+ *
+ * @return {?string} the located executable, or `null`.
+ */
+function locateSynchronously() {
+  return io.findInPath(CHROMEDRIVER_EXE, true);
 }
 
 
@@ -210,7 +227,7 @@ class ServiceBuilder extends remote.DriverService.Builder {
    *     cannot be found on the PATH.
    */
   constructor(opt_exe) {
-    let exe = opt_exe || io.findInPath(CHROMEDRIVER_EXE, true);
+    let exe = opt_exe || locateSynchronously();
     if (!exe) {
       throw Error(
           'The ChromeDriver could not be found on the current PATH. Please ' +
@@ -307,64 +324,25 @@ function getDefaultService() {
 }
 
 
-const OPTIONS_CAPABILITY_KEY = 'chromeOptions';
+const OPTIONS_CAPABILITY_KEY = 'goog:chromeOptions';
 
 
 /**
  * Class for managing ChromeDriver specific options.
  */
-class Options {
-  constructor() {
-    /** @private {!Object} */
-    this.options_ = {};
-
-    /** @private {!Array<(string|!Buffer)>} */
-    this.extensions_ = [];
-
-    /** @private {?logging.Preferences} */
-    this.logPrefs_ = null;
-
-    /** @private {?./lib/capabilities.ProxyConfig} */
-    this.proxy_ = null;
-  }
-
-  /**
-   * Extracts the ChromeDriver specific options from the given capabilities
-   * object.
-   * @param {!Capabilities} caps The capabilities object.
-   * @return {!Options} The ChromeDriver options.
-   */
-  static fromCapabilities(caps) {
-    let options = new Options();
-
-    let o = caps.get(OPTIONS_CAPABILITY_KEY);
-    if (o instanceof Options) {
-      options = o;
-    } else if (o) {
-      options.
-          addArguments(o.args || []).
-          addExtensions(o.extensions || []).
-          detachDriver(o.detach).
-          excludeSwitches(o.excludeSwitches || []).
-          setChromeBinaryPath(o.binary).
-          setChromeLogFile(o.logPath).
-          setChromeMinidumpPath(o.minidumpPath).
-          setLocalState(o.localState).
-          setMobileEmulation(o.mobileEmulation).
-          setUserPreferences(o.prefs).
-          setPerfLoggingPrefs(o.perfLoggingPrefs);
-    }
-
-    if (caps.has(Capability.PROXY)) {
-      options.setProxy(caps.get(Capability.PROXY));
-    }
+class Options extends Capabilities {
+  /**
+   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
+   *     capabilities to initialize this instance from.
+   */
+  constructor(other = undefined) {
+    super(other);
 
-    if (caps.has(Capability.LOGGING_PREFS)) {
-      options.setLoggingPrefs(
-          caps.get(Capability.LOGGING_PREFS));
-    }
+    /** @private {!Object} */
+    this.options_ = this.get(OPTIONS_CAPABILITY_KEY) || {};
 
-    return options;
+    this.setBrowserName(Browser.CHROME);
+    this.set(OPTIONS_CAPABILITY_KEY, this.options_);
   }
 
   /**
@@ -391,12 +369,16 @@ class Options {
    * > in Chrome 60. Users are encouraged to set an initial window size with
    * > the {@link #windowSize windowSize({width, height})} option.
    *
+   * > __NOTE__: For security, Chrome disables downloads by default when
+   * > in headless mode (to prevent sites from silently downloading files to
+   * > your machine). After creating a session, you may call
+   * > {@link ./chrome.Driver#setDownloadPath setDownloadPath} to re-enable
+   * > downloads, saving files in the specified directory.
+   *
    * @return {!Options} A self reference.
    */
   headless() {
-    // TODO(jleyba): Remove `disable-gpu` once head Chrome no longer requires
-    // that to be set.
-    return this.addArguments('headless', 'disable-gpu');
+    return this.addArguments('headless');
   }
 
   /**
@@ -442,7 +424,8 @@ class Options {
    * @return {!Options} A self reference.
    */
   addExtensions(...args) {
-    this.extensions_ = this.extensions_.concat(...args);
+    let current = this.options_.extensions || [];
+    this.options_.extensions = current.concat(...args);
     return this;
   }
 
@@ -486,16 +469,6 @@ class Options {
     return this;
   }
 
-  /**
-   * Sets the logging preferences for the new session.
-   * @param {!logging.Preferences} prefs The logging preferences.
-   * @return {!Options} A self reference.
-   */
-  setLoggingPrefs(prefs) {
-    this.logPrefs_ = prefs;
-    return this;
-  }
-
   /**
    * Sets the performance logging preferences. Options include:
    *
@@ -673,54 +646,25 @@ class Options {
     return this;
   }
 
-  /**
-   * Sets the proxy settings for the new session.
-   * @param {./lib/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} object.
-   * @param {Capabilities=} opt_capabilities The capabilities to merge
-   *     these options into, if any.
-   * @return {!Capabilities} The capabilities.
-   */
-  toCapabilities(opt_capabilities) {
-    let caps = opt_capabilities || Capabilities.chrome();
-    caps.
-        set(Capability.PROXY, this.proxy_).
-        set(Capability.LOGGING_PREFS, this.logPrefs_).
-        set(OPTIONS_CAPABILITY_KEY, this);
-    return caps;
-  }
-
   /**
    * Converts this instance to its JSON wire protocol representation. Note this
    * function is an implementation not intended for general use.
+   *
    * @return {!Object} The JSON wire protocol representation of this instance.
+   * @suppress {checkTypes} Suppress [] access on a struct.
    */
   [Symbols.serialize]() {
-    let json = {};
-    for (let key in this.options_) {
-      if (this.options_[key] != null) {
-        json[key] = this.options_[key];
-      }
-    }
-    if (this.extensions_.length) {
-      json.extensions = this.extensions_.map(function(extension) {
-        if (Buffer.isBuffer(extension)) {
-          return extension.toString('base64');
-        }
-        return io.read(/** @type {string} */(extension))
-            .then(buffer => buffer.toString('base64'));
-      });
+    if (this.options_.extensions &&  this.options_.extensions.length) {
+      this.options_.extensions =
+          this.options_.extensions.map(function(extension) {
+            if (Buffer.isBuffer(extension)) {
+              return extension.toString('base64');
+            }
+            return io.read(/** @type {string} */(extension))
+                .then(buffer => buffer.toString('base64'));
+          });
     }
-    return json;
+    return super[Symbols.serialize]();
   }
 }
 
@@ -739,11 +683,9 @@ class Driver extends webdriver.WebDriver {
    *     for an externally managed endpoint. If neither is provided, the
    *     {@linkplain ##getDefaultService default service} will be used by
    *     default.
-   * @param {promise.ControlFlow=} opt_flow The control flow to use, or `null`
-   *     to use the currently active flow.
    * @return {!Driver} A new driver instance.
    */
-  static createSession(opt_config, opt_serviceExecutor, opt_flow) {
+  static createSession(opt_config, opt_serviceExecutor) {
     let executor;
     if (opt_serviceExecutor instanceof http.Executor) {
       executor = opt_serviceExecutor;
@@ -753,12 +695,19 @@ class Driver extends webdriver.WebDriver {
       executor = createExecutor(service.start());
     }
 
-    let caps =
-        opt_config instanceof Options ? opt_config.toCapabilities() :
-        (opt_config || Capabilities.chrome());
+    let caps = opt_config || Capabilities.chrome();
+
+    // W3C spec requires noProxy value to be an array of strings, but Chrome
+    // expects a single host as a string.
+    let proxy = caps.get(Capability.PROXY);
+    if (proxy && Array.isArray(proxy.noProxy)) {
+      proxy.noProxy = proxy.noProxy[0];
+      if (!proxy.noProxy) {
+        proxy.noProxy = undefined;
+      }
+    }
 
-    return /** @type {!Driver} */(
-        super.createSession(executor, caps, opt_flow));
+    return /** @type {!Driver} */(super.createSession(executor, caps));
   }
 
   /**
@@ -771,24 +720,21 @@ class Driver extends webdriver.WebDriver {
   /**
    * Schedules a command to launch Chrome App with given ID.
    * @param {string} id ID of the App to launch.
-   * @return {!promise.Thenable<void>} A promise that will be resolved
+   * @return {!Promise<void>} A promise that will be resolved
    *     when app is launched.
    */
   launchApp(id) {
-    return this.schedule(
-        new command.Command(Command.LAUNCH_APP).setParameter('id', id),
-        'Driver.launchApp()');
+    return this.execute(
+        new command.Command(Command.LAUNCH_APP).setParameter('id', id));
   }
 
   /**
    * Schedules a command to get Chrome network emulation settings.
-   * @return {!promise.Thenable<T>} A promise that will be resolved
-   *     when network emulation settings are retrievied.
+   * @return {!Promise} A promise that will be resolved when network
+   *     emulation settings are retrievied.
    */
   getNetworkConditions() {
-    return this.schedule(
-        new command.Command(Command.GET_NETWORK_CONDITIONS),
-        'Driver.getNetworkConditions()');
+    return this.execute(new command.Command(Command.GET_NETWORK_CONDITIONS));
   }
 
   /**
@@ -804,17 +750,54 @@ class Driver extends webdriver.WebDriver {
    * });
    *
    * @param {Object} spec Defines the network conditions to set
-   * @return {!promise.Thenable<void>} A promise that will be resolved
-   *     when network emulation settings are set.
+   * @return {!Promise<void>} A promise that will be resolved when network
+   *     emulation settings are set.
    */
   setNetworkConditions(spec) {
     if (!spec || typeof spec !== 'object') {
       throw TypeError('setNetworkConditions called with non-network-conditions parameter');
     }
+    return this.execute(
+        new command.Command(Command.SET_NETWORK_CONDITIONS)
+            .setParameter('network_conditions', spec));
+  }
+
+  /**
+   * Sends an arbitrary devtools command to the browser.
+   *
+   * @param {string} cmd The name of the command to send.
+   * @param {Object=} params The command parameters.
+   * @return {!Promise<void>} A promise that will be resolved when the command
+   *     has finished.
+   * @see <https://chromedevtools.github.io/devtools-protocol/>
+   */
+  sendDevToolsCommand(cmd, params = {}) {
+    return this.execute(
+        new command.Command(Command.SEND_DEVTOOLS_COMMAND)
+            .setParameter('cmd', cmd)
+            .setParameter('params', params));
+  }
 
-    return this.schedule(
-        new command.Command(Command.SET_NETWORK_CONDITIONS).setParameter('network_conditions', spec),
-        'Driver.setNetworkConditions(' + JSON.stringify(spec) + ')');
+  /**
+   * Sends a DevTools command to change Chrome's download directory.
+   *
+   * @param {string} path The desired download directory.
+   * @return {!Promise<void>} A promise that will be resolved when the command
+   *     has finished.
+   * @see #sendDevToolsCommand
+   */
+  async setDownloadPath(path) {
+    if (!path || typeof path !== 'string') {
+      throw new error.InvalidArgumentError('invalid download path');
+    }
+    const stat = await io.stat(path);
+    if (!stat.isDirectory()) {
+      throw new error.InvalidArgumentError('not a directory: ' + path);
+    }
+    return this.sendDevToolsCommand('Page.setDownloadBehavior', {
+      'behavior': 'allow',
+      'downloadPath': path
+    });
   }
 }
 
@@ -827,3 +810,4 @@ exports.Options = Options;
 exports.ServiceBuilder = ServiceBuilder;
 exports.getDefaultService = getDefaultService;
 exports.setDefaultService = setDefaultService;
+exports.locateSynchronously = locateSynchronously;

package/edge.js

@@ -70,121 +70,44 @@
 
 'use strict';
 
-const fs = require('fs'),
-    util = require('util');
-
-const http = require('./http'),
-    io = require('./io'),
-    capabilities = require('./lib/capabilities'),
-    promise = require('./lib/promise'),
-    Symbols = require('./lib/symbols'),
-    webdriver = require('./lib/webdriver'),
-    portprober = require('./net/portprober'),
-    remote = require('./remote');
+const fs = require('fs');
+const util = require('util');
+
+const http = require('./http');
+const io = require('./io');
+const portprober = require('./net/portprober');
+const promise = require('./lib/promise');
+const remote = require('./remote');
+const Symbols = require('./lib/symbols');
+const webdriver = require('./lib/webdriver');
+const {Browser, Capabilities} = require('./lib/capabilities');
 
 const EDGEDRIVER_EXE = 'MicrosoftWebDriver.exe';
 
 
 /**
- * Option keys.
- * @enum {string}
+ * _Synchronously_ attempts to locate the edge driver executable on the current
+ * system.
+ *
+ * @return {?string} the located executable, or `null`.
  */
-const CAPABILITY_KEY = {
-  PAGE_LOAD_STRATEGY: 'pageLoadStrategy'
-};
+function locateSynchronously() {
+  return process.platform === 'win32'
+      ? io.findInPath(EDGEDRIVER_EXE, true) : null;
+}
 
 
 /**
  * Class for managing MicrosoftEdgeDriver specific options.
  */
-class Options {
-  constructor() {
-    /** @private {!Object} */
-    this.options_ = {};
-
-    /** @private {?capabilities.ProxyConfig} */
-    this.proxy_ = null;
-  }
-
-  /**
-   * Extracts the MicrosoftEdgeDriver specific options from the given
-   * capabilities object.
-   * @param {!capabilities.Capabilities} caps The capabilities object.
-   * @return {!Options} The MicrosoftEdgeDriver options.
-   */
-  static fromCapabilities(caps) {
-    var options = new Options();
-    var map = options.options_;
-
-    Object.keys(CAPABILITY_KEY).forEach(function(key) {
-      key = CAPABILITY_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;
-  }
-
-  /**
-   * 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;
-  }
-
+class Options extends Capabilities {
   /**
-   * Sets the page load strategy for Edge.
-   * Supported values are "normal", "eager", and "none";
-   *
-   * @param {string} pageLoadStrategy The page load strategy to use.
-   * @return {!Options} A self reference.
+   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
+   *     capabilities to initialize this instance from.
    */
-  setPageLoadStrategy(pageLoadStrategy) {
-    this.options_[CAPABILITY_KEY.PAGE_LOAD_STRATEGY] =
-      pageLoadStrategy.toLowerCase();
-    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.edge();
-    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;
-  }
-
-  /**
-   * Converts this instance to its JSON wire protocol representation. Note this
-   * function is an implementation not intended for general use.
-   * @return {{pageLoadStrategy: (string|undefined)}}
-   *   The JSON wire protocol representation of this instance.
-   */
-  [Symbols.serialize]() {
-    var json = {};
-    for (var key in this.options_) {
-      if (this.options_[key] != null) {
-        json[key] = this.options_[key];
-      }
-    }
-    return json;
+  constructor(other = undefined) {
+    super(other);
+    this.setBrowserName(Browser.EDGE);
   }
 }
 
@@ -202,7 +125,7 @@ class ServiceBuilder extends remote.DriverService.Builder {
    *   MicrosoftEdgeDriver cannot be found on the PATH.
    */
   constructor(opt_exe) {
-    let exe = opt_exe || io.findInPath(EDGEDRIVER_EXE, true);
+    let exe = opt_exe || locateSynchronously();
     if (!exe) {
       throw Error(
         'The ' + EDGEDRIVER_EXE + ' could not be found on the current PATH. ' +
@@ -218,6 +141,14 @@ class ServiceBuilder extends remote.DriverService.Builder {
     // (or can we?), force the DriverService to use "localhost".
     this.setHostname('localhost');
   }
+
+  /**
+   * Enables verbose logging.
+   * @return {!ServiceBuilder} A self reference.
+   */
+  enableVerboseLogging() {
+    return this.addArguments('--verbose');
+  }
 }
 
 
@@ -261,25 +192,19 @@ class Driver extends webdriver.WebDriver {
   /**
    * Creates a new browser session for Microsoft's Edge browser.
    *
-   * @param {(capabilities.Capabilities|Options)=} opt_config The configuration
-   *     options.
-   * @param {remote.DriverService=} opt_service The session to use; will use
+   * @param {(Capabilities|Options)=} options The configuration options.
+   * @param {remote.DriverService=} service The session to use; will use
    *     the {@linkplain #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.
    */
-  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);
-
-    var caps =
-        opt_config instanceof Options ? opt_config.toCapabilities() :
-        (opt_config || capabilities.Capabilities.edge());
+  static createSession(options, opt_service) {
+    let service = opt_service || getDefaultService();
+    let client = service.start().then(url => new http.HttpClient(url));
+    let executor = new http.Executor(client);
 
+    options = options || new Options();
     return /** @type {!Driver} */(super.createSession(
-        executor, caps, opt_flow, () => service.kill()));
+        executor, options, () => service.kill()));
   }
 
   /**
@@ -299,3 +224,4 @@ exports.Options = Options;
 exports.ServiceBuilder = ServiceBuilder;
 exports.getDefaultService = getDefaultService;
 exports.setDefaultService = setDefaultService;
+exports.locateSynchronously = locateSynchronously;

package/example/chrome_android.js

@@ -23,21 +23,20 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, until} = require('..');
 const {Options} = require('../chrome');
 
-promise.consume(function* () {
+(async function() {
   let driver;
   try {
-    driver = yield new Builder()
+    driver = await new Builder()
         .forBrowser('chrome')
         .setChromeOptions(new Options().androidChrome())
         .build();
-    yield driver.get('http://www.google.com/ncr');
-    yield driver.findElement(By.name('q')).sendKeys('webdriver');
-    yield driver.findElement(By.name('btnG')).click();
-    yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+    await driver.get('http://www.google.com/ncr');
+    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
+    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {
-    yield driver && driver.quit();
+    await driver && driver.quit();
   }
-}).then(_ => console.log('SUCCESS'), err => console.error('ERROR: ' + err));
+})().then(_ => console.log('SUCCESS'), err => console.error('ERROR: ' + err));

package/example/chrome_mobile_emulation.js

@@ -22,22 +22,21 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, until} = require('..');
 const {Options} = require('../chrome');
 
-promise.consume(function* () {
+(async function() {
   let driver;
   try {
-    driver = yield new Builder()
+    driver = await new Builder()
         .forBrowser('chrome')
         .setChromeOptions(
             new Options().setMobileEmulation({deviceName: 'Nexus 5X'}))
         .build();
-    yield driver.get('http://www.google.com/ncr');
-    yield driver.findElement(By.name('q')).sendKeys('webdriver');
-    yield driver.findElement(By.name('btnG')).click();
-    yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+    await driver.get('http://www.google.com/ncr');
+    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
+    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {
-    yield driver && driver.quit();
+    await driver && driver.quit();
   }
-}).then(_ => console.log('SUCCESS'), err => console.error('ERROR: ' + err));
+})().then(_ => console.log('SUCCESS'), err => console.error('ERROR: ' + err));