selenium-webdriver 3.4.0 → 3.5.0

package/CHANGES.md

@@ -1,3 +1,31 @@
+## 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
@@ -17,7 +45,7 @@ This release requires [geckodriver 0.15.0](https://github.com/mozilla/geckodrive
 
 * 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 
+* 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.

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]                     |

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');
 
 
 /**
@@ -293,11 +307,7 @@ function getDefaultService() {
 }
 
 
-/**
- * @type {string}
- * @const
- */
-let OPTIONS_CAPABILITY_KEY = 'chromeOptions';
+const OPTIONS_CAPABILITY_KEY = 'chromeOptions';
 
 
 /**
@@ -362,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;
     }
@@ -394,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;
   }
 
@@ -716,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));
   }
 
   /**
@@ -737,7 +779,7 @@ 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
@@ -751,16 +793,16 @@ class Driver extends webdriver.WebDriver {
 
   /**
    * 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.

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/chrome_headless.js

@@ -0,0 +1,47 @@
+// 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 An example of running Chrome in headless mode.
+ *
+ * Before running this script, ensure you have Chrome 59+ installed and that
+ * chromedriver 2.30+ is present on your system PATH:
+ * <https://sites.google.com/a/chromium.org/chromedriver/downloads>
+ *
+ * Usage:
+ *   node selenium-webdriver/example/chrome_headless.js
+ */
+
+const chrome = require('../chrome');
+const {Builder, By, until} = require('..');
+
+const width = 640;
+const height = 480;
+
+let driver = new Builder()
+    .forBrowser('chrome')
+    .setChromeOptions(
+        new chrome.Options().headless().windowSize({width, height}))
+    .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.wait(until.titleIs('webdriver - Google Search'), 1000))
+    .then(
+        _ => driver.quit(),
+        e => driver.quit().then(() => { throw e; }));

package/example/chrome_mobile_emulation.js

@@ -31,7 +31,7 @@ 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');

package/firefox/extension.js

@@ -19,12 +19,12 @@
 
 'use strict';
 
-const AdmZip = require('adm-zip'),
-    fs = require('fs'),
+const fs = require('fs'),
     path = require('path'),
     xml = require('xml2js');
 
 const io = require('../io');
+const zip = require('../io/zip');
 
 
 /**
@@ -56,11 +56,7 @@ function install(extension, dir) {
       if (!details.unpack) {
         return io.copy(extension, dst + '.xpi').then(() => details.id);
       } else {
-        return Promise.resolve().then(function() {
-          // TODO: find an async library for inflating a zip archive.
-          new AdmZip(extension).extractAllTo(dst, true);
-          return details.id;
-        });
+        return zip.unzip(extension, dst).then(() => details.id);
       }
     } else {
       return io.copyDir(extension, dst).then(() => details.id);
@@ -79,105 +75,146 @@ var AddonDetails;
 var RdfRoot;
 
 
-
 /**
  * Extracts the details needed to install an add-on.
  * @param {string} addonPath Path to the extension directory.
  * @return {!Promise<!AddonDetails>} A promise for the add-on details.
  */
 function getDetails(addonPath) {
-  return readManifest(addonPath).then(function(doc) {
-    var em = getNamespaceId(doc, 'http://www.mozilla.org/2004/em-rdf#');
-    var rdf = getNamespaceId(
-        doc, 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
-
-    var description = doc[rdf + 'RDF'][rdf + 'Description'][0];
-    var details = {
-      id: getNodeText(description, em + 'id'),
-      name: getNodeText(description, em + 'name'),
-      version: getNodeText(description, em + 'version'),
-      unpack: getNodeText(description, em + 'unpack') || false
-    };
-
-    if (typeof details.unpack === 'string') {
-      details.unpack = details.unpack.toLowerCase() === 'true';
+  return io.stat(addonPath).then((stats) => {
+    if (stats.isDirectory()) {
+      return parseDirectory(addonPath);
+    } else if (addonPath.slice(-4) === '.xpi') {
+      return parseXpiFile(addonPath);
+    } else {
+      throw Error('Add-on path is not an xpi or a directory: ' + addonPath);
     }
+  });
 
-    if (!details.id) {
-      throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
-    }
+  /**
+   * Parse an install.rdf for a Firefox add-on.
+   * @param {string} rdf The contents of install.rdf for the add-on.
+   * @return {!Promise<!AddonDetails>} A promise for the add-on details.
+   */
+  function parseInstallRdf(rdf) {
+    return parseXml(rdf).then(function(doc) {
+      var em = getNamespaceId(doc, 'http://www.mozilla.org/2004/em-rdf#');
+      var rdf = getNamespaceId(
+          doc, 'http://www.w3.org/1999/02/22-rdf-syntax-ns#');
+
+      var description = doc[rdf + 'RDF'][rdf + 'Description'][0];
+      var details = {
+        id: getNodeText(description, em + 'id'),
+        name: getNodeText(description, em + 'name'),
+        version: getNodeText(description, em + 'version'),
+        unpack: getNodeText(description, em + 'unpack') || false
+      };
+
+      if (typeof details.unpack === 'string') {
+        details.unpack = details.unpack.toLowerCase() === 'true';
+      }
 
-    return details;
-  });
+      if (!details.id) {
+        throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
+      }
 
-  function getNodeText(node, name) {
-    return node[name] && node[name][0] || '';
-  }
+      return details;
+    });
 
-  function getNamespaceId(doc, url) {
-    var keys = Object.keys(doc);
-    if (keys.length !== 1) {
-      throw new AddonFormatError('Malformed manifest for add-on ' + addonPath);
+    function parseXml(text) {
+      return new Promise((resolve, reject) => {
+        xml.parseString(text, (err, data) => {
+          if (err) {
+            reject(err);
+          } else {
+            resolve(data);
+          }
+        });
+      });
     }
 
-    var namespaces = /** @type {!RdfRoot} */(doc[keys[0]]).$;
-    var id = '';
-    Object.keys(namespaces).some(function(ns) {
-      if (namespaces[ns] !== url) {
-        return false;
-      }
+    function getNodeText(node, name) {
+      return node[name] && node[name][0] || '';
+    }
 
-      if (ns.indexOf(':') != -1) {
-        id = ns.split(':')[1] + ':';
+    function getNamespaceId(doc, url) {
+      var keys = Object.keys(doc);
+      if (keys.length !== 1) {
+        throw new AddonFormatError('Malformed manifest for add-on ' + addonPath);
       }
-      return true;
-    });
-    return id;
-  }
-}
 
+      var namespaces = /** @type {!RdfRoot} */(doc[keys[0]]).$;
+      var id = '';
+      Object.keys(namespaces).some(function(ns) {
+        if (namespaces[ns] !== url) {
+          return false;
+        }
 
-/**
- * Reads the manifest for a Firefox add-on.
- * @param {string} addonPath Path to a Firefox add-on as a xpi or an extension.
- * @return {!Promise<!Object>} A promise for the parsed manifest.
- */
-function readManifest(addonPath) {
-  var manifest;
+        if (ns.indexOf(':') != -1) {
+          id = ns.split(':')[1] + ':';
+        }
+        return true;
+      });
+      return id;
+    }
+  }
+
+  /**
+   * Parse a manifest for a Firefox WebExtension.
+   * @param {{
+   *   name: string,
+   *   version: string,
+   *   applications: {gecko:{id:string}}
+   * }} json JSON representation of the manifest.
+   * @return {!AddonDetails} The add-on details.
+   */
+  function parseManifestJson({name, version, applications}) {
+    if (!(applications && applications.gecko && applications.gecko.id)) {
+      throw new AddonFormatError('Could not find add-on ID for ' + addonPath);
+    }
 
-  if (addonPath.slice(-4) === '.xpi') {
-    manifest = new Promise((resolve, reject) => {
-      let zip = new AdmZip(addonPath);
+    return {id: applications.gecko.id, name, version, unpack: false};
+  }
 
-      if (!zip.getEntry('install.rdf')) {
-        reject(new AddonFormatError(
-            'Could not find install.rdf in ' + addonPath));
-        return;
+  function parseXpiFile(filePath) {
+    return zip.load(filePath).then(archive => {
+      if (archive.has('install.rdf')) {
+        return archive.getFile('install.rdf')
+            .then(buf => parseInstallRdf(buf.toString('utf8')));
       }
 
-      zip.readAsTextAsync('install.rdf', resolve);
-    });
-  } else {
-    manifest = io.stat(addonPath).then(function(stats) {
-      if (!stats.isDirectory()) {
-        throw Error(
-            'Add-on path is neither a xpi nor a directory: ' + addonPath);
+      if (archive.has('manifest.json')) {
+        return archive.getFile('manifest.json')
+            .then(buf => JSON.parse(buf.toString('utf8')))
+            .then(parseManifestJson);
       }
-      return io.read(path.join(addonPath, 'install.rdf'));
+
+      throw new AddonFormatError(
+          `Couldn't find install.rdf or manifest.json in ${filePath}`);
     });
   }
 
-  return manifest.then(function(content) {
-    return new Promise((resolve, reject) => {
-      xml.parseString(content, (err, data) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve(data);
-        }
-      });
-    });
-  });
+  function parseDirectory(dirPath) {
+    const rdfPath = path.join(dirPath, 'install.rdf');
+    const jsonPath = path.join(dirPath, 'manifest.json');
+    return io.exists(rdfPath)
+        .then(rdfExists => {
+          if (rdfExists) {
+            return io.read(rdfPath)
+                .then(buf => parseInstallRdf(buf.toString('utf8')));
+          }
+          return io.exists(jsonPath)
+              .then(jsonExists => {
+                if (jsonExists) {
+                  return io.read(jsonPath)
+                      .then(buf => JSON.parse(buf.toString('utf8')))
+                      .then(parseManifestJson);
+                }
+                throw new AddonFormatError(
+                    `Couldn't find install.rdf or manifest.json in ${dirPath}`);
+              });
+        })
+  }
 }