Algorithms

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 optimised 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 response 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 argument name is defined as being the same as the result of calling Object.[[\GetOwnProperty]](name).

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

The result of JSON serialization with object of type JSON Object is defined as the result of calling JSON.[[\Stringify]](object).

The result of JSON deserialization with text is defined as the result of calling JSON.[[\Parse]](text).

Commands

The WebDriver protocol is organised 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.

Processing model

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 such a connection has been established, a remote end must run the following steps:

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 jump to step 1.

   Otherwise, let command and command parameters be request match’s data. Let url variables be a url variables dictionary mapping the command parameters to their corresponding values.

4. If session id is among the variables defined by command parameters:

   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 the corresponding variable from command parameters.

   2. Let the current session be the session with ID session id in the list of active sessions, or null if there is no such matching session.

   3. If the current session is null send an error with error code invalid session id, then jump to step 1 in this overall algorithm.

   4. If the current session is not null:

      1. Enqueue request in the current session’s request queue.

      2. Wait until the first element in the current session’s request queue is request:

      3. Dequeue request from the current session’s request queue.

      4. If the list of active sessions no longer contains the current session, set the current session to null.

5. 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.

   Otherwise, let parameters be null.

6. Wait for navigation to complete. If this returns an error return its value and jump to step 1 in this overall algorithm, otherwise continue.

7. Let response result be the return value obtained by running the remote end steps for command with an argument named url variables whose value is url variables and an additional argument named parameters whose value is parameters.

8. If response result is an error, send an error with error code equal to response result’s error code and jump back to step 1 in this overall algorithm.

   Otherwise, if response result is a success, let response data be response result’s data.

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

10. Jump to step 1.

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 http 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 initialised 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 a JSON Object with a key "value" set to the JSON serialization of 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.

A url variable dictionary is defined as the mapping of a command’s URI template variable names to their corresponding values.

Routing requests

Request routing is the process of going from a 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 match 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 an exact case-sensitive match for 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 parameters be the result of extracting the variables from URL using entry’s URI template.

8. Let command be entry’s command.

9. Return success with data command and parameters.

Endpoints

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

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.

Extensions

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.

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.

Proxy

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.

Processing capabilities

To process capabilities with argument parameters, 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 argument required capabilities.

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 JSON List with a single entry of an empty JSON Object.

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

4. Let validated first match capabilities be an empty JSON 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 argument first match capabilities.

   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 matched capabilities.

9. Return success with data null.

When required to validate capabilities with argument capability:

1. If capability 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 capability, 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 capability.

   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 JSON deserialize as a timeouts configuration the value.

      name equals "unhandledPromptBehavior"

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

      name is the key of an extension capability

      Let deserialized be the result of trying to deserialize value in an implementation-specific way.

      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 with JSON Object argument capabilities, an endpoint node must take the following steps:

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

   "browserName"

   Lowercase name of the user agent as a string.

   "browserVersion"

   The user agent version, as a string.

   "platformName"

   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 interactabilty checks will be applied to <input type=file>.

   "setWindowRect"

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

2. 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.

3. For each name and value corresponding to capability’s own properties:

   1. 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.

      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.

      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.

      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.

      The following platform names are in common usage with well-understood semantics and, when matching capabilities, 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 value is true and the endpoint node does not support insecure TLS certificates, return success with data null.

      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 endpoint node does not allow the proxy it uses to be configured, 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.

      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.

      Otherwise

      If name is the key of an extension capability,

      let 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.

   2. Set a property on matched capabilities with name name and value value.

4. Return success with data matched capabilities.

New Session

The New Session command creates a new WebDriver session with the endpoint node. If the creation fails, a session not created error is returned.

If the remote end is an intermediary node, it may use the result of the capabilities processing algorithm to route the new session request to the appropriate endpoint node. An intermediary node is free to define extension capabilities to assist in this process, however, these specific capabilities must not be forwarded to the endpoint node.

If the intermediary node requires additional information unrelated to user agent features, it is recommended that this information be passed as top-level parameters, and not as part of the requested capabilities. An intermediary node must forward custom, top-level parameters (i.e. non-capabilities) to subsequent remote end nodes.

The remote end steps are:

1. If the maximum active sessions is equal to the length of the list of active sessions, return error with error code session not created.

2. If the remote end is an intermediary node, take implementation-defined steps that either result in returning an error with error code session not created, or in returning a success with data that is isomorphic to that returned by remote ends according to the rest of this algorithm. If an error is not returned, the intermediary node must retain a reference to the session created on the upstream node as the associated session such that commands may be forwarded to this associated session on subsequent commands.

   How this is done is entirely up to the implementation, but typically the sessionId, and URL and URL prefix of the upstream remote end will need to be tracked.

3. If the maximum active sessions is equal to the length of the list of active sessions, return error with error code session not created.

4. Let capabilities be the result of trying to process capabilities with parameters as an argument.

5. If capabilities’s is null, return error with error code session not created.

6. Let session id be the result of generating a UUID.

7. Let session be a new session with the session ID of session id.

8. Set the current session to session.

9. Append session to active sessions.

10. Let body be a JSON Object initialised with:

    "sessionId"

    session id

    "capabilities"

    capabilities

11. Initialize the following from capabilities:

    1. Let strategy be the result of getting property "pageLoadStrategy" from capabilities.

    2. If strategy is a string, set the current session’s page loading strategy to strategy. Otherwise, set the page loading strategy to normal and set a property of capabilities with name "pageLoadStrategy" and value "normal".

    3. Let strictFileInteractability be the result of getting property "strictFileInteractability" from capabilities.

    4. If strictFileInteractability is a boolean, set the current session’s strict file interactability to strictFileInteractability. Otherwise set the current session’s strict file interactability to false.

    5. Let proxy be the result of getting property "proxy" from capabilities and run the substeps of the first matching statement:

       proxy is a proxy configuration object

       Take implementation-defined steps to set the user agent proxy using the extracted proxy configuration. If the defined proxy cannot be configured return error with error code session not created.

       Otherwise

       Set a property of capabilities with name "proxy" and a value that is a new JSON Object.

    6. If capabilities has a property with the key "timeouts":

       1. Let timeouts be the result of trying to JSON deserialize as a timeouts configuration the value of the "timeouts" property.

       2. Make the session timeouts the new timeouts.

    7. Set a property on capabilities with name "timeouts" and value that of the JSON deserialization of the session timeouts.

    8. Apply changes to the user agent for any implementation-defined capabilities selected during the capabilities processing step.

12. Set the webdriver-active flag to true.

13. Set the current top-level browsing context for session in an implementation-specific way. This should be the top-level browsing context of the UA’s current browsing context.

    WebDriver implementations typically start a completely new browser instance, but there is no requirement in this specification (or for WebDriver only to be used to automate only web browsers). Implementations might choose to use an existing browser instance, eg. by selecting the window that currently has focus.

14. Set the request queue to a new queue.

15. Return success with data body.

Delete Session

The remote end steps are:

1. If the current session is an active session, try to close the session.

2. Return success with data null.

Status

Implementations may optionally include additional meta information as part of the body, but the top-level properties ready and message are reserved and must not be overwritten.

The remote end steps are:

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

   "ready"

   The remote end’s readiness state.

   "message"

   An implementation-defined string explaining the remote end’s readiness state.

2. Return success with data body.

Get Timeouts

The remote end step is to return success with data being the JSON serialization of the active session’s timeouts configuration.

Set Timeouts

The remote end steps are:

1. Let timeouts be the result of trying to JSON deserialize as a timeouts configuration the request’s parameters.

2. Make the session timeouts the new timeouts.

3. Return success with data null.

Navigate To

The command causes the user agent to navigate the current top-level browsing context to a new location.

If the session is not in a secure TLS state, no certificate errors that would normally cause the user agent to abort and show a security warning are to hinder navigation to the requested address.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let url be the result of getting the property url from the parameters argument.

3. If url is not an absolute URL or is not an absolute URL with fragment or not a local scheme, return error with error code invalid argument.

4. Handle any user prompts and return its value if it is an error.

5. Let current URL be the current top-level browsing context’s active document’s document URL.

6. If current URL and url do not have the same absolute URL:

   1. If timer has not been started, start a timer. If this algorithm has not completed before timer reaches the session’s session page load timeout in milliseconds, return an error with error code timeout.

7. Navigate the current top-level browsing context to url.

8. If url is special except for file and current URL and URL do not have the same absolute URL :

   1. Try to wait for navigation to complete.

   2. Try to run the post-navigation checks.

9. Set the current browsing context to the current top-level browsing context.

10. If the current top-level browsing context contains a refresh state pragma directive of time 1 second or less, wait until the refresh timeout has elapsed, a new navigate has begun, and return to the first step of this algorithm.

11. Return success with data null.

Get Current URL

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Let url be the serialization of the current top-level browsing context’s active document’s document URL.

4. Return success with data url.

Back

This command causes the browser to traverse one step backward in the joint session history of the current top-level browsing context. This is equivalent to pressing the back button in the browser chrome or invoking window.history.back.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Traverse the history by a delta –1 for the current browsing context.

4. If the previous step completed results in a pageHide event firing, wait until pageShow event fires or for the session page load timeout milliseconds to pass, whichever occurs sooner.

5. If the previous step completed by the session page load timeout being reached, and user prompts have been handled, return error with error code timeout.

6. Return success with data null.

Forward

This command causes the browser to traverse one step forwards in the joint session history of the current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Traverse the history by a delta 1 for the current browsing context.

4. If the previous step completed results in a pageHide event firing, wait until pageShow event fires or for the session page load timeout milliseconds to pass, whichever occurs sooner.

5. If the previous step completed by the session page load timeout being reached, and user prompts have been handled, return error with error code timeout.

6. Return success with data null.

Refresh

This command causes the browser to reload the page in the current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Initiate an overridden reload of the current top-level browsing context’s active document.

4. If url is special except for file:

   1. Try to wait for navigation to complete.

   2. Try to run the post-navigation checks.

5. Set the current browsing context to the current top-level browsing context.

6. Return success with data null.

Get Title

This command returns the document title of the current top-level browsing context, equivalent to calling document.title.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Let title be the result of calling the algorithm for getting the title attribute of the current top-level browsing context’s active document.

4. Return success with data title.

Get Window Handle

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Return success with data being the window handle associated with the current top-level browsing context.

Close Window

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Close the current top-level browsing context.

4. If there are no more open top-level browsing contexts, then try to close the session.

5. Return the result of running the remote end steps for the Get Window Handles command.

Switch To Window

Switching window will select the current top-level browsing context used as the target for all subsequent commands. In a tabbed browser, this will typically make the tab containing the browsing context the selected tab.

The remote end steps are:

1. Let handle be the result of getting the property "handle" from the parameters argument.

2. If handle is undefined, return error with error code invalid argument.

3. If there is an active user prompt, that prevents the focussing of another top-level browsing context, return error with error code unexpected alert open.

4. If handle is equal to the associated window handle for some top-level browsing context in the current session, set the session’s current browsing context to that browsing context.

   Otherwise, return error with error code no such window.

5. Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.

6. Return success with data null.

Get Window Handles

The order in which the window handles are returned is arbitrary.

The remote end steps are:

1. Let handles be a JSON List.

2. For each top-level browsing context in the remote end, push the associated window handle onto handles.

3. Return success with data handles.

New Window

Create a new top-level browsing context.

The remote end steps are:

1. If the implementation does not support creating new top-level browsing contexts, return error with error code unsupported operation.

2. If the current top-level browsing context is no longer open, return error with error code no such window.

3. Handle any user prompts and return its value if it is an error.

4. Let type hint be the result of getting the property "type" from the parameters argument.

5. Create a new top-level browsing context by running the window open steps with url set to "about:blank", target set to the empty string, and features set to "noopener" and the user agent configured to create a new browing context. This must be done without invoking the focusing steps for the created browsing context. If type hint has the value "tab", and the implementation supports multiple browsing context in the same OS window, the new browsing context should share an OS window with the current browsing context. If type hint is "window", and the implementation supports multiple browsing contexts in seperate OS windows, the created browsing context should be in a new OS window. In all other cases the details of how the browsing context is presented to the user are implementation defined.

6. Let handle be the associated window handle of the newly created window.

7. Let type be "tab" if the newly created window shares an OS-level window with the current browsing context, or "window" otherwise.

8. Let result be a new JSON Object initialised with:

   "handle"

   The value of handle.

   "type"

   The value of type.

9. Return success with data result.

Switch To Frame

The Switch To Frame command is used to select the current top-level browsing context or a child browsing context of the current browsing context to use as the current browsing context for subsequent commands.

The remote end steps are:

1. Let id be the result of getting the property "id" from the parameters argument.

2. If id is not null, a Number object, or an Object that represents a web element, return error with error code invalid argument.

3. If the current browsing context is no longer open, return error with error code no such window.

4. Handle any user prompts and return its value if it is an error.

5. Run the substeps of the first matching condition:

   id is null

   1. Set the current browsing context to the current top-level browsing context.

   id is a Number object

   1. If id is less than 0 or greater than 2¹⁶ – 1, return error with error code invalid argument.

   2. Let window be the associated window of the current browsing context’s active document.

   3. If id is not a supported property index of window, return error with error code no such frame.

   4. Let child window be the WindowProxy object obtained by calling window.[[\GetOwnProperty]] (id).

   5. Set the current browsing context to child window’s browsing context.

   id represents a web element

   1. Let element be the result of trying to get a known element by web element reference id.

   2. If element is stale, return error with error code stale element reference.

   3. If element is not a frame or iframe element, return error with error code no such frame.

   4. Set the current browsing context to element’s nested browsing context.

6. Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.

7. Return success with data null.

WebDriver is not bound by the same origin policy, so it is always possible to switch into child browsing contexts, even if they are different origin to the current browsing context.

Switch To Parent Frame

The Switch to Parent Frame command sets the current browsing context for future commands to the parent of the current browsing context.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. If the current browsing context is not equal to the current top-level browsing context, set the current browsing context to the parent browsing context of the current browsing context.

4. Update any implementation-specific state that would result from the user selecting the current browsing context for interaction, without altering OS-level focus.

5. Return success with data null.

Resizing and positioning windows

WebDriver provides commands for interacting with the operating system window containing the current top-level browsing context. Because different operating systems’ window managers provide different abilities, not all of the commands in this section can be supported by all remote ends. Support for these commands is determined by the window dimensioning/positioning capability. Where a command is not supported, an unsupported operation error is returned.

The top-level browsing context has an associated window state which describes what visibility state its OS widget window is in. It can be in one of the following states:

If for whatever reason the top-level browsing context’s OS window cannot enter either of the window states, or if this concept is not applicable on the current system, the default state must be normal.

A top-level browsing context’s window rect is defined as a dictionary of the screenX, screenY, outerWidth and outerHeight attributes of the WindowProxy. Its JSON representation is the following:

"x"

WindowProxy’s screenX attribute.

"y"

WindowProxy’s screenY attribute.

"width"

WindowProxy’s outerWidth attribute.

"height"

WindowProxy’s outerHeight attribute.

To maximize the window, given an operating system level window with an associated top-level browsing context, run the implementation-specific steps to transition the operating system level window into the maximized window state. If the window manager supports window resizing but does not have a concept of window maximization, the window dimensions must be increased to the maximum available size permitted by the window manager for the current screen. Return when the window has completed the transition, or within an implementation-defined timeout.

To iconify the window, given an operating system level window with an associated top-level browsing context, run implementation-specific steps to iconify, minimize, or hide the window from the visible screen. Do not return from this operation until the visibility state of the top-level browsing context’s active document has reached the hidden state, or until the operation times out.

To restore the window, given an operating system level window with an associated top-level browsing context, run implementation-specific steps to restore or unhide the window to the visible screen. Do not return from this operation until the visibility state of the top-level browsing context’s active document has reached the visible state, or until the operation times out.

Interactability

In order to determine if an element can be interacted with using pointer actions, WebDriver performs hit-testing to find if the interaction will be able to reach the requested element.

An interactable element is an element which is either pointer-interactable or keyboard-interactable.

A pointer-interactable element is defined to be the first element, defined by the paint order found at the center point of its rectangle that is inside the viewport, excluding the size of any rendered scrollbars.

A keyboard-interactable element is any element that has a focusable area, is a body element, or is the document element.

An element’s in-view center point is the origin position of the rectangle that is the intersection between the element’s first DOM client rectangle and the initial viewport. Given an element that is known to be in view, it can be calculated this way:

1. Let rectangle be the first element of the DOMRect sequence returned by calling getClientRects on element.

2. Let left be max(0, min(x coordinate, x coordinate + width dimension)).

3. Let right be min(innerWidth, max(x coordinate, x coordinate + width dimension)).

4. Let top be max(0, min(y coordinate, y coordinate + height dimension)).

5. Let bottom be min(innerHeight, max(y coordinate, y coordinate + height dimension)).

6. Let x be floor((left + right) ÷ 2.0).

7. Let y be floor((top + bottom) ÷ 2.0).

8. Return the pair of (x, y).

An element is in view if it is a member of its own pointer-interactable paint tree, given the pretense that its pointer events are not disabled.

An element is obscured if the pointer-interactable paint tree at its center point is empty, or the first element in this tree is not an inclusive descendant of itself.

An element’s pointer-interactable paint tree is produced this way:

1. If element is not in the same tree as the current browsing context’s active document, return an empty sequence.

2. Let rectangles be the DOMRect sequence returned by calling getClientRects.

3. If rectangles has the length of 0, return an empty sequence.

4. Let center point be the in-view center point of the first indexed element in rectangles.

5. Return the elements from point given the coordinates center point.

Retrieval

The Find Element, Find Elements, Find Element From Element, and Find Elements From Element commands allow lookup of individual elements and collections of elements. Element retrieval searches are performed using pre-order traversal of the document’s nodes that match the provided selector’s expression. Elements are serialized and returned as web elements.

When required to find with arguments start node, using and value, a remote end must run the following steps:

1. Let end time be the current time plus the session implicit wait timeout.

2. Let location strategy be equal to using.

3. Let selector be equal to value.

4. Let elements returned be the result of trying to call the relevant element location strategy with arguments start node, and selector.

5. If a DOMException, SyntaxError, XPathException, or other error occurs during the execution of the element location strategy, return error invalid selector.

6. If elements returned is empty and the current time is less than end time return to step 4. Otherwise, continue to the next step.

7. Let result be an empty JSON List.

8. For each element in elements returned, append the serialization of element to result.

9. Return success with data result.

State

To calculate the absolute position of element:

1. Let rect be the value returned by calling getBoundingClientRect.

2. Let window be the associated window of current top-level browsing context.

3. Let x be (scrollX of window + rect’s x coordinate).

4. Let y be (scrollY of window + rect’s y coordinate).

5. Return a pair of (x, y).

To determine if node is not in the same tree as another node, other, run the following substeps:

1. If the node’s node document is not other’s node document, return true.

2. Return true if the result of calling the node’s compareDocumentPosition with other as argument is DOCUMENT_POSITION_DISCONNECTED (1), otherwise return false.

An element’s container is:

option element in a valid element context

optgroup element in a valid element context

The element’s element context, which is determined by:

1. Let datalist parent be the first datalist element reached by traversing the tree in reverse order from element, or undefined if the root of the tree is reached.

2. Let select parent be the first select element reached by traversing the tree in reverse order from element, or undefined if the root of the tree is reached.

3. If datalist parent is undefined, the element context is select parent. Otherwise, the element context is datalist parent.

option element in an invalid element context

The element does not have a container.

Otherwise

The container is the element itself.

Interaction

The element interaction commands provide a high-level instruction set for manipulating form controls. Unlike Actions, they will implicitly scroll elements into view and check that it is an interactable element.

Some resettable elements define their own clear algorithm. Unlike their associated reset algorithms, changes made to form controls as part of these algorithms do count as changes caused by the user (and thus, e.g. do cause input events to fire). When the clear algorithm is invoked for an element that does not define its own clear algorithm, its reset algorithm must be invoked instead.

The clear algorithm for input elements is to set the dirty value flag and dirty checkedness flag back to false, set the value of the element to an empty string, set the checkedness of the element to true if the element has a checked content attribute and false if it does not, empty the list of selected files, and then invoke the value sanitization algorithm iff the type attribute’s current state defines one.

The clear algorithm for textarea elements is to set the dirty value flag back to false, and set the raw value of element to an empty string.

The clear algorithm for output elements is set the element’s value mode flag to default and then to set the element’s textContent IDL attribute to an empty string (thus clearing the element’s child nodes).

Get Page Source

The Get Page Source command returns a string serialization of the DOM of the current browsing context active document.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts and return its value if it is an error.

3. Let source be the result of invoking the fragment serializing algorithm on a fictional node whose only child is the document element providing true for the require well-formed flag. If this causes an exception to be thrown, let source be null.

4. Let source be the result of serializing to string the current browsing context active document, if source is null.

5. Return success with data source.

Executing Script

A collection is an Object that implements the Iterable interface, and whose:

• initial value of the toString own property is "Arguments"
• instance of Array
• instance of FileList
• instance of HTMLAllCollection
• instance of HTMLCollection
• instance of HTMLFormControlsCollection
• instance of HTMLOptionsCollection
• instance of NodeList

When required to JSON deserialize with argument value and optional argument seen, a remote end must run the following steps:

1. If seen is not provided, let seen be an empty List.

2. Jump to the first appropriate step below:

3. Matching on value:

   undefined

   null

   type Boolean

   type Number

   type String

   Return success with data value.

   Object that represents a web element

   Return the deserialized web element of value.

   instance of Array

   instance of Object

   Return the result of running the clone an object algorithm with arguments value and seen, and the JSON deserialize algorithm as the clone algorithm.

To perform a JSON clone return the result of calling the internal JSON clone algorithm with arguments value and an empty List.

When required to run the internal JSON clone algorithm with arguments value and seen, a remote end must return the value of the first matching statement, matching on value:

undefined

null

Success with data null.

type Boolean

type Number

type String

Success with data value.

Otherwise, return success with the serialization to JSON of the web element value.

a collection

1. Let result list be an empty list.

2. For each item of value, add the result of trying to clone an object with arguments item and seen and the internal JSON clone algorithm as the clone algorithm to result list.

3. Return success with result list.

instance of element

If the element is stale, return error with error code stale element reference.

Otherwise return success with the JSON serialization of value.

a WindowProxy object

If the associated browsing context of the WindowProxy object in value has been discarded, return error with error code stale element reference.

Otherwise return success with the JSON serialization of value.

has an own property named "toJSON" that is a Function

Return success with the value returned by Call(toJSON).

Otherwise

1. If value is in seen, return error with error code javascript error.

2. Append value to seen.

3. Let result be the value of running the clone an object algorithm with arguments value and seen, and the internal JSON clone algorithm as the clone algorithm.

4. Remove the last element of seen.

5. Return result.

To clone an object, taking the arguments value, seen, and clone algorithm:

1. Let result be the value of the first matching statement, matching on value:

   a collection

   A new Array which length property is equal to the result of getting the property length of value.

   Otherwise

   A new Object.

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

   1. Let name be the name of the property.

   2. Let source property value be the result of getting a property named name from value. If doing so causes script to be run and that script throws an error, return error with error code javascript error.

   3. Let cloned property result be the result of calling the clone algorithm with arguments source property value and seen.

   4. If cloned property result is a success, set a property of result with name name and value equal to cloned property result’s data.

   5. Otherwise, return cloned property result.

When required to extract the script arguments from a request with argument parameters the implementation must:

1. Let script be the result of getting a property named script from the parameters.

2. If script is not a String, return error with error code invalid argument.

3. Let args be the result of getting a property named args from the parameters.

4. If args is not an Array return error with error code invalid argument.

5. Let arguments be the result of calling the JSON deserialize algorithm with arguments args.

6. Return success with data script and arguments.

The rules to execute a function body are as follows. The algorithm returns an ECMASCript completion record.

If at any point during the algorithm a user prompt appears, abort all subsequent substeps of this algorithm, and return Completion { [[\Type]]: normal, [[\Value]]: null, [[\Target]]: empty }.

1. Let window be the associated window of the current browsing context’s active document.

2. Let environment settings be the environment settings object for window.

3. Let global scope be environment settings realm’s global environment.

4. If body is not parsable as a FunctionBody or if parsing detects an early error, return Completion { [[\Type]]: normal, [[\Value]]: null, [[\Target]]: empty }.

5. If body begins with a directive prologue that contains a use strict directive then let strict be true, otherwise let strict be false.

6. Prepare to run a script with environment settings.

7. Prepare to run a callback with environment settings.

8. Let function be the result of calling FunctionCreate, with arguments:

   kind

   Normal.

   list

   An empty List.

   body

   The result of parsing body above.

   global scope

   The result of parsing global scope above.

   strict

   The result of parsing strict above.

9. Let completion be Call(function, window, parameters).

10. Clean up after running a callback with environment settings.

11. Clean up after running a script with environment settings.

12. Return completion.

The above algorithm is not associated with any particular element, and is therefore not subject to the document CSP directives.

Get All Cookies

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts, and return its value if it is an error.

3. Let cookies be a new JSON List.

4. For each cookie in all associated cookies of the current browsing context’s active document:

   1. Let serialized cookie be the result of serializing cookie.

   2. Append serialized cookie to cookies

5. Return success with data cookies.

Get Named Cookie

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts, and return its value if it is an error.

3. If the url variable name matches a cookie’s cookie name amongst all associated cookies of the current browsing context’s active document, return success with the serialized cookie as data.

   Otherwise, return error with error code no such cookie.

Add Cookie

The remote end steps are:

1. Let data be the result of getting a property named cookie from the parameters argument.

2. If data is not a JSON Object with all the required (non-optional) JSON keys listed in the table for cookie conversion, return error with error code invalid argument.

3. If the current browsing context is no longer open, return error with error code no such window.

4. Handle any user prompts, and return its value if it is an error.

5. If the current browsing context’s document element is a cookie-averse Document object, return error with error code invalid cookie domain.

6. If cookie name or cookie value is null, cookie domain is not equal to the current browsing context’s active document’s domain, cookie secure only or cookie HTTP only are not boolean types, or cookie expiry time is not an integer type, or it less than 0 or greater than the maximum safe integer, return error with error code invalid argument.

7. Create a cookie in the cookie store associated with the active document’s address using cookie name name, cookie value value, and an attribute-value list of the following cookie concepts listed in the table for cookie conversion from data:

   Cookie path

   The value if the entry exists, otherwise "/".

   Cookie domain

   The value if the entry exists, otherwise the current browsing context’s active document’s URL domain.

   Cookie secure only

   The value if the entry exists, otherwise false.

   Cookie HTTP only

   The value if the entry exists, otherwise false.

   Cookie expiry time

   The value if the entry exists, otherwise leave unset to indicate that this is a session cookie.

   If there is an error during this step, return error with error code unable to set cookie.

8. Return success with data null.

Delete Cookie

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts, and return its value if it is an error.

3. Delete cookies using the url variable name parameter as the filter argument.

4. Return success with data null.

Delete All Cookies

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Handle any user prompts, and return its value if it is an error.

3. Delete cookies, giving no filtering argument.

4. Return success with data null.

Input sources

The objects and properties defined in this section are spec-internal constructs and do not correspond to ECMAScript objects. For convenience the same terminology is used for their manipulation.

An input source is a virtual device providing input events. Each input source has an associated input id, which is a string that identifies the particular device, and a source type which determines the kind of input the device can provide. As with real devices, virtual devices are stateful; this state is recorded in an input source state object associated with each input source.

Ticks

A tick is the basic unit of time over which actions can be performed. During a tick, each input source has an assigned action — possibly a noop pause action — which may result in changes to the user agent internal state and eventually cause DOM events to be fired at the page. The next tick begins after the user agent has had a chance to process all DOM events generated in the current tick.

Waiting asynchronously means waiting for something to occur whilst allowing the browser to continue processing the event loop.