Recognized browser names.

Enumeration of the buttons used in the advanced interactions API.

The standard WebDriver capability keys.

Enum of legacy error codes. TODO: remove this when all code paths have been switched to the new error types.

Represents the type of script evaluation result. Described in https://w3c.github.io/webdriver-bidi/#type-script-EvaluateResult.

Script used to compute the offset from the center of a DOM element's first client rect from the top-left corner of the element's bounding client rect. The element's center point is computed using the algorithm defined here: https://w3c.github.io/webdriver/webdriver-spec.html#dfn-center-point.

This is only exported for use in internal unit tests. DO NOT USE.

Represents the different phases of intercepting network requests and responses.

Representations of pressable keys that aren't text. These are stored in the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. Refer to http://www.google.com.au/search?&q=unicode+pua&btnK=Search

Enumeration of predefined names command names that all command processors will support.

Represents a non-primitive type.

Defines the reference point from which to compute offsets for capturing screenshot.

Defines the reference point from which to compute offsets for pointer move actions.

Strategies for waiting for document readiness after a navigation event.

Common platform names. These platforms are not explicitly defined by the WebDriver spec, however, their use is encouraged for interoperability.

Represents a primitive type.

Protocol for virtual authenticators

Represents the types of realms. Described in https://w3c.github.io/webdriver-bidi/#type-script-RealmType.

Represents the types of remote reference.

Represents a remote value type.

Enum representing the ownership types.

Represents the possible values for the SameSite attribute of a cookie.

Represents a speacial number type.

AuthenticatorTransport values

Represents the types of partition descriptors.

Common log types.

Supported proxy configuration types.

The possible default actions a WebDriver session can take to respond to unhandled user prompts (window.alert(), window.confirm(), and window.prompt()).

Targets that have been previously built.

This implementation is still in beta, and may change.

Utility to find if a given file is present and executable.

Starts the server on the specified port.

Stops the server.

Formats a URL for this server.

Creates a condition that will wait until the input driver is able to switch to the designated frame. The target frame may be specified as

1. a numeric index into window.frames for the currently selected frame.
2. a ./webdriver.WebElement, which must reference a FRAME or IFRAME element on the current page.
3. a locator which may be used to first locate a FRAME or IFRAME on the current page before attempting to switch to it.

Upon successful resolution of this condition, the driver will be left focused on the new frame.

Adds the console handler to the given logger. The console handler will log all messages using the JavaScript Console API.

Creates a condition that waits for an alert to be opened. Upon success, the returned promise will be fulfilled with the handle for the opened alert.

Checks if the two arrays are equal or not. Conditions to check are:

1. If the length of both arrays is equal
2. If all elements of array1 are present in array2
3. If all elements of array2 are present in array1

Determines the path of the correct driver

Builds a fully qualified path using the given set of command parameters. Each path segment prefixed with ':' will be replaced by the value of the corresponding parameter. All parameters spliced into the path will be removed from the parameter map.

Checks if a value is a valid locator.

Checks a legacy response from the Selenium 2.0 wire protocol for an error.

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();

Wraps a function that expects a node-style callback as its final argument. This callback expects two arguments: an error value (which will be null if the call succeeded), and the success value as the second argument. The callback will the resolve or reject the returned promise, based on its arguments.

Logs all messages to the Console API.

Copies one file to another.

Recursively copies the contents of one directory to another.

Creates a promise that will be resolved at a set time in the future.

Configures WebDriver to bypass all browser proxies.

Creates a condition that will wait for the given element to be disabled.

Creates a condition that will wait for the given element to be enabled.

Creates a condition that will wait for the given element to be deselected.

Creates a condition that will wait for the given element to be in the DOM, yet not visible to the user.

Creates a condition that will wait for the given element to be selected.

Creates a condition that will wait for the given element to become visible.

Creates a condition that will loop until an element is found with the given locator.

Creates a condition that will wait for the given element's visible text to contain the given substring.

Creates a condition that will wait for the given element's visible text to match the given {@code text} exactly.

Creates a condition that will wait for the given element's visible text to match a regular expression.

Creates a condition that will loop until at least one element is found with the given locator.

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 chrome.Driver and 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).

Escapes a CSS string.

Spawns a child process. The returned Command may be used to wait for the process result or to send signals to the process.

Translates a command to its wire-protocol representation before passing it to the given executor for execution.

Tests if a file path exists.

Extracts the encoded WebElement ID from the object.

Calls a function for each element in an array, and if the function returns true adds the element to a new array.

If the return value of the filter function is a promise, this function will wait for it to be fulfilled before determining whether to insert the element into the new array.

If the filter function throws or returns a rejected promise, the promise returned by this function will be rejected with the same reason. Only the first failure will be reported; all subsequent errors will be silently ignored.

Searches the {@code PATH} environment variable for the given file.

Converts a value from its JSON representation according to the WebDriver wire protocol. Any JSON object that defines a WebElement ID will be decoded to a WebElement object. All other values will be passed through as is.

Returns a promise that will be resolved with the input value in a fully-resolved state. If the value is an array, each element will be fully resolved. Likewise, if the value is an object, all keys will be fully resolved. In both cases, all nested arrays and objects will also be fully resolved. All fields are resolved in place; the returned promise will resolve on {@code value} and not a copy.

Warning: This function makes no checks against objects that contain cyclical references:

var value = {};
value['self'] = value;
promise.fullyResolved(value);  // Stack overflow.

Retrieves the external IP address for this host.

Determines the path of the correct Selenium Manager binary

Determines the path of the correct Selenium Manager binary

Extracts the browsers for a test suite to target from the SELENIUM_BROWSER environment variable.

initiate browsing context instance and return

Queries the system network interfaces for an IP address.

returns path to java or 'java' string if JAVA_HOME does not exist in env obj

Converts a level name or value to a Level value. If the name/value is not recognized, Level.ALL will be returned.

initiate inspector instance and return

Retrieves a named logger, creating it in the process. This function will implicitly create the requested logger, and any of its parents, if they do not yet exist.

The log level will be unspecified for newly created loggers. Use Logger#setLevel(level) to explicitly set a level.

Retrieves a loopback address for this machine.

Queries a WebDriver server for its current status.

Converts a headers map to a HTTP header block string.

Returns an object with wrappers for the standard mocha/jasmine test functions: describe and it, which will redirect to xdescribe and xit, respectively, if provided predicate function returns false.

Sample usage:

const {Browser} = require('selenium-webdriver');
const {suite, ignore} = require('selenium-webdriver/testing');

suite(function(env) {

    // Skip tests the current environment targets Chrome.
    ignore(env.browsers(Browser.CHROME)).
    describe('something', async function() {
      let driver = await env.builder().build();
      // etc.
    });
});

Initializes this module by determining which browsers a test suite should run against. The default behavior is to run tests against every browser with a WebDriver executables (chromedriver, firefoxdriver, etc.) are installed on the system by PATH.

Specific browsers can be selected at runtime by setting the SELENIUM_BROWSER environment variable. This environment variable has the same semantics as with the WebDriver Builder, except you may use a comma-delimited list to run against multiple browsers:

SELENIUM_BROWSER=chrome,firefox mocha --recursive tests/

The SELENIUM_REMOTE_URL environment variable may be set to configure tests to run against an externally managed (usually remote) Selenium server. When set, the WebDriver builder provided by each TestEnvironment will automatically be configured to use this server instead of starting a browser driver locally.

The SELENIUM_SERVER_JAR environment variable may be set to the path of a standalone Selenium server on the local machine that should be used for WebDriver sessions. When set, the WebDriver builder provided by each TestEnvironment will automatically be configured to use the started server instead of using a browser driver directly. It should only be necessary to set the SELENIUM_SERVER_JAR when testing locally against browsers not natively supported by the WebDriver Builder.

When either of the SELENIUM_REMOTE_URL or SELENIUM_SERVER_JAR environment variables are set, the SELENIUM_BROWSER variable must also be set.

Installs the console log handler on the root logger.

Tests if the given value is a valid error response object according to the W3C WebDriver spec.

Tests if a port is free.

Determines whether a {@code value} should be treated as an object.

Determines whether a {@code value} should be treated as a promise. Any object whose "then" property is a function will be considered a promise.

Asynchronously opens a zip archive.

Locates a test resource.

Start searching for relative objects using search criteria with By.

Manually configures the browser proxy. The following options are supported:

• ftp: Proxy host to use for FTP requests
• http: Proxy host to use for HTTP requests
• https: Proxy host to use for HTTPS requests
• bypass: A list of hosts requests should directly connect to, bypassing any other proxies for that request. May be specified as a comma separated string, or a list of strings.

Behavior is undefined for FTP, HTTP, and HTTPS requests if the corresponding key is omitted from the configuration options.

Calls a function for each element in an array and inserts the result into a new array, which is used as the fulfillment value of the promise returned by this function.

If the return value of the mapping function is a promise, this function will wait for it to be fulfilled before inserting it into the new array.

If the mapping function throws or returns a rejected promise, the promise returned by this function will be rejected with the same reason. Only the first failure will be reported; all subsequent errors will be silently ignored.

Creates a directory.

Recursively creates a directory and any ancestors that do not yet exist.

Creates a build of the listed targets.

Configures WebDriver to configure the browser proxy using the PAC file at the given URL.

Pads a number to ensure it has a minimum of two digits.

Callback used to parse Response objects from a HttpClient.

Reads the contents of the given file.

Removes the console log handler from the given logger.

Resolves a wait message from either a function or a string.

Recursively removes a directory and all of its contents. This is equivalent to {@code rm -rf} on a POSIX system.

Responds to a request for the file server's main index.

Sends a single HTTP request.

Serializes a capabilities object. This is defined as a standalone function so it may be type checked (where Capabilities[Symbols.serialize] has type checking disabled since it is defined with [] access on a struct).

A retry is sometimes needed on Windows where we may quickly run out of ephemeral ports. A more robust solution is bumping the MaxUserPort setting as described here: http://msdn.microsoft.com/en-us/library/aa560610%28v=bts.20%29.aspx

Creates a proxy configuration for a socks proxy.

Example:

const {Capabilities} = require('selenium-webdriver');
const proxy = require('selenium-webdriver/lib/proxy');

let capabilities = new Capabilities();
capabilities.setProxy(proxy.socks('localhost:1234'));

// Or, to include authentication.
capabilities.setProxy(proxy.socks('bob:password@localhost:1234'));

Splits a hostport string, e.g. "www.example.com:80", into its component parts.

Creates a condition that will wait for the given element to become stale. An element is considered stale once it is removed from the DOM, or a new page has loaded.

Starts an instance of the Selenium server if not yet running.

Calls stat(2).

Defines a test suite by calling the provided function once for each of the target browsers. If a suite is not limited to a specific set of browsers in the provided suite options, the suite will be configured to run against each of the runtime target browsers.

Sample usage:

const {By, Key, until} = require('selenium-webdriver');
const {suite} = require('selenium-webdriver/testing');

suite(function(env) {
  describe('Google Search', function() {
    let driver;

    before(async function() {
      driver = await env.builder().build();
    });

    after(() => driver.quit());

    it('demo', async function() {
      await driver.get('http://www.google.com/ncr');

      let q = await driver.findElement(By.name('q'));
      await q.sendKeys('webdriver', Key.RETURN);
      await driver.wait(
          until.titleIs('webdriver - Google Search'), 1000);
    });
  });
});

By default, this example suite will run against every WebDriver-enabled browser on the current system. Alternatively, the SELENIUM_BROWSER environment variable may be used to run against a specific browser:

SELENIUM_BROWSER=firefox mocha -t 120000 example_test.js

Configures WebDriver to use the current system's proxy.

Registers a listener to invoke when a promise is resolved, regardless of whether the promise's value was successfully computed. This function is synonymous with the {@code finally} clause in a synchronous API:

// Synchronous API:
try {
  doSynchronousWork();
} finally {
  cleanUp();
}

// Asynchronous promise API:
doAsynchronousWork().finally(cleanUp);

Note: similar to the {@code finally} clause, if the registered callback returns a rejected promise or throws an error, it will silently replace the rejection error (if any) from this promise:

try {
  throw Error('one');
} finally {
  throw Error('two');  // Hides Error: one
}

let p = Promise.reject(Error('one'));
promise.finally(p, function() {
  throw Error('two');  // Hides Error: one
});

Throws an error coded from the W3C protocol. A generic error will be thrown if the provided data is not a valid encoded error.

Creates a condition that will wait for the current page's title to contain the given substring.

Creates a condition that will wait for the current page's title to match the given value.

Creates a condition that will wait for the current page's title to match the given regular expression.

Converts a generic hash object to a map.

Converts an object to its JSON representation in the WebDriver wire protocol. When converting values of type object, the following steps will be taken:

1. if the object is a WebElement, the return value will be the element's server ID
2. if the object defines a Symbols.serialize method, this algorithm will be recursively applied to the object's serialized representation
3. if the object provides a "toJSON" function, this algorithm will recursively be applied to the result of that function
4. otherwise, the value of each key will be recursively converted according to the rules above.

Deletes a name from the filesystem and possibly the file it refers to. Has no effect if the file does not exist.

Asynchronously unzips an archive file.

Creates a condition that will wait for the current page's url to contain the given substring.

Creates a condition that will wait for the current page's url to match the given value.

Creates a condition that will wait for the current page's url to match the given regular expression.

Waits for a WebDriver server to be healthy and accepting requests.

Polls a URL with GET requests until it returns a 2xx response or the timeout expires.

Recursively walks a directory, returning a promise that will resolve with a list of all files/directories seen.

Builds the URL for a file in the //common/src/web directory of the Selenium client.

Start Searching for relative objects using the value returned from By.tagName().

Note: this method will likely be removed in the future please use locateWith.