* Add more options to the Builder API (every common, settable capabil…

…ity should be covered).

* Require calling Builder.usingServer(url) to use a remote server. If this is not called, the
builder will attempt to create a client locally, throwing an error if it can't (e.g. for IE).
* Add browser specific constructors to simplify creating a client without the Builder.

Fixes issue 7593

javascript/node/selenium-webdriver/CHANGES.md

@@ -4,7 +4,23 @@
     `ControlFlow#wait`. For more information, see documentation on
     `webdriver.promise.consume`. Requires harmony support (run with
     `node --harmony-generators` in `v0.11.x`).
-* Added `Builder#setLoggingPreferences()`
+* Various improvements to the `Builder` API. Notably, the `build()` function
+    will no longer default to attempting to use a server at
+    `http://localhost:4444/wd/hub` if it cannot start a browser directly -
+    you must specify the WebDriver server with `usingServer(url)`. You can
+    also set the target browser and WebDriver server through a pair of
+    environment variables. See the documentation on the `Builder` constructor
+    for more information.
+* For consistency with the other language bindings, added browser specific
+    classes that can be used to start a browser without the builder.
+
+        var webdriver = require('selenium-webdriver')
+            chrome = require('selenium-webdriver/chrome');
+
+        // The following are equivalent.
+        var driver1 = new webdriver.Builder().forBrowser('chrome').build();
+        var driver2 = new chrome.Driver();
+
 * Promise A+ compliance: a promise may no longer resolve to itself.
 * For consistency with other language bindings, deprecated
     `UnhandledAlertError#getAlert` and added `#getAlertText`.

javascript/node/selenium-webdriver/builder.js

@@ -15,77 +15,206 @@
 var base = require('./_base'),
     executors = require('./executors');
 
-var goog = base.require('goog'),
-    AbstractBuilder = base.require('webdriver.AbstractBuilder'),
-    Browser = base.require('webdriver.Browser'),
+// Use base.require to avoid circular references between index and this module.
+var Browser = base.require('webdriver.Browser'),
+    Capabilities = base.require('webdriver.Capabilities'),
     Capability = base.require('webdriver.Capability'),
     WebDriver = base.require('webdriver.WebDriver'),
     promise = base.require('webdriver.promise');
 
 
+
 /**
- * @param {!webdriver.Capabilities} capabilities The desired capabilities.
- * @param {webdriver.promise.ControlFlow} flow The control flow to use, or
- *     {@code null} to use the currently active flow.
- * @return {webdriver.WebDriver} A new WebDriver instance or {@code null}
- *     if the requested browser is not natively supported in Node.
+ * Creates new {@link webdriver.WebDriver WebDriver} instances. The environment
+ * variables listed below may be used to override a builder's configuration,
+ * allowing quick runtime changes.
+ * <ul>
+ * <li>{@code SELENIUM_REMOTE_URL}: defines the remote URL for all builder
+ *   instances. This environment variable should be set to a fully qualified
+ *   URL for a WebDriver server (e.g. http://localhost:4444/wd/hub).
+ *
+ * <li>{@code SELENIUM_BROWSER}: defines the target browser in the form
+ *   {@code browser[:version][:platform]}.
+ * </ul>
+ *
+ * <p>Suppose you had mytest.js that created WebDriver with
+ *     {@code var driver = new webdriver.Builder().build();}.
+ *
+ * This test could be made to use Firefox on the local machine by running with
+ * {@code SELENIUM_BROWSER=firefox node mytest.js}.
+ *
+ * <p>Alternatively, you could request Chrome 36 on Linux from a remote
+ * server with {@code
+ *     SELENIUM_BROWSER=chrome:36:LINUX
+ *     SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub
+ *     node mytest.js}.
+ *
+ * @constructor
  */
-function createNativeDriver(capabilities, flow) {
-  switch (capabilities.get(Capability.BROWSER_NAME)) {
-    case Browser.CHROME:
-      // Requiring 'chrome' above would create a cycle:
-      // index -> builder -> chrome -> index
-      var chrome = require('./chrome');
-      return chrome.createDriver(capabilities, null, flow);
+var Builder = function() {
 
-    case Browser.PHANTOM_JS:
-      // Requiring 'phantomjs' would create a cycle:
-      // index -> builder -> phantomjs -> index
-      var phantomjs = require('./phantomjs');
-      return phantomjs.createDriver(capabilities, flow);
+  /** @private {webdriver.promise.ControlFlow} */
+  this.flow_ = null;
 
-    default:
-      return null;
-  }
-}
+  /** @private {string} */
+  this.url_ = '';
+
+  /** @private {!webdriver.Capabilities} */
+  this.capabilities_ = new Capabilities();
 
+  /** @private {chrome.Options} */
+  this.chromeOptions_ = null;
+};
 
 
 /**
- * Creates new {@link webdriver.WebDriver WebDriver} instances.
- * @constructor
- * @extends {webdriver.AbstractBuilder}
+ * Sets the URL of a remote WebDriver server to use. Once a remote URL has been
+ * specified, the builder direct all new clients to that server. If this method
+ * is never called, the Builder will attempt to create all clients locally.
+ *
+ * <p>As an alternative to this method, you may also set the
+ * {@code SELENIUM_REMOTE_URL} environment variable.
+ *
+ * @param {string} url The URL of a remote server to use.
+ * @return {!Builder} A self reference.
  */
-var Builder = function() {
-  goog.base(this);
+Builder.prototype.usingServer = function(url) {
+  this.url_ = url;
+  return url;
+};
 
-  /** @private {webdriver.promise.ControlFlow} */
-  this.flow_ = null;
+
+/**
+ * @return {string} The URL of the WebDriver server this instance is configured
+ *     to use.
+ */
+Builder.prototype.getServerUrl = function() {
+  return this.url_;
+};
+
+
+/**
+ * Sets the desired capabilities when requesting a new session. This will
+ * overwrite any previously set capabilities.
+ * @param {!(Object|webdriver.Capabilities)} capabilities The desired
+ *     capabilities for a new session.
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.withCapabilities = function(capabilities) {
+  this.capabilities_ = new Capabilities(capabilities);
+  return this;
+};
+
+
+/**
+ * Returns the base set of capabilities this instance is currently configured
+ * to use.
+ * @return {!webdriver.Capabilities} The current capabilities for this builder.
+ */
+Builder.prototype.getCapabilities = function() {
+  return this.capabilities_;
+};
+
+
+/**
+ * Configures the target browser for clients created by this instance.
+ * Any calls to {@link #withCapabilities} after this function will
+ * overwrite these settings.
+ *
+ * <p>You may also define the target browser using the {@code SELENIUM_BROWSER}
+ * environment variable. If set, this environment variable should be of the
+ * form {@code browser[:[version][:platform]]}.
+ *
+ * @param {(string|webdriver.Browser)} name The name of the target browser;
+ *     common defaults are available on the {@link webdriver.Browser} enum.
+ * @param {string=} opt_version A desired version; may be omitted if any
+ *     version should be used.
+ * @param {string=} opt_platform The desired platform; may be omitted if any
+ *     version may be used.
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.forBrowser = function(name, opt_version, opt_platform) {
+  this.capabilities_.set(Capability.BROWSER_NAME, name);
+  this.capabilities_.set(Capability.VERSION, opt_version || null);
+  this.capabilities_.set(Capability.PLATFORM, opt_platform || null);
+  return this;
 };
-goog.inherits(Builder, AbstractBuilder);
 
 
 /**
  * Sets the proxy configuration to use for WebDriver clients created by this
  * builder. Any calls to {@link #withCapabilities} after this function will
  * overwrite these settings.
- * @param {!proxy.ProxyConfig} config The configuration to use.
+ * @param {!webdriver.ProxyConfig} config The configuration to use.
  * @return {!Builder} A self reference.
  */
 Builder.prototype.setProxy = function(config) {
-  this.getCapabilities().set(Capability.PROXY, config);
+  this.capabilities_.setProxy(config);
+  return this;
+};
+
+
+/**
+ * Sets the logging preferences for the created session. Preferences may be
+ * changed by repeated calls, or by calling {@link #withCapabilities}.
+ * @param {!(webdriver.logging.Preferences|Object.<string, string>)} prefs The
+ *     desired logging preferences.
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.setLoggingPrefs = function(prefs) {
+  this.capabilities_.setLoggingPrefs(prefs);
+  return this;
+};
+
+
+/**
+ * Sets whether native events should be used.
+ * @param {boolean} enabled Whether to enable native events.
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.setEnableNativeEvents = function(enabled) {
+  this.capabilities_.setEnableNativeEvents(enabled);
+  return this;
+};
+
+
+/**
+ * Sets how elements should be scrolled into view for interaction.
+ * @param {number} behavior The desired scroll behavior: either 0 to align with
+ *     the top of the viewport or 1 to align with the bottom.
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.setScrollBehavior = function(behavior) {
+  this.capabilities_.setScrollBehavior(behavior);
+  return this;
+};
+
+
+/**
+ * Sets the default action to take with an unexpected alert before returning
+ * an error.
+ * @param {string} beahvior The desired behavior; should be "accept", "dismiss",
+ *     or "ignore". Defaults to "dismiss".
+ * @return {!Builder} A self reference.
+ */
+Builder.prototype.setAlertBehavior = function(behavior) {
+  this.capabilities_.setAlertBehavior(behavior);
   return this;
 };
 
 
 /**
- * Sets Chrome-specific options for drivers created by this builder.
+ * Sets Chrome-specific options for drivers created by this builder. Any
+ * logging or proxy settings defined on the given options will take precedence
+ * over those set through {@link #setLoggingPrefs} and {@link #setProxy},
+ * respectively.
+ *
  * @param {!chrome.Options} options The ChromeDriver options to use.
  * @return {!Builder} A self reference.
  */
 Builder.prototype.setChromeOptions = function(options) {
-  var newCapabilities = options.toCapabilities(this.getCapabilities());
-  return /** @type {!Builder} */(this.withCapabilities(newCapabilities));
+  this.chromeOptions_ = options;
+  return this;
 };
 
 
@@ -94,7 +223,7 @@ Builder.prototype.setChromeOptions = function(options) {
  * the flow is never set, or is set to {@code null}, it will use the active
  * flow at the time {@link #build()} is called.
  * @param {webdriver.promise.ControlFlow} flow The control flow to use, or
- *     {@code null} to 
+ *     {@code null} to
  * @return {!Builder} A self reference.
  */
 Builder.prototype.setControlFlow = function(flow) {
@@ -104,25 +233,62 @@ Builder.prototype.setControlFlow = function(flow) {
 
 
 /**
- * @override
+ * Creates a new WebDriver client based on this builder's current
+ * configuration.
+ *
+ * @return {!webdriver.WebDriver} A new WebDriver instance.
+ * @throws {Error} If the current configuration is invalid.
  */
 Builder.prototype.build = function() {
-  var url = this.getServerUrl();
-
-  // If a remote server wasn't specified, check for browsers we support
-  // natively in node before falling back to using the java Selenium server.
-  if (!url) {
-    var driver = createNativeDriver(this.getCapabilities(), this.flow_);
-    if (driver) {
-      return driver;
-    }
-
-    // Nope, fall-back to using the default java server.
-    url = AbstractBuilder.DEFAULT_SERVER_URL;
+  // Create a copy for any changes we may need to make based on the current
+  // environment.
+  var capabilities = new Capabilities(this.capabilities_);
+
+  var browser = process.env.SELENIUM_BROWSER;
+  if (browser) {
+    browser = browser.split(/:/, 3);
+    capabilities.set(Capability.BROWSER_NAME, browser[0]);
+    capabilities.set(Capability.VERSION, browser[1] || null);
+    capabilities.set(Capability.PLATFORM, browser[2] || null);
+  }
+
+  browser = capabilities.get(Capability.BROWSER_NAME);
+
+  if (!browser) {
+    throw Error(
+        'Target browser not defined; did you forget to call forBrowser()?');
+  }
+
+  // Apply browser specific overrides.
+  if (browser === Browser.CHROME && this.chromeOptions_) {
+    capabilities.merge(this.chromeOptions_.toCapabilities());
+  }
+
+  // Check for a remote browser.
+  var url = process.env.SELENIUM_REMOTE_URL || this.url_;
+  if (url) {
+    var executor = executors.createExecutor(url);
+    return WebDriver.createSession(executor, capabilities, this.flow_);
   }
 
-  var executor = executors.createExecutor(url);
-  return WebDriver.createSession(executor, this.getCapabilities(), this.flow_);
+  // Check for a native browser.
+  switch (browser) {
+    case Browser.CHROME:
+      // Requiring 'chrome' above would create a cycle:
+      // index -> builder -> chrome -> index
+      var chrome = require('./chrome');
+      return new chrome.Driver(capabilities, null, this.flow_);
+
+    case Browser.PHANTOM_JS:
+      // Requiring 'phantomjs' would create a cycle:
+      // index -> builder -> phantomjs -> index
+      var phantomjs = require('./phantomjs');
+      return new phantomjs.Driver(capabilities, this.flow_);
+
+    default:
+      throw new Error('Do not know how to build driver: ' + browser
+          + '; did you forget to call usingServer(url)?');
+  }
 };