Module: selenium-webdriver/builder

class Builder

Creates new WebDriver instances. The environment variables listed below may be used to override a builder's configuration, allowing quick runtime changes.

SELENIUM_BROWSER: defines the target browser in the form browser[:version][:platform].
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 SELENIUM_SERVER_JAR.
SELENIUM_SERVER_JAR: defines the path to the standalone Selenium server 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

new Builder()

Parameters

None.

Instance Methods

build()code »

Creates a new WebDriver client based on this builder's current configuration.

Returns

webdriver.WebDriver: A new WebDriver instance.

Throws

Error: If the current configuration is invalid.

disableEnvironmentOverrides()code »

Configures this builder to ignore any environment variable overrides and to only use the configuration specified through this instance's API.

Returns

Builder: A self reference.

forBrowser(name, opt_version, opt_platform)code »

Configures the target browser for clients created by this instance. Any calls to #withCapabilities after this function will overwrite these settings.

You may also define the target browser using the SELENIUM_BROWSER environment variable. If set, this environment variable should be of the form browser[:[version][:platform]].

Parameters

namestring: The name of the target browser; common defaults are available on the webdriver.Browser enum.
opt_versionstring=: A desired version; may be omitted if any version should be used.
opt_platformstring=: The desired platform; may be omitted if any version may be used.

Returns

Builder: A self reference.

getCapabilities()code »

Returns the base set of capabilities this instance is currently configured to use.

Returns

webdriver.Capabilities: The current capabilities for this builder.

getServerUrl()code »

Returns

string: The URL of the WebDriver server this instance is configured to use.

getWebDriverProxy()code »

Returns

string: The URL of the proxy server to use for the WebDriver's HTTP connections.

setAlertBehavior(beahvior)code »

Sets the default action to take with an unexpected alert before returning an error.

Parameters

beahviorstring: The desired behavior; should be "accept", "dismiss", or "ignore". Defaults to "dismiss".

Returns

Builder: A self reference.

setChromeOptions(options)code »

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 #setLoggingPrefs and #setProxy, respectively.

Parameters

optionschrome.Options: The ChromeDriver options to use.

Returns

Builder: A self reference.

setControlFlow(flow)code »

Sets the control flow that created drivers should execute actions in. If the flow is never set, or is set to null, it will use the active flow at the time #build() is called.

Parameters

flowwebdriver.promise.ControlFlow: The control flow to use, or null to

Returns

Builder: A self reference.

setEnableNativeEvents(enabled)code »

Sets whether native events should be used.

Parameters

enabledboolean: Whether to enable native events.

Returns

Builder: A self reference.

setFirefoxOptions(options)code »

Sets Firefox 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 #setLoggingPrefs and #setProxy, respectively.

Parameters

optionsfirefox.Options: The FirefoxDriver options to use.

Returns

Builder: A self reference.

setIeOptions(options)code »

Sets Internet Explorer specific options for drivers created by this builder. Any proxy settings defined on the given options will take precedence over those set through #setProxy.

Parameters

optionsie.Options: The IEDriver options to use.

Returns

Builder: A self reference.

setLoggingPrefs(prefs)code »

Sets the logging preferences for the created session. Preferences may be changed by repeated calls, or by calling #withCapabilities.

Parameters

prefs(webdriver.logging.Preferences|Object<string, string>): The desired logging preferences.

Returns

Builder: A self reference.

setOperaOptions(options)code »

Sets Opera 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 #setLoggingPrefs and #setProxy, respectively.

Parameters

optionsopera.Options: The OperaDriver options to use.

Returns

Builder: A self reference.

setProxy(config)code »

Sets the proxy configuration to use for WebDriver clients created by this builder. Any calls to #withCapabilities after this function will overwrite these settings.

Parameters

config{proxyType: string}: The configuration to use.

Returns

Builder: A self reference.

setSafariOptions(options)code »

Sets Safari specific options for drivers created by this builder. Any logging settings defined on the given options will take precedence over those set through #setLoggingPrefs.

Parameters

optionssafari.Options: The Safari options to use.

Returns

Builder: A self reference.

setScrollBehavior(behavior)code »

Sets how elements should be scrolled into view for interaction.

Parameters

behaviornumber: The desired scroll behavior: either 0 to align with the top of the viewport or 1 to align with the bottom.

Returns

Builder: A self reference.

usingServer(url)code »

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.

Parameters

urlstring: The URL of a remote server to use.

Returns

Builder: A self reference.

usingWebDriverProxy(proxy)code »

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.

Parameters

proxystring: The URL of a proxy to use.

Returns

Builder: A self reference.

withCapabilities(capabilities)code »

Sets the desired capabilities when requesting a new session. This will overwrite any previously set capabilities.

Parameters

capabilitiesObject: The desired capabilities for a new session.

Returns

Builder: A self reference.