selenium-webdriver 3.1.0 → 3.6.0

package/CHANGES.md

@@ -1,3 +1,114 @@
+## v3.6.0
+
+### Bug Fixes
+
+* The Capabilities factory methods should only specify the name of the browser.
+* Protect against the remote end sometimes not returning a list to findElements
+  commands.
+* Properly reset state in `remote.DriverService#kill()`
+* The firefox module will no longer apply the preferences required by the legacy
+  FirefoxDriver. These preferences were only required when using the legacy
+  driver, support for which was dropped in v3.5.0.
+
+### API Changes
+
+* Added new methods to `selenium-webdriver/firefox.Options`:
+  - addArguments()
+  - headless()
+  - windowSize()
+* Deprecated `selenium-webdriver/firefox/binary.Binary`
+* Removed `selenium-webdriver/firefox.Options#useGeckoDriver()`
+* Removed the unused `selenium-webdriver/firefox/profile.decode()`
+* Removed methods from `selenium-webdriver/firefox/profile.Profile` that had
+  no effect since support for the legacy FirefoxDriver was dropped in 3.5.0:
+  - setNativeEventsEnabled
+  - nativeEventsEnabled
+  - getPort
+  - setPort
+* Removed `selenium-webdriver/firefox.ServiceBuilder#setFirefoxBinary()`; custom
+  binaries should be configured through the `firefox.Options` class.
+* Removed `selenium-webdriver/firefox.Capability`. These hold overs from the
+  legacy FirefoxDriver are no longer supported.
+
+### Changes for W3C WebDriver Spec Compliance
+
+* Deprecated `error.ElementNotVisibleError` in favor of the more generic
+  `error.ElementNotInteractableError`.
+* Support the `httpOnly` option when adding a cookie.
+
+
+## v3.5.0
+
+### Notice
+
+Native support for Firefox 45 (ESR) has been removed. Users will have to connect
+to a remote Selenium server that supports Firefox 45.
+
+### Changes
+
+* Removed native support for Firefox 46 and older.
+  - The `SELENIUM_MARIONETTE` enviornment variable no longer has an effect.
+  - `selenium-webdriver/firefox.Capability.MARIONETTE` is deprecated.
+  - `selenium-webdriver/firefox.Options#useGeckoDriver()` is deprecated and now a no-op.
+* `firefox.Options` will no longer discard the `"moz:firefoxOptions"` set in
+  user provided capabilities (via `Builder.withCapabilities({})`). When both
+  are used, the settings in `firefox.Options` will be applied _last_.
+* Added `chrome.Options#headless()` and `chrome.Options#windowSize()`, which
+  may be used to start Chrome in headless mode (requires Chrome 59+) and to set
+  the initial window size, respectively.
+
+
+### Changes for W3C WebDriver Spec Compliance
+
+* Added `error.WebDriverError#remoteStacktrace` to capture the stacktrace
+  reported by a remote WebDriver endpoint (if any).
+* Fixed `WebElement#sendKeys` to send text as a string instead of an array of
+  strings.
+
+## v3.4.0
+
+### Notice
+
+This release requires [geckodriver 0.15.0](https://github.com/mozilla/geckodriver/releases/tag/v0.15.0) or newer.
+
+### API Changes
+
+* Added `Options#getTimeouts()` for retrieving the currently configured session
+  timeouts (i.e. implicit wait). This method will only work with W3C compatible
+  WebDriver implementations.
+* Deprecated the `Timeouts` class in favor of `Options#setTimeouts()`, which
+  supports setting multiple timeouts at once.
+* Added support for emulating different network conditions (e.g., offline, 2G, WiFi) on Chrome.
+
+### Changes for W3C WebDriver Spec Compliance
+
+* Fixed W3C response parsing, which expects response data to always be a JSON
+  object with a `value` key.
+* Added W3C endpoints for interacting with various types of
+  [user prompts](https://w3c.github.io/webdriver/webdriver-spec.html#user-prompts).
+* Added W3C endpoints for remotely executing scripts.
+* Added W3C endpoints to get current window handle and all windows handles.
+
+
+## v3.3.0
+
+* Added warning log messages when the user creates new managed promises, or
+  schedules unchained tasks. Users may opt in to printing these log messages
+  with
+
+  ```js
+  const {logging} = require('selenium-webdriver');
+  logging.installConsoleHandler();
+  logging.getLogger('promise.ControlFlow').setLevel(logging.Level.WARNING);
+  ```
+* If the `JAVA_HOME` environment variable is set, use it to locate java.exe.
+
+
+## v3.2.0
+
+* Release skipped to stay in sync with the main Selenium project.
+
+
 ## v3.1.0
 
 * The `lib` package is once again platform agnostic (excluding `lib/devmode`).
@@ -17,6 +128,7 @@
 * Use the proper wire command for WebElement.getLocation() and
   WebElement.getSize() for W3C compliant drivers.
 
+
 ## v3.0.1
 
 * More API adjustments to align with native Promises

package/NOTICE

@@ -1,2 +1,2 @@
-Copyright 2011-2016 Software Freedom Conservancy
+Copyright 2011-2017 Software Freedom Conservancy
 Copyright 2004-2011 Selenium committers

package/README.md

@@ -17,16 +17,13 @@ be placed on your system [PATH]. Apple's safaridriver is shipped with
 Safari 10 for OS X El Capitan and macOS Sierra. You will need to enable Remote
 Automation in the Develop menu of Safari 10 before testing.
 
-> **NOTE:**  Mozilla's [geckodriver] is only required for Firefox 47+.
-> Everything you need for Firefox 38-46 is included with this package.
-
 
 | Browser           | Component                          |
 | ----------------- | ---------------------------------- |
 | Chrome            | [chromedriver(.exe)][chrome]       |
 | Internet Explorer | [IEDriverServer.exe][release]      |
 | Edge              | [MicrosoftWebDriver.msi][edge]     |
-| Firefox 47+       | [geckodriver(.exe)][geckodriver]   |
+| Firefox           | [geckodriver(.exe)][geckodriver]   |
 | PhantomJS         | [phantomjs(.exe)][phantomjs]       |
 | Opera             | [operadriver(.exe)][opera]         |
 | Safari            | [safaridriver]                     |
@@ -36,17 +33,14 @@ Automation in the Develop menu of Safari 10 before testing.
 The sample below and others are included in the `example` directory. You may
 also find the tests for selenium-webdriver informative.
 
-    var webdriver = require('selenium-webdriver'),
-        By = webdriver.By,
-        until = webdriver.until;
+    const {Builder, By, Key, until} = require('selenium-webdriver');
 
-    var driver = new webdriver.Builder()
+    let driver = new Builder()
         .forBrowser('firefox')
         .build();
 
     driver.get('http://www.google.com/ncr');
-    driver.findElement(By.name('q')).sendKeys('webdriver');
-    driver.findElement(By.name('btnG')).click();
+    driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
     driver.wait(until.titleIs('webdriver - Google Search'), 1000);
     driver.quit();
 
@@ -193,7 +187,7 @@ the issue tracker
 - __Do not__ post empty "I see this too" or "Any updates?" comments. These
     provide no additional information and clutter the log.
 - __Do not__ report regressions on closed bugs as they are not actively
-    monitored for upates (especially bugs that are >6 months old). Please open a
+    monitored for updates (especially bugs that are >6 months old). Please open a
     new issue and reference the original bug in your report.
 
 ## License

package/chrome.js

@@ -36,6 +36,20 @@
  *     a unique browser session with a clean user profile (unless otherwise
  *     configured through the {@link Options} class).
  *
+ * __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.
+ *
+ *     let chrome = require('selenium-webdriver/chrome');
+ *     let {Builder} = require('selenium-webdriver');
+ *
+ *     let driver = new Builder()
+ *         .forBrowser('chrome')
+ *         .setChromeOptions(new chrome.Options().headless())
+ *         .build();
+ *
  * __Customizing the ChromeDriver Server__ <a id="custom-server"></a>
  *
  * By default, every Chrome session will use a single driver service, which is
@@ -114,19 +128,19 @@
 
 '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, Capability} = require('./lib/capabilities'),
-    command = require('./lib/command'),
-    logging = require('./lib/logging'),
-    promise = require('./lib/promise'),
-    Symbols = require('./lib/symbols'),
-    webdriver = require('./lib/webdriver'),
-    portprober = require('./net/portprober'),
-    remote = require('./remote');
+const http = require('./http');
+const io = require('./io');
+const {Capabilities, Capability} = require('./lib/capabilities');
+const command = require('./lib/command');
+const logging = require('./lib/logging');
+const promise = require('./lib/promise');
+const Symbols = require('./lib/symbols');
+const webdriver = require('./lib/webdriver');
+const portprober = require('./net/portprober');
+const remote = require('./remote');
 
 
 /**
@@ -143,7 +157,9 @@ const CHROMEDRIVER_EXE =
  * @enum {string}
  */
 const Command = {
-  LAUNCH_APP: 'launchApp'
+  LAUNCH_APP: 'launchApp',
+  GET_NETWORK_CONDITIONS: 'getNetworkConditions',
+  SET_NETWORK_CONDITIONS: 'setNetworkConditions'
 };
 
 
@@ -169,6 +185,14 @@ function configureExecutor(executor) {
       Command.LAUNCH_APP,
       'POST',
       '/session/:sessionId/chromium/launch_app');
+  executor.defineCommand(
+      Command.GET_NETWORK_CONDITIONS,
+      'GET',
+      '/session/:sessionId/chromium/network_conditions');
+  executor.defineCommand(
+      Command.SET_NETWORK_CONDITIONS,
+      'POST',
+      '/session/:sessionId/chromium/network_conditions');
 }
 
 
@@ -283,11 +307,7 @@ function getDefaultService() {
 }
 
 
-/**
- * @type {string}
- * @const
- */
-let OPTIONS_CAPABILITY_KEY = 'chromeOptions';
+const OPTIONS_CAPABILITY_KEY = 'chromeOptions';
 
 
 /**
@@ -352,28 +372,61 @@ class Options {
    * browser.  Each argument may be specified with or without the "--" prefix
    * (e.g. "--foo" and "foo"). Arguments with an associated value should be
    * delimited by an "=": "foo=bar".
-   * @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) {
-    let args = this.options_.args || [];
-    args = args.concat.apply(args, arguments);
-    if (args.length) {
-      this.options_.args = args;
+  addArguments(...args) {
+    let newArgs = (this.options_.args || []).concat(...args);
+    if (newArgs.length) {
+      this.options_.args = newArgs;
     }
     return this;
   }
 
+  /**
+   * Configures the chromedriver to start Chrome in headless mode.
+   *
+   * > __NOTE:__ Resizing the browser window in headless mode is only supported
+   * > in Chrome 60. Users are encouraged to set an initial window size with
+   * > the {@link #windowSize windowSize({width, height})} option.
+   *
+   * @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');
+  }
+
+  /**
+   * Sets the initial window size.
+   *
+   * @param {{width: number, height: number}} size The desired window size.
+   * @return {!Options} A self reference.
+   * @throws {TypeError} if width or height is unspecified, not a number, or
+   *     less than or equal to 0.
+   */
+  windowSize({width, height}) {
+    function checkArg(arg) {
+      if (typeof arg !== 'number' || arg <= 0) {
+        throw TypeError('Arguments must be {width, height} with numbers > 0');
+      }
+    }
+    checkArg(width);
+    checkArg(height);
+    return this.addArguments(`window-size=${width},${height}`);
+  }
+
   /**
    * List of Chrome command line switches to exclude that ChromeDriver by default
    * passes when starting Chrome.  Do not prefix switches with "--".
    *
-   * @param {...(string|!Array<string>)} var_args The switches to exclude.
+   * @param {...(string|!Array<string>)} args The switches to exclude.
    * @return {!Options} A self reference.
    */
-  excludeSwitches(var_args) {
-    let switches = this.options_.excludeSwitches || [];
-    switches = switches.concat.apply(switches, arguments);
+  excludeSwitches(...args) {
+    let switches = (this.options_.excludeSwitches || []).concat(...args);
     if (switches.length) {
       this.options_.excludeSwitches = switches;
     }
@@ -384,13 +437,12 @@ class Options {
    * Add additional extensions to install when launching Chrome. Each extension
    * should be specified as the path to the packed CRX file, or a Buffer for an
    * extension.
-   * @param {...(string|!Buffer|!Array<(string|!Buffer)>)} var_args The
+   * @param {...(string|!Buffer|!Array<(string|!Buffer)>)} args The
    *     extensions to add.
    * @return {!Options} A self reference.
    */
-  addExtensions(var_args) {
-    this.extensions_ =
-        this.extensions_.concat.apply(this.extensions_, arguments);
+  addExtensions(...args) {
+    this.extensions_ = this.extensions_.concat(...args);
     return this;
   }
 
@@ -706,7 +758,7 @@ class Driver extends webdriver.WebDriver {
         (opt_config || Capabilities.chrome());
 
     return /** @type {!Driver} */(
-        webdriver.WebDriver.createSession(executor, caps, opt_flow, this));
+        super.createSession(executor, caps, opt_flow));
   }
 
   /**
@@ -727,6 +779,43 @@ class Driver extends webdriver.WebDriver {
         new command.Command(Command.LAUNCH_APP).setParameter('id', id),
         'Driver.launchApp()');
   }
+
+  /**
+   * 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.
+   */
+  getNetworkConditions() {
+    return this.schedule(
+        new command.Command(Command.GET_NETWORK_CONDITIONS),
+        'Driver.getNetworkConditions()');
+  }
+
+  /**
+   * Schedules a command to set Chrome network emulation settings.
+   *
+   * __Sample Usage:__
+   *
+   *  driver.setNetworkConditions({
+   *    offline: false,
+   *    latency: 5, // Additional latency (ms).
+   *    download_throughput: 500 * 1024, // Maximal aggregated download throughput.
+   *    upload_throughput: 500 * 1024 // Maximal aggregated upload throughput.
+   * });
+   *
+   * @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.
+   */
+  setNetworkConditions(spec) {
+    if (!spec || typeof spec !== 'object') {
+      throw TypeError('setNetworkConditions called with non-network-conditions parameter');
+    }
+
+    return this.schedule(
+        new command.Command(Command.SET_NETWORK_CONDITIONS).setParameter('network_conditions', spec),
+        'Driver.setNetworkConditions(' + JSON.stringify(spec) + ')');
+  }
 }
 
 

package/edge.js

@@ -278,8 +278,8 @@ class Driver extends webdriver.WebDriver {
         opt_config instanceof Options ? opt_config.toCapabilities() :
         (opt_config || capabilities.Capabilities.edge());
 
-    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
-        executor, caps, opt_flow, this, () => service.kill()));
+    return /** @type {!Driver} */(super.createSession(
+        executor, caps, opt_flow, () => service.kill()));
   }
 
   /**

package/example/async_await_test.js

@@ -0,0 +1,69 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+/**
+ * @fileoverview Example Mocha tests using async/await.
+ *
+ * Usage:
+ *
+ *     mocha -t 20000 --harmony_async_await \
+ *         selenium-webdriver/example/async_await_test.js
+ *
+ * You can change which browser is started with the SELENIUM_BROWSER environment
+ * variable:
+ *
+ *     SELENIUM_BROWSER=chrome \
+ *         mocha -t 20000 --harmony_async_await \
+ *         selenium-webdriver/example/async_await_test.js
+ */
+
+'use strict';
+
+const assert = require('assert');
+const {Builder, By, Key, promise, until} = require('..');
+
+// async/await do not work well when the promise manager is enabled.
+// See https://github.com/SeleniumHQ/selenium/issues/3037
+//
+// 3037 does not impact these specific examples, but it is still recommended
+// that you disable the promise manager when using async/await.
+promise.USE_PROMISE_MANAGER = false;
+
+describe('Google Search', function() {
+  let driver;
+
+  beforeEach(async function() {
+    driver = await new Builder().forBrowser('firefox').build();
+  });
+
+  afterEach(async function() {
+    await driver.quit();
+  });
+
+  it('example', async function() {
+    await driver.get('https://www.google.com/ncr');
+
+    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
+
+    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+
+    let url = await driver.getCurrentUrl();
+    assert.ok(
+        url.startsWith('https://www.google.com/search'),
+        'unexpected url: ' + url);
+  });
+});

package/example/chrome_android.js

@@ -23,7 +23,7 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, promise, until} = require('..');
 const {Options} = require('../chrome');
 
 promise.consume(function* () {
@@ -34,8 +34,7 @@ promise.consume(function* () {
         .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.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
     yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {
     yield driver && driver.quit();

package/example/chrome_mobile_emulation.js

@@ -22,7 +22,7 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, promise, until} = require('..');
 const {Options} = require('../chrome');
 
 promise.consume(function* () {
@@ -31,11 +31,10 @@ promise.consume(function* () {
     driver = yield new Builder()
         .forBrowser('chrome')
         .setChromeOptions(
-            new Options().setMobileEmulation({deviceName: 'Google Nexus 5'}))
+            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.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
     yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {
     yield driver && driver.quit();

package/example/firefox_channels.js

@@ -27,7 +27,7 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, promise, until} = require('..');
 const {Channel, Options} = require('../firefox');
 
 let i = 0;
@@ -45,8 +45,8 @@ function doSearch(driver) {
     .then(_ => promise.delayed(750))
     // Now do the rest.
     .then(_ => driver.get('http://www.google.com/ncr'))
-    .then(_ => driver.findElement(By.name('q')).sendKeys('webdriver'))
-    .then(_ => driver.findElement(By.name('btnG')).click())
+    .then(_ =>
+        driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN))
     .then(_ => driver.wait(until.titleIs('webdriver - Google Search'), 1000))
     .then(_ => driver.quit());
 }

package/example/google_search.js

@@ -37,14 +37,14 @@
  *     node selenium-webdriver/example/google_search.js
  */
 
-const {Builder, By, until} = require('..');
+const {Builder, By, Key, until} = require('..');
 
 var driver = new Builder()
     .forBrowser('firefox')
     .build();
 
 driver.get('http://www.google.com/ncr')
-    .then(_ => driver.findElement(By.name('q')).sendKeys('webdriver'))
-    .then(_ => driver.findElement(By.name('btnG')).click())
+    .then(_ =>
+        driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN))
     .then(_ => driver.wait(until.titleIs('webdriver - Google Search'), 1000))
     .then(_ => driver.quit());

package/example/google_search_generator.js

@@ -28,7 +28,7 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, promise, until} = require('..');
 
 promise.consume(function* () {
   let driver;
@@ -38,10 +38,7 @@ promise.consume(function* () {
     yield driver.get('http://www.google.com/ncr');
 
     let q = yield driver.findElement(By.name('q'));
-    yield q.sendKeys('webdriver');
-
-    let btnG = yield driver.findElement(By.name('btnG'));
-    yield btnG.click();
+    yield q.sendKeys('webdriver', Key.RETURN);
 
     yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   } finally {

package/example/google_search_test.js

@@ -29,7 +29,7 @@
  *         mocha -t 10000 selenium-webdriver/example/google_search_test.js
  */
 
-const {Builder, By, until} = require('..');
+const {Builder, By, Key, until} = require('..');
 const test = require('../testing');
 
 test.describe('Google Search', function() {
@@ -41,9 +41,9 @@ test.describe('Google Search', function() {
 
   // You can write tests either using traditional promises.
   it('works with promises', function() {
-    return driver.get('http://www.google.com')
-        .then(_ => driver.findElement(By.name('q')).sendKeys('webdriver'))
-        .then(_ => driver.findElement(By.name('btnG')).click())
+    return driver.get('http://www.google.com/ncr')
+        .then(_ =>
+            driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN))
         .then(_ => driver.wait(until.titleIs('webdriver - Google Search'), 1000));
   });
 
@@ -52,8 +52,7 @@ test.describe('Google Search', function() {
   // generator.
   test.it('works with generators', function*() {
     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.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
     yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
   });