WebDriver

Various parts of this specification are written in terms of step-by-step algorithms. The details of these algorithms do not have any normative significance; implementations are free to adopt any implementation strategy that produces equivalent output to the specification. In particular, algorithms in this document are optimized for readability rather than performance.

Where algorithms that return values are fallible, they are written in terms of returning either success or error. A success value has an associated data field which encapsulates the value returned, whereas an error value has an associated error code.

When calling a fallible algorithm, the construct “Let result be the result of trying to call algorithm” is equivalent to

1. Let temp be the result of calling algorithm.

2. If temp is an error return temp, otherwise let result be temp's data field.

The result of getting a property with name from object is defined as being the same as the result of calling Object.[[GetOwnProperty]](name) on object.

The result of getting a property with default with arguments name and default from object is defined as being the same as the result of calling Object.[[GetOwnProperty]](name) on object if that results in a value other than undefined and default otherwise.

Setting a property with arguments name and value on object is defined as being the same as calling Object.[[Put]](name, value) on object.

The result of JSON serialization with object of type JSON Object is defined as the result of calling stringify(object).

The result of JSON deserialization with text is defined as the result of calling parse(text).

The WebDriver protocol is organized into commands. Each HTTP request with a method and template defined in this specification represents a single command, and therefore each command produces a single HTTP response.

In response to a command, a remote end will run a series of actions known as remote end steps. These provide the sequences of actions that a remote end takes when it receives a particular command.

The remote end is an HTTP server reading requests from the client and writing responses, typically over a TCP socket. For the purposes of this specification we model the data transmission between a particular local end and remote end with a connection to which the remote end may write bytes and read bytes. However the exact details of how this connection works and how it is established are out of scope.

After a connection is established, the remote end must run the following steps:

1. While the connection is not closed:

   1. Read bytes from the connection until a complete HTTP request can be constructed from the data. Let request be a request constructed from the received data, according to the requirements of [RFC7230]. If it is not possible to construct a complete HTTP request, the remote end must either close the connection, return an HTTP response with status code 500, or return an error with error code unknown error.

   2. Let request match be the result of the algorithm to match a request with request's method and URL as arguments.

   3. If request match is of type error, send an error with request match's error code and continue.

      Otherwise, let command and URL variables be request match's data.

   4. Let session be null.

   5. If URL variables contains "session id":

      Note

      This condition is intended to exclude the New Session and Status commands and any extension commands which do not operate on a particular session.

      1. Let session id be URL variables["session id"].

      2. For each active session in the list of active sessions:

         1. If active session's session ID is equal to session id, then let session be active session, and break.

      3. If the session is null send an error with error code invalid session id, then continue.

   6. Enqueue a task on remote end's request queue to run the following steps:

      1. If session is no longer in the list of active sessions, then send an error with error code invalid session id and return.

      2. Let parameters be null.

      3. If request's method is POST:

         1. Let parse result be the result of parsing as JSON with request's body as the argument. If this process throws an exception, return an error with error code invalid argument and jump back to step 1 in this overall algorithm.

         2. If parse result is not an Object, send an error with error code invalid argument and jump back to step 1 in this overall algorithm.

            Otherwise, let parameters be parse result.

      4. Let navigate result be the result of wait for navigation to complete with session.

      5. If navigate result is an error, send an error with error code equal to navigate result's error code and return.

      6. Let response result be the return value obtained by running the remote end steps for command with session, URL variables, and parameters.

      7. If response result is an error, send an error with error code equal to response result's error code and return.

      8. Assert: response result is a success.

      9. Let response data be response result's data.

      10. Send a response with status 200 and response data.

When required to send an error, with error code and an optional error data dictionary, a remote end must run the following steps:

1. Let status and name be the error response data for error code.

2. Let message be an implementation-defined string containing a human-readable description of the reason for the error.

3. Let stacktrace be an implementation-defined string containing a stack trace report of the active stack frames at the time when the error occurred.

   Let body be a new JSON Object initialized with the following properties:

   "error"

   name

   "message"

   message

   "stacktrace"

   stacktrace

4. If the error data dictionary contains any entries, set the "data" field on body to a new JSON Object populated with the dictionary.

5. Send a response with status and body as arguments.

When required to send a response, with arguments status and data, a remote end must run the following steps:

1. Let response be a new response.

2. Set response's HTTP status to status, and status message to the string corresponding to the description of status in the status code registry.

3. Set the response's header with name and value with the following values:

   Content-Type

   "application/json; charset=utf-8"

   Cache-Control

   "no-cache"

4. Let response's body be the UTF-8 encoded JSON serialization of a JSON Object with a key "value" set to data.

5. Let response bytes be the byte sequence resulting from serializing response according to the rules in [RFC7230].

6. Write response bytes to the connection.

Request routing is the process of going from an HTTP request to the series of steps needed to implement the command represented by that request.

A remote end has an associated URL prefix, which is used as a prefix on all WebDriver-defined URLs on that remote end. This must either be undefined or a path-absolute URL.

In order to match a request given a method and URL, the following steps must be taken:

1. Let endpoints be a list containing each row in the table of endpoints.

2. Remove each entry from endpoints for which the concatenation of the URL prefix and the entry's URI template does not have a valid expansion equal to URL's path.

3. If there are no entries in endpoints, return error with error code unknown command.

4. Remove each entry in endpoints for which the method column is not equal to method.

5. If there are no entries in endpoints, return error with error code unknown method.

6. There is now exactly one entry in endpoints; let entry be this entry.

7. Let URI template be the concatenation of URL prefix with entry's URI template.

8. Let command be entry's command.

9. Let URL variables be a map with one entry for each variable defined in URI template, with the entry name equal to the template variable name, and the entry value being the variable value required to expand the URI template to match URL's path.

10. Return success with data command and URL variables.

The following table of endpoints lists the method and URI template for each endpoint node command. Extension commands are implicitly appended to this table.

Errors are represented in the WebDriver protocol by an HTTP response with an HTTP status in the 4xx or 5xx range, and a JSON body containing details of the error. The body is a JSON Object and has a field named "value" whose value is an object bearing three, and sometimes four, fields:

• "error", containing a string indicating the error code.
• "message", containing an implementation-defined string with a human readable description of the kind of error that occurred.
• "stacktrace", containing an implementation-defined string with a stack trace report of the active stack frames at the time when the error occurred.
• Optionally "data", which is a JSON Object with additional error data helpful in diagnosing the error.

The following table lists each error code, its associated HTTP status, JSON error code, and a non-normative description of the error. The error response data for a particular error code is the values of the HTTP Status and JSON Error Code columns for the row corresponding to that error code.

An error data dictionary is a mapping of string keys to JSON serializable values that can optionally be included with error objects.

Using the terminology defined in this section, others may define additional commands that seamlessly integrate with the standard protocol. This allows vendors to expose functionality that is specific to their user agent, and it also allows other web standards to define commands for automating new platform features.

Commands defined in this way are called extension commands and behave no differently than other commands; each has a dedicated HTTP endpoint and a set of remote end steps.

Each extension command has an associated extension command URI Template that is a URI Template string, and which should bear some resemblance to what the command performs. This value, along with the HTTP method and extension command, is added to the table of endpoints and thus follows the same rules for request routing as that of other built-in commands.

In order to avoid potential resource conflicts with other implementations, vendor-specific extension command URI Templates must begin with one or more path segments which uniquely identifies the vendor and UA. It is suggested that vendors use their vendor prefixes without additional characters as outlined in [CSS21], notably in section 4.1.2.2 on vendor keywords, as the name for this path element, and include a vendor-chosen UA identifier.

Other specifications may define additional WebDriver capabilities. Each defined capability must have a capability name which is a string not containing a ":" (colon) character, an additional capability deserialization algorithm which is a set of steps taking a single argument value which has a JSON type, returning either success wrapping the deserialized capability value or error.

An additional WebDriver capability may also define a matched capability serialization algorithm, which is a set of steps used to determine if a capability is matched by the current implementation and provide any computed value to return to the user. This set of steps takes a single argument value, which is the output of the corresponding additional capability deserialization algorithm, and returns either null to indicate the capability is not matched, or a non-null JSON-serializable value if the capability is matched.

Other specifications may also define WebDriver new session algorithms, which are called just after a new session is created, and before the new session response is sent to the remote end. These algorithms are called with session representing the WebDriver session that will be established, and capabilities, the capabilities object that will be returned to the remote end. It is permitted for such an algorithm to modify any entry in the capabilities object with a name that's an additional WebDriver capability defined by the same specification.

Remote ends may also introduce extension capabilities that are extra capabilities used to provide configuration or fulfill other vendor-specific needs. Extension capabilities' key must contain a ":" (colon) character, denoting an implementation specific namespace. The value can be arbitrary JSON types.

As with extension commands, it is suggested that the key used to denote the extension capability namespace is based on the vendor keywords listed in [CSS21] and precedes the first ":" character in the string.

The proxy configuration capability is a JSON Object nested within the primary capabilities. Implementations may define additional proxy configuration options, but they must not alter the semantics of those listed below.

A host and optional port for a scheme is defined as being a valid host, optionally followed by a colon and a valid port. The host may include credentials. If the port is omitted and scheme has a default port, this is the implied port. Otherwise, the port is left undefined.

A proxyType of "direct" indicates that the browser should not use a proxy at all.

A proxyType of "system" indicates that the browser should use the various proxies configured for the underlying Operating System.

A proxyType of "autodetect" indicates that the proxy to use should be detected in an implementation-specific way.

The remote end steps to deserialize as a proxy argument parameter are:

1. If parameter is not a JSON Object return an error with error code invalid argument.

2. Let proxy be a new, empty proxy configuration object.

3. For each enumerable own property in parameter run the following substeps:

   1. Let key be the name of the property.

   2. Let value be the result of getting a property named name from parameter.

   3. If there is no matching key for key in the proxy configuration table return an error with error code invalid argument.

   4. If value is not one of the valid values for that key, return an error with error code invalid argument.

   5. Set a property key to value on proxy.

4. If proxy does not have an own property for "proxyType" return an error with error code invalid argument.

5. If the result of getting a property named "proxyType" from proxy equals "pac", and proxy does not have an own property for "proxyAutoconfigUrl" return an error with error code invalid argument.

6. If proxy has an own property for "socksProxy" and does not have an own property for "socksVersion" return an error with error code invalid argument.

7. Return success with data proxy.

A proxy configuration object is a JSON Object where each of its own properties matching keys in the proxy configuration meets the validity criteria for that key.

To process capabilities given parameters, and session configuration flags flags, the endpoint node must take the following steps:

1. Let capabilities request be the result of getting the property "capabilities" from parameters.

   1. If capabilities request is not a JSON Object, return error with error code invalid argument.

2. Let required capabilities be the result of getting the property "alwaysMatch" from capabilities request.

   1. If required capabilities is undefined, set the value to an empty JSON Object.

   2. Let required capabilities be the result of trying to validate capabilities with arguments required capabilities and flag.

3. Let all first match capabilities be the result of getting the property "firstMatch" from capabilities request.

   1. If all first match capabilities is undefined, set the value to a List with a single entry of an empty JSON Object.

   2. If all first match capabilities is not a List with one or more entries, return error with error code invalid argument.

4. Let validated first match capabilities be an empty List.

5. For each first match capabilities corresponding to an indexed property in all first match capabilities:

   1. Let validated capabilities be the result of trying to validate capabilities with arguments first match capabilities and flags.

   2. Append validated capabilities to validated first match capabilities.

6. Let merged capabilities be an empty List.

7. For each first match capabilities corresponding to an indexed property in validated first match capabilities:

   1. Let merged be the result of trying to merge capabilities with required capabilities and first match capabilities as arguments.

   2. Append merged to merged capabilities.

8. For each capabilities corresponding to an indexed property in merged capabilities:

   1. Let matched capabilities be the result of trying to match capabilities with capabilities as an argument.

   2. If matched capabilities is not null, return success with data matched capabilities.

9. Return success with data null.

When required to validate capabilities with argument capabilities:

1. If capabilities is not a JSON Object return an error with error code invalid argument.

2. Let result be an empty JSON Object.

3. For each enumerable own property in capabilities, run the following substeps:

   1. Let name be the name of the property.

   2. Let value be the result of getting a property named name from capabilities.

   3. Run the substeps of the first matching condition:

      value is null

      Let deserialized be set to null.

      name equals "acceptInsecureCerts"

      If value is not a boolean return an error with error code invalid argument. Otherwise, let deserialized be set to value.

      name equals "browserName"

      name equals "browserVersion"

      name equals "platformName"

      If value is not a string return an error with error code invalid argument. Otherwise, let deserialized be set to value.

      name equals "pageLoadStrategy"

      Let deserialized be the result of trying to deserialize as a page load strategy with argument value.

      name equals "proxy"

      Let deserialized be the result of trying to deserialize as a proxy with argument value.

      name equals "strictFileInteractability"

      If value is not a boolean return an error with error code invalid argument. Otherwise, let deserialized be set to value

      name equals "timeouts"

      Let deserialized be the result of trying to deserialize as timeouts configuration with value.

      name equals "unhandledPromptBehavior"

      Let deserialized be the result of trying to deserialize as an unhandled prompt behavior with argument value.

      name is the name of an additional WebDriver capability

      Let deserialized be the result of trying to run the additional capability deserialization algorithm for the extension capability corresponding to name, with argument value.

      name is the key of an extension capability

      If name is known to the implementation, let deserialized be the result of trying to deserialize value in an implementation-specific way. Otherwise, let deserialized be set to value.

      The remote end is an endpoint node

      Return an error with error code invalid argument.

   4. If deserialized is not null, set a property on result with name name and value deserialized.

4. Return success with data result.

When merging capabilities with JSON Object arguments primary and secondary, an endpoint node must take the following steps:

1. Let result be a new JSON Object.

2. For each enumerable own property in primary, run the following substeps:

   1. Let name be the name of the property.

   2. Let value be the result of getting a property named name from primary.

   3. Set a property on result with name name and value value.

3. If secondary is undefined, return result.

4. For each enumerable own property in secondary, run the following substeps:

   1. Let name be the name of the property.

   2. Let value be the result of getting a property named name from secondary.

   3. Let primary value be the result of getting the property name from primary.

   4. If primary value is not undefined, return an error with error code invalid argument.

   5. Set a property on result with name name and value value.

5. Return result.

When matching capabilities given JSON Object capabilities, and a session configuration flags flags, an endpoint node must take the following steps:

1. Let matched capabilities be a JSON Object with the following entries:

   "browserName"

   ASCII Lowercase name of the user agent as a string.

   "browserVersion"

   The user agent version, as a string.

   "platformName"

   ASCII Lowercase name of the current platform as a string.

   "acceptInsecureCerts"

   Boolean initially set to false, indicating the session will not implicitly trust untrusted or self-signed TLS certificates on navigation.

   "strictFileInteractability"

   Boolean initially set to false, indicating that interactability checks will be applied to <input type=file>.

   "setWindowRect"

   Boolean indicating whether the remote end supports all of the resizing and positioning commands.

   "userAgent"

   String containing the default User-Agent value.

2. If flags contains "http", add the following entries to matched capabilities:

   "strictFileInteractability"

   Boolean initially set to false, indicating that interactabilty checks will be applied to <input type=file>.

3. Optionally add extension capabilities as entries to matched capabilities. The values of these may be elided, and there is no requirement that all extension capabilities be added.

   Note

4. For each name and value corresponding to capabilities's own properties:

   1. Let match value equal value.

   2. Run the substeps of the first matching name:

      "browserName"

      If value is not a string equal to the "browserName" entry in matched capabilities, return success with data null.

      Note

      There is a chance the remote end will need to start a browser process to correctly determine the browserName. Lightweight checks are preferred before this is done.

      "browserVersion"

      Compare value to the "browserVersion" entry in matched capabilities using an implementation-defined comparison algorithm. The comparison is to accept a value that places constraints on the version using the "<", "<=", ">", and ">=" operators.

      If the two values do not match, return success with data null.

      Note

      Version comparison is left as an implementation detail since each user agent will likely have conflicting methods of encoding the user agent version, and standardizing these schemes is beyond the scope of this standard.

      Note

      There is a chance the remote end will need to start a browser process to correctly determine the browserVersion. Lightweight checks are preferred before this is done.

      "platformName"

      If value is not a string equal to the "platformName" entry in matched capabilities, return success with data null.

      Note

      The following platform names are in common usage with well-understood semantics and, when matching capabilities for platform name, greatest interoperability can be achieved by honoring them as valid synonyms for well-known Operating Systems:

      Key	System
      "linux"	Any server or desktop system based upon the Linux kernel.
      "mac"	Any version of Apple's macOS.
      "windows"	Any version of Microsoft Windows, including desktop and mobile versions.

      This list is not exhaustive.

      When returning capabilities from New Session, it is valid to return a more specific platformName, allowing users to correctly identify the Operating System the WebDriver implementation is running on.

      "acceptInsecureCerts"

      If accept insecure TLS flag is set and not equal to value, return success with data null.

      Note

      If the endpoint node does not support insecure TLS certificates and this is the reason no match is ultimately made, it is useful to provide this information to the local end.

      "proxy"

      If the has proxy configuration flag is set, or if the proxy configuration defined in value is not one that passes the endpoint node's implementation-specific validity checks, return success with data null.

      Note

      A local end would only send this capability if it expected it to be honored and the configured proxy used. The intent is that if this is not possible a new session will not be established.

      "unhandledPromptBehavior"

      If check user prompt handler matches with value is false, return success with data null.

      Otherwise

      • If name is the name of an additional WebDriver capability which defines a matched capability serialization algorithm, let match value be the result of running the matched capability serialization algorithm for capability name with arguments value, and flags.

      • Otherwise, if name is the key of an extension capability, let match value be the result of trying implementation-specific steps to match on name with value. If the match is not successful, return success with data null.

   3. If match value is not null, set a property on matched capabilities with name name and value match value.

5. Return success with data matched capabilities.