selenium-webdriver 3.0.0-beta-1 → 3.0.1

package/example/google_search_generator.js

@@ -18,28 +18,33 @@
 /**
  * @fileoverview An example WebDriver script using generator functions.
  *
- * Usage: node selenium-webdriver/example/google_search_generator.js
+ * Before running this script, ensure that Mozilla's geckodriver is present on
+ * your system PATH: <https://github.com/mozilla/geckodriver/releases>
+ *
+ * Usage:
+ *
+ *     node selenium-webdriver/example/google_search_generator.js
  */
 
-var webdriver = require('..'),
-    By = webdriver.By;
+'use strict';
+
+const {Builder, By, promise, until} = require('..');
 
-var driver = new webdriver.Builder()
-    .forBrowser('firefox')
-    .build();
+promise.consume(function* () {
+  let driver;
+  try {
+    driver = yield new Builder().forBrowser('firefox').build();
 
-driver.get('http://www.google.com/ncr');
-driver.call(function* () {
-  var query = yield driver.findElement(By.name('q'));
-  query.sendKeys('webdriver');
+    yield driver.get('http://www.google.com/ncr');
 
-  var submit = yield driver.findElement(By.name('btnG'));
-  submit.click();
-});
+    let q = yield driver.findElement(By.name('q'));
+    yield q.sendKeys('webdriver');
 
-driver.wait(function* () {
-  var title = yield driver.getTitle();
-  return 'webdriver - Google Search' === title;
-}, 1000);
+    let btnG = yield driver.findElement(By.name('btnG'));
+    yield btnG.click();
 
-driver.quit();
+    yield driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+  } finally {
+    yield driver && driver.quit();
+  }
+}).then(_ => console.log('SUCCESS'), err => console.error('ERROR: ' + err));

package/example/google_search_test.js

@@ -17,31 +17,45 @@
 
 /**
  * @fileoverview An example test that may be run using Mocha.
- * Usage: mocha -t 10000 selenium-webdriver/example/google_search_test.js
+ *
+ * Usage:
+ *
+ *     mocha -t 10000 selenium-webdriver/example/google_search_test.js
+ *
+ * You can change which browser is started with the SELENIUM_BROWSER environment
+ * variable:
+ *
+ *     SELENIUM_BROWSER=chrome \
+ *         mocha -t 10000 selenium-webdriver/example/google_search_test.js
  */
 
-var webdriver = require('..'),
-    By = webdriver.By,
-    until = webdriver.until,
-    test = require('../testing');
+const {Builder, By, until} = require('..');
+const test = require('../testing');
 
 test.describe('Google Search', function() {
-  var driver;
+  let driver;
 
-  test.before(function() {
-    driver = new webdriver.Builder()
-        .forBrowser('firefox')
-        .build();
+  test.before(function *() {
+    driver = yield new Builder().forBrowser('firefox').build();
   });
 
-  test.it('should append query to title', function() {
-    driver.get('http://www.google.com');
-    driver.findElement(By.name('q')).sendKeys('webdriver');
-    driver.findElement(By.name('btnG')).click();
-    driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+  // 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));
   });
 
-  test.after(function() {
-    driver.quit();
+  // 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);
   });
+
+  test.after(() => driver.quit());
 });

package/example/logging.js

@@ -21,23 +21,15 @@
 
 'use strict';
 
-var webdriver = require('..'),
-    By = webdriver.By,
-    until = webdriver.until;
+const {Builder, By, logging, until} = require('..');
 
-webdriver.logging.installConsoleHandler();
-webdriver.logging.getLogger('webdriver.http')
-    .setLevel(webdriver.logging.Level.ALL);
+logging.installConsoleHandler();
+logging.getLogger('webdriver.http').setLevel(logging.Level.ALL);
 
-var driver = new webdriver.Builder()
-    .forBrowser('firefox')
-    .build();
+var driver = new Builder().forBrowser('firefox').build();
 
-driver.get('http://www.google.com/ncr');
-
-var searchBox = driver.wait(until.elementLocated(By.name('q')), 3000);
-searchBox.sendKeys('webdriver');
-
-driver.findElement(By.name('btnG')).click();
-driver.wait(until.titleIs('webdriver - Google Search'), 1000);
-driver.quit();
+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());

package/example/parallel_flows.js

@@ -18,6 +18,9 @@
 /**
  * @fileoverview An example of starting multiple WebDriver clients that run
  * in parallel in separate control flows.
+ *
+ * This example will only work when the promise manager is enabled
+ * (see <https://github.com/SeleniumHQ/selenium/issues/2969>).
  */
 
 var webdriver = require('..'),

package/firefox/binary.js

@@ -181,6 +181,15 @@ class Binary {
     this.devEdition_ = false;
   }
 
+  /**
+   * @return {(string|undefined)} The path to the Firefox executable to use, or
+   *     `undefined` if WebDriver should attempt to locate Firefox automatically
+   *     on the current system.
+   */
+  getExe() {
+    return this.exe_;
+  }
+
   /**
    * Add arguments to the command line used to start Firefox.
    * @param {...(string|!Array.<string>)} var_args Either the arguments to add
@@ -196,6 +205,14 @@ class Binary {
     }
   }
 
+  /**
+   * @return {!Array<string>} The command line arguments to use when starting
+   *     the browser.
+   */
+  getArguments() {
+    return this.args_;
+  }
+
   /**
    * Specifies whether to use Firefox Developer Edition instead of the normal
    * stable channel. Setting this option has no effect if this instance was

package/firefox/index.js

@@ -305,30 +305,6 @@ function findGeckoDriver() {
 }
 
 
-/**
- * @param {(string|!Binary)} binary .
- * @return {!remote.DriverService} .
- */
-function createGeckoDriverService(binary) {
-  let exe = typeof binary === 'string' ?
-    Promise.resolve(binary) : binary.locate();
-
-  let geckoDriver = findGeckoDriver();
-  let port =  portprober.findFreePort();
-  let marionettePort = portprober.findFreePort();
-  return new remote.DriverService(geckoDriver, {
-    loopback: true,
-    port: port,
-    args: Promise.all([exe, port, marionettePort]).then(args => {
-      return ['-b', args[0],
-              '--port', args[1],
-              '--marionette-port', args[2]];
-    })
-    // ,stdio: 'inherit'
-  });
-}
-
-
 /**
  * @param {(Profile|string)} profile The profile to prepare.
  * @param {number} port The port the FirefoxDriver should listen on.
@@ -420,29 +396,210 @@ function configureExecutor(executor) {
 }
 
 
+/**
+ * Creates {@link selenium-webdriver/remote.DriverService} instances that manage
+ * a [geckodriver](https://github.com/mozilla/geckodriver) server in a child
+ * process.
+ */
+class ServiceBuilder extends remote.DriverService.Builder {
+  /**
+   * @param {string=} opt_exe Path to the server executable to use. If omitted,
+   *     the builder will attempt to locate the geckodriver on the system PATH.
+   */
+  constructor(opt_exe) {
+    super(opt_exe || findGeckoDriver());
+    this.setLoopback(true);  // Required.
+  }
+
+  /**
+   * Enables verbose logging.
+   *
+   * @param {boolean=} opt_trace Whether to enable trace-level logging. By
+   *     default, only debug logging is enabled.
+   * @return {!ServiceBuilder} A self reference.
+   */
+  enableVerboseLogging(opt_trace) {
+    return this.addArguments(opt_trace ? '-vv' : '-v');
+  }
+
+  /**
+   * Sets the path to the executable Firefox binary that the geckodriver should
+   * use. If this method is not called, this builder will attempt to locate
+   * Firefox in the default installation location for the current platform.
+   *
+   * @param {(string|!Binary)} binary Path to the executable Firefox binary to use.
+   * @return {!ServiceBuilder} A self reference.
+   * @see Binary#locate()
+   */
+  setFirefoxBinary(binary) {
+    let exe = typeof binary === 'string'
+        ? Promise.resolve(binary) : binary.locate();
+    return this.addArguments('-b', exe);
+  }
+}
+
+
+/**
+ * @typedef {{executor: !command.Executor,
+ *            capabilities: (!capabilities.Capabilities|
+ *                           {desired: (capabilities.Capabilities|undefined),
+ *                            required: (capabilities.Capabilities|undefined)}),
+ *            onQuit: function(this: void): ?}}
+ */
+var DriverSpec;
+
+
+/**
+ * @param {(http.Executor|remote.DriverService|undefined)} executor
+ * @param {!capabilities.Capabilities} caps
+ * @param {Profile} profile
+ * @param {Binary} binary
+ * @return {DriverSpec}
+ */
+function createGeckoDriver(executor, caps, profile, binary) {
+  let firefoxOptions = {};
+  caps.set('moz:firefoxOptions', firefoxOptions);
+
+  if (binary) {
+    if (binary.getExe()) {
+      firefoxOptions['binary'] = binary.getExe();
+    }
+
+    let args = binary.getArguments();
+    if (args.length) {
+      firefoxOptions['args'] = args;
+    }
+  }
+
+  if (profile) {
+    // If the user specified a template directory or any extensions to install,
+    // we need to encode the profile as a base64 string (which requires writing
+    // it to disk first). Otherwise, if the user just specified some custom
+    // preferences, we can send those directly.
+    if (profile.getTemplateDir() || profile.getExtensions().length) {
+      firefoxOptions['profile'] = profile.encode();
+
+    } else {
+      let prefs = profile.getPreferences();
+      if (Object.keys(prefs).length) {
+        firefoxOptions['prefs'] = prefs;
+      }
+    }
+  }
+
+  let sessionCaps = caps;
+  if (caps.has(capabilities.Capability.PROXY)) {
+    let proxy = normalizeProxyConfiguration(
+        caps.get(capabilities.Capability.PROXY));
+
+    // Marionette requires proxy settings to be specified as required
+    // capabilities. See mozilla/geckodriver#97
+    let required = new capabilities.Capabilities()
+        .set(capabilities.Capability.PROXY, proxy);
+
+    caps.delete(capabilities.Capability.PROXY);
+    sessionCaps = {required, desired: caps};
+  }
+
+  /** @type {!command.Executor} */
+  let cmdExecutor;
+  let onQuit = function() {};
+
+  if (executor instanceof http.Executor) {
+    configureExecutor(executor);
+    cmdExecutor = executor;
+  } else if (executor instanceof remote.DriverService) {
+    cmdExecutor = createExecutor(executor.start());
+    onQuit = () => executor.kill();
+  } else {
+    let builder = new ServiceBuilder();
+    if (binary) {
+      builder.setFirefoxBinary(binary);
+    }
+    let service = builder.build();
+    cmdExecutor = createExecutor(service.start());
+    onQuit = () => service.kill();
+  }
+
+  return {
+    executor: cmdExecutor,
+    capabilities: sessionCaps,
+    onQuit
+  };
+}
+
+
+/**
+ * @param {!capabilities.Capabilities} caps
+ * @param {Profile} profile
+ * @param {!Binary} binary
+ * @return {DriverSpec}
+ */
+function createLegacyDriver(caps, profile, binary, flow) {
+  profile = profile || new Profile;
+
+  let freePort = portprober.findFreePort();
+  let preparedProfile =
+      freePort.then(port => prepareProfile(profile, port));
+  let command = preparedProfile.then(dir => binary.launch(dir));
+
+  let serverUrl = command.then(() => freePort)
+      .then(function(/** number */port) {
+        let serverUrl = url.format({
+          protocol: 'http',
+          hostname: net.getLoopbackAddress(),
+          port: port + '',
+          pathname: '/hub'
+        });
+        let ready = httpUtil.waitForServer(serverUrl, 45 * 1000);
+        return ready.then(() => serverUrl);
+      });
+
+  return {
+    executor: createExecutor(serverUrl),
+    capabilities: caps,
+    onQuit: function() {
+      return command.then(command => {
+        command.kill();
+        return preparedProfile.then(io.rmDir)
+            .then(() => command.result(),
+                  () => command.result());
+      });
+    }
+  };
+}
+
+
 /**
  * A WebDriver client for Firefox.
  */
 class Driver extends webdriver.WebDriver {
   /**
+   * Creates a new Firefox session.
+   *
    * @param {(Options|capabilities.Capabilities|Object)=} opt_config The
    *    configuration options for this driver, specified as either an
    *    {@link Options} or {@link capabilities.Capabilities}, or as a raw hash
    *    object.
-   * @param {promise.ControlFlow=} opt_flow The flow to
-   *     schedule commands through. Defaults to the active flow object.
-   * @param {http.Executor=} opt_executor A pre-configured command executor to
-   *     use for communicating with an externally managed remoted end (which is
-   *     assumed to already be running). The provided executor should not be
-   *     reused with other clients as its internal command mappings will be
-   *     updated to support Firefox-specific commands.
+   * @param {(http.Executor|remote.DriverService)=} opt_executor Either a
+   *   pre-configured command executor to use for communicating with an
+   *   externally managed remote end (which is assumed to already be running),
+   *   or the `DriverService` to use to start the geckodriver in a child
+   *   process.
    *
-   * _This parameter may only be used with Mozilla's GeckoDriver._
+   *   If an executor is provided, care should e taken not to use reuse it with
+   *   other clients as its internal command mappings will be updated to support
+   *   Firefox-specific commands.
    *
+   *   _This parameter may only be used with Mozilla's GeckoDriver._
+   *
+   * @param {promise.ControlFlow=} opt_flow The flow to
+   *     schedule commands through. Defaults to the active flow object.
    * @throws {Error} If a custom command executor is provided and the driver is
    *     configured to use the legacy FirefoxDriver from the Selenium project.
+   * @return {!Driver} A new driver instance.
    */
-  constructor(opt_config, opt_flow, opt_executor) {
+  static createSession(opt_config, opt_executor, opt_flow) {
     let caps;
     if (opt_config instanceof Options) {
       caps = opt_config.toCapabilities();
@@ -462,8 +619,6 @@ class Driver extends webdriver.WebDriver {
       caps.delete(Capability.PROFILE);
     }
 
-    let serverUrl, onQuit;
-
     // Users must now explicitly disable marionette to use the legacy
     // FirefoxDriver.
     let noMarionette =
@@ -471,78 +626,19 @@ class Driver extends webdriver.WebDriver {
             || /^0|false$/i.test(process.env['SELENIUM_MARIONETTE']);
     let useMarionette = !noMarionette;
 
+    let spec;
     if (useMarionette) {
-      if (opt_executor) {
-        configureExecutor(opt_executor);
-        serverUrl = Promise.reject(Error('unexpected variable use'));
-        onQuit = function noop() {};
-      } else {
-        let service = createGeckoDriverService(binary);
-        serverUrl = service.start();
-        onQuit = () => service.kill();
-      }
-
-      if (profile) {
-        caps.set(Capability.PROFILE, profile.encode());
-      }
-
-      if (caps.has(capabilities.Capability.PROXY)) {
-        let proxy = normalizeProxyConfiguration(
-            caps.get(capabilities.Capability.PROXY));
-
-        // Marionette requires proxy settings to be specified as required
-        // capabilities. See mozilla/geckodriver#97
-        let required = new capabilities.Capabilities()
-            .set(capabilities.Capability.PROXY, proxy);
-
-        caps.delete(capabilities.Capability.PROXY);
-        caps = {required, desired: caps};
-      }
+      spec = createGeckoDriver(opt_executor, caps, profile, binary);
     } else {
       if (opt_executor) {
         throw Error('You may not use a custom command executor with the legacy'
             + ' FirefoxDriver');
       }
-
-      profile = profile || new Profile;
-
-      let freePort = portprober.findFreePort();
-      let preparedProfile =
-          freePort.then(port => prepareProfile(profile, port));
-      let command = preparedProfile.then(dir => binary.launch(dir));
-
-      serverUrl = command.then(() => freePort)
-          .then(function(/** number */port) {
-            let serverUrl = url.format({
-              protocol: 'http',
-              hostname: net.getLoopbackAddress(),
-              port: port + '',
-              pathname: '/hub'
-            });
-            let ready = httpUtil.waitForServer(serverUrl, 45 * 1000);
-            return ready.then(() => serverUrl);
-          });
-
-      onQuit = function() {
-        return command.then(command => {
-          command.kill();
-          return preparedProfile.then(io.rmDir)
-              .then(() => command.result(),
-                    () => command.result());
-        });
-      };
+      spec = createLegacyDriver(caps, profile, binary, opt_flow);
     }
 
-    let executor = opt_executor || createExecutor(serverUrl);
-    let driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
-    super(driver.getSession(), executor, driver.controlFlow());
-
-    let boundQuit = this.quit.bind(this);
-
-    /** @override */
-    this.quit = function() {
-      return boundQuit().finally(onQuit);
-    };
+    return /** @type {!Driver} */(webdriver.WebDriver.createSession(
+        spec.executor, spec.capabilities, opt_flow, this, spec.onQuit));
   }
 
   /**
@@ -556,7 +652,7 @@ class Driver extends webdriver.WebDriver {
   /**
    * Get the context that is currently in effect.
    *
-   * @return {!promise.Promise<Context>} Current context.
+   * @return {!promise.Thenable<Context>} Current context.
    */
   getContext() {
     return this.schedule(
@@ -576,7 +672,7 @@ class Driver extends webdriver.WebDriver {
    *
    * Use your powers wisely.
    *
-   * @param {!promise.Promise<void>} ctx The context to switch to.
+   * @param {!promise.Thenable<void>} ctx The context to switch to.
    */
   setContext(ctx) {
     return this.schedule(
@@ -595,3 +691,4 @@ exports.Context = Context;
 exports.Driver = Driver;
 exports.Options = Options;
 exports.Profile = Profile;
+exports.ServiceBuilder = ServiceBuilder;

package/firefox/profile.js

@@ -201,9 +201,6 @@ class Profile {
     /** @private {!Object} */
     this.preferences_ = {};
 
-    Object.assign(this.preferences_, getDefaultPreferences()['mutable']);
-    Object.assign(this.preferences_, getDefaultPreferences()['frozen']);
-
     /** @private {boolean} */
     this.nativeEventsEnabled_ = true;
 
@@ -217,6 +214,14 @@ class Profile {
     this.extensions_ = [];
   }
 
+  /**
+   * @return {(string|undefined)} Path to an existing Firefox profile directory
+   *     to use as a template when writing this Profile to disk.
+   */
+  getTemplateDir() {
+    return this.template_;
+  }
+
   /**
    * Registers an extension to be included with this profile.
    * @param {string} extension Path to the extension to include, as either an
@@ -226,6 +231,13 @@ class Profile {
     this.extensions_.push(extension);
   }
 
+  /**
+   * @return {!Array<string>} A list of extensions to install in this profile.
+   */
+  getExtensions() {
+    return this.extensions_;
+  }
+
   /**
    * Sets a desired preference for this profile.
    * @param {string} key The preference key.
@@ -254,6 +266,13 @@ class Profile {
     return this.preferences_[key];
   }
 
+  /**
+   * @return {!Object} A copy of all currently configured preferences.
+   */
+  getPreferences() {
+    return Object.assign({}, this.preferences_);
+  }
+
   /**
    * Specifies which host the driver should listen for commands on. If not
    * specified, the driver will default to "localhost". This option should be
@@ -353,6 +372,8 @@ class Profile {
 
     // Freeze preferences for async operations.
     var prefs = {};
+    Object.assign(prefs, getDefaultPreferences()['mutable']);
+    Object.assign(prefs, getDefaultPreferences()['frozen']);
     Object.assign(prefs, this.preferences_);
 
     // Freeze extensions for async operations.