Class 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 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

Hierarchy

Builder

Constructors

constructor

new Builder(): Builder
Returns Builder

Methods

build

build(): 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.WebDriver WebDriver instance. The promise will be rejected if the remote end fails to create a new session.

Returns ThenableWebDriver
A new WebDriver instance.

Throws
If the current configuration is invalid.

disableEnvironmentOverrides

disableEnvironmentOverrides(): Builder
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

forBrowser(name, opt_version?, opt_platform?): 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 {@code browser[:[version][:platform]]}.
Parameters
- name: string
  The name of the target browser; common defaults are available on the Browser enum.
- Optional opt_version: string
  A desired version; may be omitted if any version should be used.
- Optional opt_platform: string
  The desired platform; may be omitted if any version may be used.
Returns Builder
A self reference.

getCapabilities

getCapabilities(): Capabilities
Returns the base set of capabilities this instance is currently configured to use.

Returns Capabilities
The current capabilities for this builder.

getChromeOptions

getChromeOptions(): Options
Returns Options
the Chrome specific options currently configured for this builder.

getFirefoxOptions

getFirefoxOptions(): Options
Returns Options
the Firefox specific options currently configured for this instance.

getHttpAgent

getHttpAgent(): any
Returns any
The http agent used for each request

getSafariOptions

getSafariOptions(): Options
Returns Options
the Safari specific options currently configured for this instance.

getServerUrl

getServerUrl(): string
Returns string
The URL of the WebDriver server this instance is configured to use.

getWebDriverProxy

getWebDriverProxy(): null | string
Returns null | string
The URL of the proxy server to use for the WebDriver's HTTP connections, or null if not set.

setAlertBehavior

setAlertBehavior(behavior?): Builder
Sets the default action to take with an unexpected alert before returning an error.
Parameters
- Optional behavior: string
Returns Builder
A self reference.

setChromeOptions

setChromeOptions(options): 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
- options: Options
  The ChromeDriver options to use.
Returns Builder
A self reference.

setChromeService

setChromeService(service): Builder
Sets the service builder to use for managing the chromedriver child process when creating new Chrome sessions.
Parameters
- service: ServiceBuilder
  the service to use.
Returns Builder
A self reference.

setEdgeOptions

setEdgeOptions(options): 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
- options: Options
  The MicrosoftEdgeDriver options to use.
Returns Builder
A self reference.

setEdgeService

setEdgeService(service): Builder
Sets the edge.ServiceBuilder to use to manage the MicrosoftEdgeDriver child process when creating sessions locally.
Parameters
- service: ServiceBuilder
  the service to use.
Returns Builder
a self reference.

setFirefoxOptions

setFirefoxOptions(options): 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
- options: Options
  The FirefoxDriver options to use.
Returns Builder
A self reference.

setFirefoxService

setFirefoxService(service): Builder
Sets the firefox.ServiceBuilder to use to manage the geckodriver child process when creating Firefox sessions locally.
Parameters
- service: ServiceBuilder
  the service to use.
Returns Builder
a self reference.

setIeOptions

setIeOptions(options): 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
- options: Options
  The IEDriver options to use.
Returns Builder
A self reference.

setIeService

setIeService(service): Builder
Sets the ie.ServiceBuilder to use to manage the geckodriver child process when creating IE sessions locally.
Parameters
- service: ServiceBuilder
  the service to use.
Returns Builder
a self reference.

setLoggingPrefs

setLoggingPrefs(prefs): Builder
Sets the logging preferences for the created session. Preferences may be changed by repeated calls, or by calling #withCapabilities.
Parameters
- prefs: {} | Preferences
  The desired logging preferences.
Returns Builder
A self reference.

setProxy

setProxy(config): Builder
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: ProxyConfig
  The configuration to use.
Returns Builder
A self reference.

setSafariOptions

setSafariOptions(options): 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
- options: Options
  The Safari options to use.
Returns Builder
A self reference.

usingHttpAgent

usingHttpAgent(agent): 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
- agent: any
  The agent to use for each request.
Returns Builder
A self reference.

usingServer

usingServer(url): 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 {@code SELENIUM_REMOTE_URL} environment variable.
Parameters
- url: string
  The URL of a remote server to use.
Returns Builder
A self reference.

usingWebDriverProxy

usingWebDriverProxy(proxy): 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
- proxy: string
  The URL of a proxy to use.
Returns Builder
A self reference.

withCapabilities

withCapabilities(capabilities): Builder
Sets the desired capabilities when requesting a new session. This will overwrite any previously set capabilities.
Parameters
- capabilities: {} | Capabilities
  The desired capabilities for a new session.
Returns Builder
A self reference.

Class Builder

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Returns Builder

Methods

build

Returns ThenableWebDriver

Throws

disableEnvironmentOverrides

Returns Builder

forBrowser

Parameters

name: string

Optional opt_version: string

Optional opt_platform: string

Returns Builder

getCapabilities

Returns Capabilities

getChromeOptions

Returns Options

getFirefoxOptions

Returns Options

getHttpAgent

Returns any

getSafariOptions

Returns Options

getServerUrl

Returns string

getWebDriverProxy

Returns null | string

setAlertBehavior

Parameters

Optional behavior: string

Returns Builder

setChromeOptions

Parameters

options: Options

Returns Builder

setChromeService

Parameters

service: ServiceBuilder

Returns Builder

setEdgeOptions

Parameters

options: Options

Returns Builder

setEdgeService

Parameters

service: ServiceBuilder

Returns Builder

setFirefoxOptions

Parameters

options: Options

Returns Builder

setFirefoxService

Parameters

service: ServiceBuilder

Returns Builder

setIeOptions

Parameters

options: Options

Returns Builder

setIeService

Parameters

service: ServiceBuilder

Returns Builder

setLoggingPrefs

Parameters

prefs: {} | Preferences

Returns Builder

setProxy

Parameters

config: ProxyConfig

Returns Builder

setSafariOptions

Parameters

`Optional` opt_version: string

`Optional` opt_platform: string

`Optional` behavior: string