Class: Builder

Builder

Creates new 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 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

Constructor

new Builder()

Source: index.js, line 195

Methods

build() → (non-null) {ThenableWebDriver}

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

This method will return a ThenableWebDriver instance, allowing users to issue commands directly without calling then(). The returned thenable wraps a promise that will resolve to a concrete WebDriver instance. The promise will be rejected if the remote end fails to create a new session.

Source: index.js, line 583

Throws:

If the current configuration is invalid.
Type Error

Returns:

A new WebDriver instance.

Type:: ThenableWebDriver

disableEnvironmentOverrides() → (non-null) {Builder}

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

Source: index.js, line 249

Returns:

A self reference.

Type:: Builder

forBrowser(name, opt_versionopt, opt_platformopt) → (non-null) {Builder}

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 {@code SELENIUM_BROWSER} environment variable. If set, this environment variable should be of the form browser[:[version][:platform]].

Parameters:

Name	Type	Attributes	Description
`name`	string \| Browser		The name of the target browser; common defaults are available on the webdriver.Browser enum.
`opt_version`	string	<optional>	A desired version; may be omitted if any version should be used.
`opt_platform`	string \| capabilities.Platform	<optional>	The desired platform; may be omitted if any platform may be used.

Source: index.js, line 372

Returns:

A self reference.

Type:: Builder

getCapabilities() → (non-null) {Capabilities}

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

Source: index.js, line 338

Returns:

The current capabilities for this builder.

Type:: Capabilities

getChromeOptions() → {chrome.Options}

Source: index.js, line 439

Returns:

the Chrome specific options currently configured for this builder.

Type:: chrome.Options

getFirefoxOptions() → {firefox.Options}

Source: index.js, line 476

Returns:

the Firefox specific options currently configured for this instance.

Type:: firefox.Options

getHttpAgent() → {http.Agent}

Source: index.js, line 315

Returns:

The http agent used for each request

Type:: http.Agent

getSafariOptions() → {safari.Options}

Source: index.js, line 566

Returns:

the Safari specific options currently configured for this instance.

Type:: safari.Options

getServerUrl() → {string}

Source: index.js, line 275

Returns:

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

Type:: string

getWebDriverProxy() → (nullable) {string}

Source: index.js, line 296

Returns:

The URL of the proxy server to use for the WebDriver's HTTP connections, or null if not set.

Type:: string

setAlertBehavior(behaviornullable) → (non-null) {Builder}

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

Parameters:

Name	Type	Attributes	Description
`behavior`	capabilities.UserPromptHandler	<nullable>	The desired behavior.

Source: index.js, line 416
See: capabilities.Capabilities#setAlertBehavior

Returns:

A self reference.

Type:: Builder

setCapability(key, value) → (non-null) {Builder}

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.

Parameters:

Name	Type	Description
`key`	string	The capability key.
`value`	*	The capability value.

Source: index.js, line 350

Returns:

A self reference.

Type:: Builder

setChromeOptions(optionsnon-null) → (non-null) {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 #setLoggingPrefs and #setProxy, respectively.

Parameters:

Name	Type	Description
`options`	chrome.Options	The ChromeDriver options to use.

Source: index.js, line 430

Returns:

A self reference.

Type:: Builder

setChromeService(service) → (non-null) {Builder}

Sets the service builder to use for managing the chromedriver child process when creating new Chrome sessions.

Parameters:

Name	Type	Description
`service`	chrome.ServiceBuilder	the service to use.

Source: index.js, line 450

Returns:

A self reference.

Type:: Builder

setEdgeOptions(optionsnon-null) → (non-null) {Builder}

Set 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 #setProxy.

Parameters:

Name	Type	Description
`options`	edge.Options	The MicrosoftEdgeDriver options to use.

Source: index.js, line 529

Returns:

A self reference.

Type:: Builder

setEdgeService(service) → (non-null) {Builder}

Sets the edge.ServiceBuilder to use to manage the MicrosoftEdgeDriver child process when creating sessions locally.

Parameters:

Name	Type	Description
`service`	edge.ServiceBuilder	the service to use.

Source: index.js, line 541

Returns:

a self reference.

Type:: Builder

setFirefoxOptions(optionsnon-null) → (non-null) {Builder}

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:

Name	Type	Description
`options`	firefox.Options	The FirefoxDriver options to use.

Source: index.js, line 467

Returns:

A self reference.

Type:: Builder

setFirefoxService(service) → (non-null) {Builder}

Sets the firefox.ServiceBuilder to use to manage the geckodriver child process when creating Firefox sessions locally.

Parameters:

Name	Type	Description
`service`	firefox.ServiceBuilder	the service to use.

Source: index.js, line 487

Returns:

a self reference.

Type:: Builder

setIeOptions(optionsnon-null) → (non-null) {Builder}

Set 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:

Name	Type	Description
`options`	ie.Options	The IEDriver options to use.

Source: index.js, line 503

Returns:

A self reference.

Type:: Builder

setIeService(service) → (non-null) {Builder}

Sets the ie.ServiceBuilder to use to manage the geckodriver child process when creating IE sessions locally.

Parameters:

Name	Type	Description
`service`	ie.ServiceBuilder	the service to use.

Source: index.js, line 515

Returns:

a self reference.

Type:: Builder

setLoggingPrefs(prefs) → (non-null) {Builder}

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

Parameters:

Name	Type	Description
`prefs`

Source: index.js, line 403

Returns:

A self reference.

Type:: Builder

setProxy(config) → (non-null) {Builder}

Sets the proxy configuration for the target browser. Any calls to #withCapabilities after this function will overwrite these settings.

Parameters:

Name	Type	Description
`config`

Source: index.js, line 391

Returns:

A self reference.

Type:: Builder

setSafariOptions(optionsnon-null) → (non-null) {Builder}

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:

Name	Type	Description
`options`	safari.Options	The Safari options to use.

Source: index.js, line 557

Returns:

A self reference.

Type:: Builder

usingHttpAgent(agent) → (non-null) {Builder}

Sets the http agent to use for each request. If this method is not called, the Builder will use http.globalAgent by default.

Parameters:

Name	Type	Description
`agent`	http.Agent	The agent to use for each request.

Source: index.js, line 307

Returns:

A self reference.

Type:: Builder

usingServer(url) → (non-null) {Builder}

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:

Name	Type	Description
`url`	string	The URL of a remote server to use.

Source: index.js, line 266

Returns:

A self reference.

Type:: Builder

usingWebDriverProxy(proxy) → (non-null) {Builder}

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:

Name	Type	Description
`proxy`	string	The URL of a proxy to use.

Source: index.js, line 287

Returns:

A self reference.

Type:: Builder

withCapabilities(capabilitiesnon-null) → (non-null) {Builder}

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.

Parameters:

Name	Type	Description
`capabilities`	Object \| Capabilities	The desired capabilities for a new session.

Source: index.js, line 328

Returns:

A self reference.

Type:: Builder