text: // 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;
  