selenium-webdriver 3.3.0 → 4.0.0-alpha.1

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,18 @@ 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, service = getDefaultService()) {
+    let client = service.start().then(url => new http.HttpClient(url));
+    let executor = new http.Executor(client);
 
-    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
-        executor, caps, opt_flow, this, () => service.kill()));
+    options = options || new Options();
+    return /** @type {!Driver} */(super.createSession(
+        executor, options, () => service.kill()));
   }
 
   /**
@@ -299,3 +223,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: '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.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/firefox_channels.js

@@ -27,28 +27,37 @@
 
 'use strict';
 
-const {Builder, By, promise, until} = require('..');
+const {Builder, By, Key, promise, until} = require('..');
 const {Channel, Options} = require('../firefox');
 
 let i = 0;
 function resposition(driver) {
-  return driver.manage().window().setSize(600, 400)
-      .then(_ => driver.manage().window().setPosition(300 * (i++), 0));
+  return driver.manage().window().setRect({
+    width: 600,
+    height: 400,
+    x: 300 * (i++),
+    y: 0
+  });
 }
 
-function doSearch(driver) {
-  // Start on the base about page.
-  return driver.get('about:')
+async function doSearch(driver) {
+  try {
+    // Start on the base about page.
+    await driver.get('about:')
     // Reposition so users can see the three windows.
-    .then(_ => resposition(driver))
+    await resposition(driver);
     // Pause so users can see the magic.
-    .then(_ => promise.delayed(750))
+    await 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.wait(until.titleIs('webdriver - Google Search'), 1000))
-    .then(_ => driver.quit());
+    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);
+    console.log('Success!');
+  } catch (ex) {
+    console.log('An error occured! ' + ex);
+  } finally {
+    await driver.quit();
+  }
 }
 
 function createDriver(channel) {
@@ -56,17 +65,12 @@ function createDriver(channel) {
   return new Builder().forBrowser('firefox').setFirefoxOptions(options).build();
 }
 
-// NOTE: disabling the promise manager so searches all run concurrently.
-// For more on the promise manager and its pending deprecation, see
-// https://github.com/SeleniumHQ/selenium/issues/2969
-promise.USE_PROMISE_MANAGER = false;
-
 Promise.all([
   doSearch(createDriver(Channel.RELEASE)),
   doSearch(createDriver(Channel.AURORA)),  // Developer Edition.
   doSearch(createDriver(Channel.NIGHTLY)),
 ]).then(_ => {
-  console.log('Success!');
+  console.log('All done!');
 }, err => {
   console.error('An error occured! ' + err);
   setTimeout(() => {throw err}, 0);

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_test.js

@@ -18,44 +18,56 @@
 /**
  * @fileoverview An example test that may be run using Mocha.
  *
+ * This example uses the `selenium-webdriver/testing.suite` function, which will
+ * automatically run tests against every available WebDriver browser on the
+ * current system. Alternatively, you may use the `SELENIUM_BROWSER`
+ * environment variable to narrow the scope at runtime.
+ *
  * Usage:
  *
+ *     # Automatically determine which browsers to run against.
  *     mocha -t 10000 selenium-webdriver/example/google_search_test.js
  *
- * You can change which browser is started with the SELENIUM_BROWSER environment
- * variable:
- *
+ *     # Configure tests to only run against Google Chrome.
  *     SELENIUM_BROWSER=chrome \
  *         mocha -t 10000 selenium-webdriver/example/google_search_test.js
  */
 
-const {Builder, By, until} = require('..');
-const test = require('../testing');
+const assert = require('assert');
 
-test.describe('Google Search', function() {
-  let driver;
+const {Browser, By, Key, until} = require('..');
+const {ignore, suite} = require('../testing');
 
-  test.before(function *() {
-    driver = yield new Builder().forBrowser('firefox').build();
-  });
+suite(function(env) {
+  describe('Google Search', function() {
+    let driver;
 
-  // 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())
-        .then(_ => driver.wait(until.titleIs('webdriver - Google Search'), 1000));
-  });
+    before(async function() {
+      // env.builder() returns a Builder instance preconfigured for the
+      // envrionment's target browser (you may still define browser specific
+      // options if necessary (i.e. firefox.Options or chrome.Options)).
+      driver = await env.builder().build();
+    });
 
-  // Or you can define the test as a generator function. The test will wait for
-  // any yielded promises to resolve before invoking the next step in the
-  // 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.wait(until.titleIs('webdriver - Google Search'), 1000);
-  });
+    it('demo', 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);
+    });
+
+    // The ignore function returns wrappers around describe & it that will
+    // suppress tests if the provided predicate returns true. You may provide
+    // any synchronous predicate. The env.browsers(...) function generates a
+    // predicate that will suppress tests if the  env targets one of the
+    // specified browsers.
+    //
+    // This example is always configured to skip Chrome.
+    ignore(env.browsers(Browser.CHROME)).it('demo 2', async function() {
+      await driver.get('http://www.google.com/ncr');
+      let url = await driver.getCurrentUrl();
+      assert.equal(url, 'https://www.google.com/');
+    });
 
-  test.after(() => driver.quit());
+    after(() => driver && driver.quit());
+  });
 });

package/example/headless.js

@@ -0,0 +1,55 @@
+// 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 or Firefox in headless mode.
+ *
+ * To run with Chrome, 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>
+ *
+ *     SELENIUM_BROWSER=chrome node selenium-webdriver/example/headless.js
+ *
+ * To run with Firefox, ensure you have Firefox 57+ installed and that
+ * geckodriver 0.19.0+ is present on your system PATH:
+ * <https://github.com/mozilla/geckodriver/releases>
+ *
+ *     SELENIUM_BROWSER=firefox node selenium-webdriver/example/headless.js
+ */
+
+const chrome = require('../chrome');
+const firefox = require('../firefox');
+const {Builder, By, Key, until} = require('..');
+
+const width = 640;
+const height = 480;
+
+let driver = new Builder()
+    .forBrowser('chrome')
+    .setChromeOptions(
+        new chrome.Options().headless().windowSize({width, height}))
+    .setFirefoxOptions(
+        new firefox.Options().headless().windowSize({width, height}))
+    .build();
+
+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))
+    .then(
+        _ => driver.quit(),
+        e => driver.quit().then(() => { throw e; }));

package/example/logging.js

@@ -21,15 +21,48 @@
 
 'use strict';
 
-const {Builder, By, logging, until} = require('..');
+const chrome = require('../chrome');
+const firefox = require('../firefox');
+const edge = require('../edge');
+const {Builder, By, Key, logging, until} = require('..');
 
 logging.installConsoleHandler();
 logging.getLogger('webdriver.http').setLevel(logging.Level.ALL);
 
-var driver = new Builder().forBrowser('firefox').build();
+(async function() {
+  let driver;
+  try {
+    driver = await new Builder()
+        // Default to using Firefox. This can be overridden at runtime by
+        // setting the SELENIUM_BROWSER environment variable:
+        //
+        //   SELENIUM_BROWSER=chrome node selenium-webdriver/example/logging.js
+        .forBrowser('firefox')
+        // Configure the service for each browser to enable verbose logging and
+        // to inherit the stdio settings from the current process. The builder
+        // will only start the service if needed for the selected browser.
+        .setChromeService(
+            new chrome.ServiceBuilder()
+                .enableVerboseLogging()
+                .setStdio('inherit'))
+        .setEdgeService(
+            process.platform === 'win32'
+                ? new edge.ServiceBuilder()
+                    .enableVerboseLogging()
+                    .setStdio('inherit')
+                : null)
+        .setFirefoxService(
+            new firefox.ServiceBuilder()
+                .enableVerboseLogging()
+                .setStdio('inherit'))
+        .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());
+    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 {
+    if (driver) {
+      await driver.quit();
+    }
+  }
+})();