selenium-webdriver/builder.js

The official WebDriver JavaScript bindings from the Selenium project

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

var base = require('./_base'),
    executors = require('./executors');

// 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');



var seleniumServer;

/**
 * Starts an instance of the Selenium server if not yet running.
 * @param {string} jar Path to the server jar to use.
 * @return {!webdriver.promise.Promise<string>} A promise for the server's
 *     addrss once started.
 */
function startSeleniumServer(jar) {
  if (!seleniumServer) {
    // Requiring 'chrome' above would create a cycle:
    // index -> builder -> chrome -> index
    var remote = require('./remote');
    seleniumServer = new remote.SeleniumServer(jar);
  }
  return seleniumServer.start();
}


/**
 * 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.
 *
 * - {@code SELENIUM_BROWSER}: defines the target browser in the form
 *   {@code browser[:version][:platform]}.
 *
 * - {@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). This
 *   option always takes precedence over {@code SELENIUM_SERVER_JAR}.
 *
 * - {@code SELENIUM_SERVER_JAR}: defines the path to the
 *   <a href="http://selenium-release.storage.googleapis.com/index.html">
 *   standalone Selenium server</a> jar to use. The server will be started the
 *   first time a WebDriver instance and be killed when the process exits.
 *
 * Suppose you had mytest.js that created WebDriver with
 *
 *     var driver = new webdriver.Builder()
 *         .forBrowser('chrome')
 *         .build();
 *
 * This test could be made to use Firefox on the local machine by running with
 * `SELENIUM_BROWSER=firefox node mytest.js`. Rather than change the code to
 * target Google Chrome on a remote machine, you can simply set the
 * `SELENIUM_BROWSER` and `SELENIUM_REMOTE_URL` environment variables:
 *
 *     SELENIUM_BROWSER=chrome:36:LINUX \
 *     SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub \
 *     node mytest.js
 *
 * You could also use a local copy of the standalone Selenium server:
 *
 *     SELENIUM_BROWSER=chrome:36:LINUX \
 *     SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar \
 *     node mytest.js
 *
 * @constructor
 */
var Builder = function() {

  /** @private {webdriver.promise.ControlFlow} */
  this.flow_ = null;

  /** @private {string} */
  this.url_ = '';

  /** @private {?string} */
  this.proxy_ = null;

  /** @private {!webdriver.Capabilities} */
  this.capabilities_ = new Capabilities();

  /** @private {chrome.Options} */
  this.chromeOptions_ = null;

  /** @private {firefox.Options} */
  this.firefoxOptions_ = null;

  /** @private {opera.Options} */
  this.operaOptions_ = null;

  /** @private {ie.Options} */
  this.ieOptions_ = null;

  /** @private {safari.Options} */
  this.safariOptions_ = null;

  /** @private {boolean} */
  this.ignoreEnv_ = false;
};


/**
 * Configures this builder to ignore any environment variable overrides and to
 * only use the configuration specified through this instance's API.
 *
 * @return {!Builder} A self reference.
 */
Builder.prototype.disableEnvironmentOverrides = function() {
  this.ignoreEnv_ = true;
  return this;
};


/**
 * 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.
 *
 * As an alternative to this method, you may also set the `SELENIUM_REMOTE_URL`
 * environment variable.
 *
 * @param {string} url The URL of a remote server to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.usingServer = function(url) {
  this.url_ = url;
  return this;
};


/**
 * @return {string} The URL of the WebDriver server this instance is configured
 *     to use.
 */
Builder.prototype.getServerUrl = function() {
  return this.url_;
};


/**
 * Sets the URL of the proxy to use for the WebDriver's HTTP connections.
 * If this method is never called, the Builder will create a connection without
 * a proxy.
 *
 * @param {string} proxy The URL of a proxy to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.usingWebDriverProxy = function(proxy) {
  this.proxy_ = proxy;
  return this;
};


/**
 * @return {string} The URL of the proxy server to use for the WebDriver's HTTP
 *    connections.
 */
Builder.prototype.getWebDriverProxy = function() {
  return this.proxy_;
};


/**
 * 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.
 *
 * You may also define the target browser using the {@code SELENIUM_BROWSER}
 * environment variable. If set, this environment variable should be of the
 * form `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;
};


/**
 * 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 {!webdriver.ProxyConfig} config The configuration to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.setProxy = function(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 {@linkplain selenium-webdriver/chrome.Options 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) {
  this.chromeOptions_ = options;
  return this;
};


/**
 * Sets Firefox specific {@linkplain selenium-webdriver/firefox.Options 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 {!firefox.Options} options The FirefoxDriver options to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.setFirefoxOptions = function(options) {
  this.firefoxOptions_ = options;
  return this;
};


/**
 * Sets Opera specific {@linkplain selenium-webdriver/opera.Options 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 {!opera.Options} options The OperaDriver options to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.setOperaOptions = function(options) {
  this.operaOptions_ = options;
  return this;
};


/**
 * Sets Internet Explorer specific
 * {@linkplain selenium-webdriver/ie.Options options} for drivers created by
 * this builder. Any proxy settings defined on the given options will take
 * precedence over those set through {@link #setProxy}.
 *
 * @param {!ie.Options} options The IEDriver options to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.setIeOptions = function(options) {
  this.ieOptions_ = options;
  return this;
};


/**
 * Sets Safari specific {@linkplain selenium-webdriver/safari.Options options}
 * for drivers created by this builder. Any logging settings defined on the
 * given options will take precedence over those set through
 * {@link #setLoggingPrefs}.
 *
 * @param {!safari.Options} options The Safari options to use.
 * @return {!Builder} A self reference.
 */
Builder.prototype.setSafariOptions = function(options) {
  this.safariOptions_ = options;
  return this;
};


/**
 * Sets the control flow that created drivers should execute actions in. If
 * 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
 * @return {!Builder} A self reference.
 */
Builder.prototype.setControlFlow = function(flow) {
  this.flow_ = flow;
  return this;
};


/**
 * 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() {
  // Create a copy for any changes we may need to make based on the current
  // environment.
  var capabilities = new Capabilities(this.capabilities_);

  var browser;
  if (!this.ignoreEnv_ && process.env.SELENIUM_BROWSER) {
    browser = process.env.SELENIUM_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 (typeof browser !== 'string') {
    throw TypeError(
        'Target browser must be a string, but is <' + (typeof browser) + '>;' +
        ' did you forget to call forBrowser()?');
  }

  if (browser === 'ie') {
    browser = Browser.INTERNET_EXPLORER;
  }

  // Apply browser specific overrides.
  if (browser === Browser.CHROME && this.chromeOptions_) {
    capabilities.merge(this.chromeOptions_.toCapabilities());

  } else if (browser === Browser.FIREFOX && this.firefoxOptions_) {
    capabilities.merge(this.firefoxOptions_.toCapabilities());

  } else if (browser === Browser.INTERNET_EXPLORER && this.ieOptions_) {
    capabilities.merge(this.ieOptions_.toCapabilities());

  } else if (browser === Browser.OPERA && this.operaOptions_) {
    capabilities.merge(this.operaOptions_.toCapabilities());

  } else if (browser === Browser.SAFARI && this.safariOptions_) {
    capabilities.merge(this.safariOptions_.toCapabilities());
  }

  // Check for a remote browser.
  var url = this.url_;
  if (!this.ignoreEnv_) {
    if (process.env.SELENIUM_REMOTE_URL) {
      url = process.env.SELENIUM_REMOTE_URL;
    } else if (process.env.SELENIUM_SERVER_JAR) {
      url = startSeleniumServer(process.env.SELENIUM_SERVER_JAR);
    }
  }

  if (url) {
    var executor = executors.createExecutor(url, this.proxy_);
    return WebDriver.createSession(executor, capabilities, 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.FIREFOX:
      // Requiring 'firefox' above would create a cycle:
      // index -> builder -> firefox -> index
      var firefox = require('./firefox');
      return new firefox.Driver(capabilities, this.flow_);

    case Browser.INTERNET_EXPLORER:
      // Requiring 'ie' above would create a cycle:
      // index -> builder -> ie -> index
      var ie = require('./ie');
      return new ie.Driver(capabilities, this.flow_);

    case Browser.OPERA:
      // Requiring 'opera' would create a cycle:
      // index -> builder -> opera -> index
      var opera = require('./opera');
      return new opera.Driver(capabilities, 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_);

    case Browser.SAFARI:
      // Requiring 'safari' would create a cycle:
      // index -> builder -> safari -> index
      var safari = require('./safari');
      return new safari.Driver(capabilities, this.flow_);

    default:
      throw new Error('Do not know how to build driver: ' + browser
          + '; did you forget to call usingServer(url)?');
  }
};


// PUBLIC API


exports.Builder = Builder;