// 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 The main user facing module. Exports WebDriver's primary * public API and provides convenience assessors to certain sub-modules. */'use strict'const _http = require('./http')const by = require('./lib/by')const capabilities = require('./lib/capabilities')const chrome = require('./chrome')const edge = require('./edge')const error = require('./lib/error')const firefox = require('./firefox')const ie = require('./ie')const input = require('./lib/input')const logging = require('./lib/logging')const promise = require('./lib/promise')const remote = require('./remote')const safari = require('./safari')const session = require('./lib/session')const until = require('./lib/until')const webdriver = require('./lib/webdriver')const select = require('./lib/select')const LogInspector = require('./bidi/logInspector')const BrowsingContext = require('./bidi/browsingContext')const BrowsingContextInspector = require('./bidi/browsingContextInspector')const ScriptManager = require('./bidi/scriptManager')const NetworkInspector = require('./bidi/networkInspector')const version = require('./package.json').versionconst Browser = capabilities.Browserconst Capabilities = capabilities.Capabilitiesconst Capability = capabilities.Capabilityconst WebDriver = webdriver.WebDriverlet seleniumServer/** * Starts an instance of the Selenium server if not yet running. * @param {string} jar Path to the server jar to use. * @return {!Promise<string>} A promise for the server's *     address once started. */function startSeleniumServer(jar) {  if (!seleniumServer) {    seleniumServer = new remote.SeleniumServer(jar)  }  return seleniumServer.start()}/** * {@linkplain webdriver.WebDriver#setFileDetector WebDriver's setFileDetector} * method uses a non-standard command to transfer files from the local client * to the remote end hosting the browser. Many of the WebDriver sub-types, like * the {@link chrome.Driver} and {@link firefox.Driver}, do not support this * command. Thus, these classes override the `setFileDetector` to no-op. * * This function uses a mixin to re-enable `setFileDetector` by calling the * original method on the WebDriver prototype directly. This is used only when * the builder creates a Chrome or Firefox instance that communicates with a * remote end (and thus, support for remote file detectors is unknown). * * @param {function(new: webdriver.WebDriver, ...?)} ctor * @return {function(new: webdriver.WebDriver, ...?)} */function ensureFileDetectorsAreEnabled(ctor) {  return class extends ctor {    /** @param {input.FileDetector} detector */    setFileDetector(detector) {      webdriver.WebDriver.prototype.setFileDetector.call(this, detector)    }  }}/** * A thenable wrapper around a {@linkplain webdriver.IWebDriver IWebDriver} * instance that allows commands to be issued directly instead of having to * repeatedly call `then`: * *     let driver = new Builder().build(); *     driver.then(d => d.get(url));  // You can do this... *     driver.get(url);               // ...or this * * If the driver instance fails to resolve (e.g. the session cannot be created), * every issued command will fail. * * @extends {webdriver.IWebDriver} * @extends {IThenable<!webdriver.IWebDriver>} * @interface */class ThenableWebDriver {  /** @param {...?} args */  static createSession(...args) {} // eslint-disable-line}/** * @const {!Map<function(new: WebDriver, !IThenable<!Session>, ...?), *              function(new: ThenableWebDriver, !IThenable<!Session>, ...?)>} */const THENABLE_DRIVERS = new Map()/** * @param {function(new: WebDriver, !IThenable<!Session>, ...?)} ctor * @param {...?} args * @return {!ThenableWebDriver} */function createDriver(ctor, ...args) {  let thenableWebDriverProxy = THENABLE_DRIVERS.get(ctor)  if (!thenableWebDriverProxy) {    /**     * @extends {WebDriver}  // Needed since `ctor` is dynamically typed.     * @implements {ThenableWebDriver}     */    thenableWebDriverProxy = class extends ctor {      /**       * @param {!IThenable<!Session>} session       * @param {...?} rest       */      constructor(session, ...rest) {        super(session, ...rest)        const pd = this.getSession().then((session) => {          return new ctor(session, ...rest)        })        /** @override */        this.then = pd.then.bind(pd)        /** @override */        this.catch = pd.catch.bind(pd)      }    }    THENABLE_DRIVERS.set(ctor, thenableWebDriverProxy)  }  return thenableWebDriverProxy.createSession(...args)}/** * 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="https://www.selenium.dev/downloads/"> *   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 */class Builder {  constructor() {    /** @private @const */    this.log_ = logging.getLogger(`${logging.Type.DRIVER}.Builder`)    /** @private {string} */    this.url_ = ''    /** @private {?string} */    this.proxy_ = null    /** @private {!Capabilities} */    this.capabilities_ = new Capabilities()    /** @private {chrome.Options} */    this.chromeOptions_ = null    /** @private {chrome.ServiceBuilder} */    this.chromeService_ = null    /** @private {firefox.Options} */    this.firefoxOptions_ = null    /** @private {firefox.ServiceBuilder} */    this.firefoxService_ = null    /** @private {ie.Options} */    this.ieOptions_ = null    /** @private {ie.ServiceBuilder} */    this.ieService_ = null    /** @private {safari.Options} */    this.safariOptions_ = null    /** @private {edge.Options} */    this.edgeOptions_ = null    /** @private {remote.DriverService.Builder} */    this.edgeService_ = null    /** @private {boolean} */    this.ignoreEnv_ = false    /** @private {http.Agent} */    this.agent_ = null  }  /**   * 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.   */  disableEnvironmentOverrides() {    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.   */  usingServer(url) {    this.url_ = url    return this  }  /**   * @return {string} The URL of the WebDriver server this instance is   *     configured to use.   */  getServerUrl() {    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.   */  usingWebDriverProxy(proxy) {    this.proxy_ = proxy    return this  }  /**   * @return {?string} The URL of the proxy server to use for the WebDriver's   *    HTTP connections, or `null` if not set.   */  getWebDriverProxy() {    return this.proxy_  }  /**   * Sets the http agent to use for each request.   * If this method is not called, the Builder will use http.globalAgent by default.   *   * @param {http.Agent} agent The agent to use for each request.   * @return {!Builder} A self reference.   */  usingHttpAgent(agent) {    this.agent_ = agent    return this  }  /**   * @return {http.Agent} The http agent used for each request   */  getHttpAgent() {    return this.agent_  }  /**   * Recommended way is to use set*Options where * is the browser(eg setChromeOptions)   *   * Sets the desired capabilities when requesting a new session. This will   * overwrite any previously set capabilities.   * @param {!(Object|Capabilities)} capabilities The desired capabilities for   *     a new session.   * @return {!Builder} A self reference.   */  withCapabilities(capabilities) {    this.capabilities_ = new Capabilities(capabilities)    return this  }  /**   * Returns the base set of capabilities this instance is currently configured   * to use.   * @return {!Capabilities} The current capabilities for this builder.   */  getCapabilities() {    return this.capabilities_  }  /**   * Sets the desired capability when requesting a new session.   * If there is already a capability named key, its value will be overwritten with value.   * This is a convenience wrapper around builder.getCapabilities().set(key, value) to support Builder method chaining.   * @param {string} key The capability key.   * @param {*} value The capability value.   * @return {!Builder} A self reference.   */  setCapability(key, value) {    this.capabilities_.set(key, value)    return this  }  /**   * 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|!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|!capabilities.Platform)=} opt_platform   *     The desired platform; may be omitted if any platform may be used.   * @return {!Builder} A self reference.   */  forBrowser(name, opt_version, opt_platform) {    this.capabilities_.setBrowserName(name)    if (opt_version) {      this.capabilities_.setBrowserVersion(opt_version)    }    if (opt_platform) {      this.capabilities_.setPlatform(opt_platform)    }    return this  }  /**   * Sets the proxy configuration for the target browser.   * Any calls to {@link #withCapabilities} after this function will   * overwrite these settings.   *   * @param {!./lib/proxy.Config} config The configuration to use.   * @return {!Builder} A self reference.   */  setProxy(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 {!(./lib/logging.Preferences|Object<string, string>)} prefs The   *     desired logging preferences.   * @return {!Builder} A self reference.   */  setLoggingPrefs(prefs) {    this.capabilities_.setLoggingPrefs(prefs)    return this  }  /**   * Sets the default action to take with an unexpected alert before returning   * an error.   *   * @param {?capabilities.UserPromptHandler} behavior The desired behavior.   * @return {!Builder} A self reference.   * @see capabilities.Capabilities#setAlertBehavior   */  setAlertBehavior(behavior) {    this.capabilities_.setAlertBehavior(behavior)    return this  }  /**   * Sets Chrome specific {@linkplain 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.   */  setChromeOptions(options) {    this.chromeOptions_ = options    return this  }  /**   * @return {chrome.Options} the Chrome specific options currently configured   *     for this builder.   */  getChromeOptions() {    return this.chromeOptions_  }  /**   * Sets the service builder to use for managing the chromedriver child process   * when creating new Chrome sessions.   *   * @param {chrome.ServiceBuilder} service the service to use.   * @return {!Builder} A self reference.   */  setChromeService(service) {    if (service && !(service instanceof chrome.ServiceBuilder)) {      throw TypeError('not a chrome.ServiceBuilder object')    }    this.chromeService_ = service    return this  }  /**   * Sets Firefox specific {@linkplain 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.   */  setFirefoxOptions(options) {    this.firefoxOptions_ = options    return this  }  /**   * @return {firefox.Options} the Firefox specific options currently configured   *     for this instance.   */  getFirefoxOptions() {    return this.firefoxOptions_  }  /**   * Sets the {@link firefox.ServiceBuilder} to use to manage the geckodriver   * child process when creating Firefox sessions locally.   *   * @param {firefox.ServiceBuilder} service the service to use.   * @return {!Builder} a self reference.   */  setFirefoxService(service) {    if (service && !(service instanceof firefox.ServiceBuilder)) {      throw TypeError('not a firefox.ServiceBuilder object')    }    this.firefoxService_ = service    return this  }  /**   * Set Internet Explorer specific {@linkplain 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.   */  setIeOptions(options) {    this.ieOptions_ = options    return this  }  /**   * Sets the {@link ie.ServiceBuilder} to use to manage the geckodriver   * child process when creating IE sessions locally.   *   * @param {ie.ServiceBuilder} service the service to use.   * @return {!Builder} a self reference.   */  setIeService(service) {    this.ieService_ = service    return this  }  /**   * Set {@linkplain edge.Options options} specific to Microsoft's Edge browser   * for drivers created by this builder. Any proxy settings defined on the   * given options will take precedence over those set through   * {@link #setProxy}.   *   * @param {!edge.Options} options The MicrosoftEdgeDriver options to use.   * @return {!Builder} A self reference.   */  setEdgeOptions(options) {    this.edgeOptions_ = options    return this  }  /**   * Sets the {@link edge.ServiceBuilder} to use to manage the   * MicrosoftEdgeDriver child process when creating sessions locally.   *   * @param {edge.ServiceBuilder} service the service to use.   * @return {!Builder} a self reference.   */  setEdgeService(service) {    if (service && !(service instanceof edge.ServiceBuilder)) {      throw TypeError('not a edge.ServiceBuilder object')    }    this.edgeService_ = service    return this  }  /**   * Sets Safari specific {@linkplain 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.   */  setSafariOptions(options) {    this.safariOptions_ = options    return this  }  /**   * @return {safari.Options} the Safari specific options currently configured   *     for this instance.   */  getSafariOptions() {    return this.safariOptions_  }  /**   * Creates a new WebDriver client based on this builder's current   * configuration.   *   * This method will return a {@linkplain ThenableWebDriver} instance, allowing   * users to issue commands directly without calling `then()`. The returned   * thenable wraps a promise that will resolve to a concrete   * {@linkplain webdriver.WebDriver WebDriver} instance. The promise will be   * rejected if the remote end fails to create a new session.   *   * @return {!ThenableWebDriver} A new WebDriver instance.   * @throws {Error} If the current configuration is invalid.   */  build() {    // Create a copy for any changes we may need to make based on the current    // environment.    const capabilities = new Capabilities(this.capabilities_)    let browser    if (!this.ignoreEnv_ && process.env.SELENIUM_BROWSER) {      this.log_.fine(`SELENIUM_BROWSER=${process.env.SELENIUM_BROWSER}`)      browser = process.env.SELENIUM_BROWSER.split(/:/, 3)      capabilities.setBrowserName(browser[0])      browser[1] && capabilities.setBrowserVersion(browser[1])      browser[2] && capabilities.setPlatform(browser[2])    }    browser = capabilities.get(Capability.BROWSER_NAME)    /**     * If browser is not defined in forBrowser, check if browserOptions are defined to pick the browserName     */    if (!browser) {      const options =        this.chromeOptions_ || this.firefoxOptions_ || this.ieOptions_ || this.safariOptions_ || this.edgeOptions_      if (options) {        browser = options['map_'].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_)    } else if (browser === Browser.FIREFOX && this.firefoxOptions_) {      capabilities.merge(this.firefoxOptions_)    } else if (browser === Browser.INTERNET_EXPLORER && this.ieOptions_) {      capabilities.merge(this.ieOptions_)    } else if (browser === Browser.SAFARI && this.safariOptions_) {      capabilities.merge(this.safariOptions_)    } else if (browser === Browser.EDGE && this.edgeOptions_) {      capabilities.merge(this.edgeOptions_)    }    checkOptions(capabilities, 'chromeOptions', chrome.Options, 'setChromeOptions')    checkOptions(capabilities, 'moz:firefoxOptions', firefox.Options, 'setFirefoxOptions')    checkOptions(capabilities, 'safari.options', safari.Options, 'setSafariOptions')    // Check for a remote browser.    let url = this.url_    if (!this.ignoreEnv_) {      if (process.env.SELENIUM_REMOTE_URL) {        this.log_.fine(`SELENIUM_REMOTE_URL=${process.env.SELENIUM_REMOTE_URL}`)        url = process.env.SELENIUM_REMOTE_URL      } else if (process.env.SELENIUM_SERVER_JAR) {        this.log_.fine(`SELENIUM_SERVER_JAR=${process.env.SELENIUM_SERVER_JAR}`)        url = startSeleniumServer(process.env.SELENIUM_SERVER_JAR)      }    }    if (url) {      this.log_.fine('Creating session on remote server')      let client = Promise.resolve(url).then((url) => new _http.HttpClient(url, this.agent_, this.proxy_))      let executor = new _http.Executor(client)      if (browser === Browser.CHROME) {        const driver = ensureFileDetectorsAreEnabled(chrome.Driver)        return createDriver(driver, capabilities, executor)      }      if (browser === Browser.FIREFOX) {        const driver = ensureFileDetectorsAreEnabled(firefox.Driver)        return createDriver(driver, capabilities, executor)      }      return createDriver(WebDriver, executor, capabilities)    }    // Check for a native browser.    switch (browser) {      case Browser.CHROME: {        let service = null        if (this.chromeService_) {          service = this.chromeService_.build()        }        return createDriver(chrome.Driver, capabilities, service)      }      case Browser.FIREFOX: {        let service = null        if (this.firefoxService_) {          service = this.firefoxService_.build()        }        return createDriver(firefox.Driver, capabilities, service)      }      case Browser.INTERNET_EXPLORER: {        let service = null        if (this.ieService_) {          service = this.ieService_.build()        }        return createDriver(ie.Driver, capabilities, service)      }      case Browser.EDGE: {        let service = null        if (this.edgeService_) {          service = this.edgeService_.build()        }        return createDriver(edge.Driver, capabilities, service)      }      case Browser.SAFARI:        return createDriver(safari.Driver, capabilities)      default:        throw new Error('Do not know how to build driver: ' + browser + '; did you forget to call usingServer(url)?')    }  }}/** * In the 3.x releases, the various browser option classes * (e.g. firefox.Options) had to be manually set as an option using the * Capabilities class: * *     let ffo = new firefox.Options(); *     // Configure firefox options... * *     let caps = new Capabilities(); *     caps.set('moz:firefoxOptions', ffo); * *     let driver = new Builder() *         .withCapabilities(caps) *         .build(); * * The options are now subclasses of Capabilities and can be used directly. A * direct translation of the above is: * *     let ffo = new firefox.Options(); *     // Configure firefox options... * *     let driver = new Builder() *         .withCapabilities(ffo) *         .build(); * * You can also set the options for various browsers at once and let the builder * choose the correct set at runtime (see Builder docs above): * *     let ffo = new firefox.Options(); *     // Configure ... * *     let co = new chrome.Options(); *     // Configure ... * *     let driver = new Builder() *         .setChromeOptions(co) *         .setFirefoxOptions(ffo) *         .build(); * * @param {!Capabilities} caps * @param {string} key * @param {function(new: Capabilities)} optionType * @param {string} setMethod * @throws {error.InvalidArgumentError} */function checkOptions(caps, key, optionType, setMethod) {  let val = caps.get(key)  if (val instanceof optionType) {    throw new error.InvalidArgumentError(      'Options class extends Capabilities and should not be set as key ' +        `"${key}"; set browser-specific options with ` +        `Builder.${setMethod}(). For more information, see the ` +        'documentation attached to the function that threw this error',    )  }}// PUBLIC APIexports.Browser = capabilities.Browserexports.Builder = Builderexports.Button = input.Buttonexports.By = by.Byexports.RelativeBy = by.RelativeByexports.withTagName = by.withTagNameexports.locateWith = by.locateWithexports.Capabilities = capabilities.Capabilitiesexports.Capability = capabilities.Capabilityexports.Condition = webdriver.Conditionexports.FileDetector = input.FileDetectorexports.Key = input.Keyexports.Origin = input.Originexports.Session = session.Sessionexports.ThenableWebDriver = ThenableWebDriverexports.WebDriver = webdriver.WebDriverexports.WebElement = webdriver.WebElementexports.WebElementCondition = webdriver.WebElementConditionexports.WebElementPromise = webdriver.WebElementPromiseexports.error = errorexports.logging = loggingexports.promise = promiseexports.until = untilexports.Select = select.Selectexports.LogInspector = LogInspectorexports.BrowsingContext = BrowsingContextexports.BrowsingContextInspector = BrowsingContextInspectorexports.ScriptManager = ScriptManagerexports.NetworkInspector = NetworkInspectorexports.version = version