WebDriver

6.1 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 named name from object is defined as being the same as the result of calling Object . object . [[GetOwnProperty]] ( name ).

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

Setting a property with arguments Setting a property with arguments name and and value is defined as being the same as calling is defined as being the same as calling Object . [[Put]] ( name , , value ). The result of JSON serialization with ).

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

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

6.2 6.2 Commands The WebDriver protocol is organised into

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 . Each HTTP request with a method and template defined in this specification represents a single command produces a single HTTP response . In response to a , 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 , 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 . .

6.3 Processing model 6.3 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

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 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 works and how it is established are out of scope.

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

1. While the connection is not closed:

   1. Read bytes from the Read bytes from the connection until a complete HTTP request can be constructed from the data. Let until a complete HTTP request can be constructed from the data. Let request be a be a request constructed from the received data, according to the requirements of [ 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 ]. 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 , 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 Let request match be the result of the algorithm to match a request with request ’s ’s method and and URL as arguments. as arguments.

   3. If request match is of type error , send an error with request match ’s If request match is of type error code and jump to step 1. Otherwise, let command and command parameters be request match ’s data. Let url variables , send an error with request match be a url variables dictionary mapping the ’s error code and continue.

      Otherwise, let command parameters and URL variables be request match to their corresponding values. ’s data.

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

   5. If URL variables has an item named session id:

      Note

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

      1. Let session id Let session id be URL variables be the corresponding variable from command parameters . 's session id.

      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 . For each active session in the list of active sessions :

         1. If the current session is null send an error with error code invalid If active session 's session ID is equal to session id , then let session id , then jump to step 1 in this overall algorithm. be active session , and break.

      3. If the current If the session is not is null : Enqueue request in the current session ’s request queue . send an error with error code invalid session id , then continue.

   6. Wait until the first element in the current session ’s request queue Enqueue a task on remote end is request : Dequeue request from the current 's request queue to run the following steps:

      1. If session ’s request queue . is no longer in the list of active sessions , then return.

      2. If the list of active sessions no longer contains the current session , set the current session to Let parameters be null . .

      3. If If request ’s ’s method is POST: is POST:

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

         2. If parse result is not an 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 , send an error with error code invalid argument and jump back to step 1 in this overall algorithm.

            Otherwise, let parameters be null . be parse result .

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

      5. Wait for navigation to complete . If this returns an

         If navigate result is an error return its value and jump to step 1 in this overall algorithm, otherwise continue. , 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 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 with session , URL variables , and parameters . .

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

      8. Otherwise, if response result is a Assert: response result is a success , let response data be response result .

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

      10. Send a response with status 200 and response data . 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: 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 Let status and and name be the error response data for error code . be the error response data for error code .

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

3. Let 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 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 be a new JSON Object initialized with the following properties: initialized with the following properties:

   " error " "

   name

   " message " "

   message

   " stacktrace " "

   stacktrace

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

5. Send a response with Send a response with status and and body as arguments. When required to send a response , with arguments as arguments.

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

1. Let Let response be a new be a new response . .

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

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

   Content-Type

   " application/json; charset=utf-8 application/json; charset=utf-8 " "

   Cache-Control

   " no-cache " "

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

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

6. Write response bytes to the 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. .

6.4 Routing requests 6.4 Routing requests

Request routing is the process of going from a HTTP request to the series of steps needed to implement the 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 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 . or a path-absolute URL .

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

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

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

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

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

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

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

7. Let parameters be the result of extracting the variables from URL using Let URI template be the concatenation of URL prefix with entry ’s URI template . 's URI template .

8. Let Let command be be entry ’s ’s command . .

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

10. Return success with data with data command and parameters . and URL variables .

6.5 6.5 Endpoints The following table of endpoints lists the

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

6.6 6.6 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 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 . The body is a JSON Object and has a field named " and has a field named " value " whose value is an object bearing three, and sometimes four, fields: " whose value is an object bearing three, and sometimes four, fields:

• " error ", containing a string indicating the error code . ", 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. ", 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 " ", 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 ", which is a JSON Object with additional error data helpful in diagnosing the error. with additional error data helpful in diagnosing the error.

The following table lists each error code , its associated HTTP status , JSON error code . Error Code HTTP Status JSON Error Code Description 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. objects.

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

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 ; 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 [ .

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 ], notably in section 4.1.2.2 on vendor keywords , as the name for this path element, and include a vendor-chosen UA identifier. , 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 " (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 which has a JSON type, returning either success wrapping the deserialized capability value or 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 .

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 , 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 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 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 representing the WebDriver session that will be established, and capabilities object with a name that's an additional WebDriver capability defined by the same specification. , 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 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 " 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 [ " (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 " ] and precedes the first " : " character in the string. " character in the string.

7.1 7.1 Proxy The proxy configuration capability is a JSON

The proxy configuration capability is a JSON Object nested within the primary nested within the primary capabilities . Implementations may define additional proxy configuration options, but they must not alter the semantics of those listed below. Key Value Type Description Valid values . 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 is defined as being a valid host , optionally followed by a colon and a valid , optionally followed by a colon and a valid port . The . The host may include credentials . If the port is omitted and 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 has a default port , this is the implied port. Otherwise, the port is left undefined.

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

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

A proxyType of " 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 " 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: are:

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

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

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

   1. Let Let key be the name of the property. be the name of the property.

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

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

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

   5. Set a property Set a property key to to value on on proxy . .

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

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

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

7. Return Return success with data proxy . A with data proxy configuration object is a JSON .

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. where each of its own properties matching keys in the proxy configuration meets the validity criteria for that key.

7.2 Processing capabilities 7.2 Processing capabilities To process capabilities with argument

To process capabilities with argument parameters , the endpoint node must take the following steps: , and flags , the endpoint node must take the following steps:

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

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

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

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

   2. Let required capabilities be the result of Let required capabilities be the result of trying to validate capabilities with argument required capabilities . to validate capabilities with argument required capabilities .

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

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

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

4. Let validated first match capabilities be an empty JSON 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 : For each first match capabilities corresponding to an indexed property in all first match capabilities :

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

   2. Append validated capabilities to validated first match capabilities . Append validated capabilities to validated first match capabilities .

6. Let merged capabilities be an empty Let merged capabilities be an empty List . .

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

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

   2. Append merged to Append merged capabilities . to merged capabilities .

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

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

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

9. Return Return success with data with data null . When required to validate capabilities with argument .

When required to validate capabilities with argument capability : :

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

2. Let Let result be an empty JSON be an empty JSON Object . .

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

   1. Let name be the Let name of the property. be the name of the property.

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

   3. Run the substeps of the first matching condition: Run the substeps of the first matching condition:

      value is is null

      Let Let deserialized be set to be set to null . .

      name equals " equals " acceptInsecureCerts " "

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

      name equals " equals " browserName " "

      name equals " equals " browserVersion " "

      name equals " equals " platformName " "

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

      name equals " equals " pageLoadStrategy " "

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

      name equals " equals " proxy " "

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

      name equals " equals " strictFileInteractability " "

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

      name equals " equals " timeouts " "

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

      name equals " equals " unhandledPromptBehavior " "

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

      name is the name of an additional WebDriver capability is the name of an additional WebDriver capability

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

      name is the key of an extension capability is the key of an extension capability

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

      The remote end is an endpoint node

      Return an error with Return an error code invalid argument . with error code invalid argument .

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

4. Return success with data with data result . When merging capabilities with JSON .

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

1. Let Let result be a new JSON be a new JSON Object . .

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

   1. Let name be the Let name of the property. be the name of the property.

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

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

3. If If secondary is is undefined , return , return result . .

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

   1. Let name be the Let name of the property. be the name of the property.

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

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

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

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

5. Return Return result . .

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

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

   " browserName " "

   ASCII Lowercase name of the user agent as a ASCII Lowercase name of the user agent as a string . .

   " browserVersion " The user agent version, as a "

   The user agent version, as a string . .

   " platformName " "

   ASCII Lowercase name of the current platform as a 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 initially set to false, indicating the session will not implicitly trust untrusted or self-signed TLS certificates on navigation . .

   " strictFileInteractability setWindowRect " "

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

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

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

   " strictFileInteractability "

   Boolean indicating whether the remote end supports all of the resizing and positioning commands . 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. 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

   This allows a remote end to add information that might be useful to a local end without unnecessarily bloating the response sent back to the user with (e.g.) an entire browser profile. For example, an implementation could choose to indicate that a screenshot will be taken when returning an error by setting the capability

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

   1. Let match value equal Let match value equal value . .

   2. Run the substeps of the first matching Run the substeps of the first matching name : :

      " browserName " "

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

      Note

      There is a chance the remote end will need to start a browser process to correctly determine the 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. . Lightweight checks are preferred before this is done.

      " browserVersion " "

      Compare Compare value to the " to the " browserVersion " entry in matched capabilities using an implementation-defined comparison algorithm. The comparison is to accept a " 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 " that places constraints on the version using the " < ", " ", " <= ", " ", " > ", and " ", and " >= " operators. If the two values do not match, return " operators.

      If the two values do not match, return success with data 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. 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 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. . Lightweight checks are preferred before this is done.

      " platformName " "

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

      Note

      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

      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.	Any server or desktop system based upon the Linux kernel.
      " mac " Any version of Apple’s macOS.	Any version of Apple’s macOS.
      " windows " Any version of Microsoft Windows, including desktop and mobile versions. This list is not exhaustive. When returning	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 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. , allowing users to correctly identify the Operating System the WebDriver implementation is running on.

      " acceptInsecureCerts " "

      If If accept insecure TLS flag is set and not equal to value is true and the endpoint node does not support insecure TLS certificates , return , return success with data 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 . 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 If the has proxy configuration flag is set, or if the proxy configuration defined in value is not one that passes the endpoint node is not one that passes the endpoint node ’s implementation-specific validity checks, return ’s implementation-specific validity checks, return success with data 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. 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

      • If 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 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 argument with arguments value , and flags . Otherwise, if

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

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

5. Return Return success with data matched capabilities . with data matched capabilities .

9.1 9.1 Get Timeouts Get Timeouts HTTP Method URI Template

The remote end steps , given session , URL variables and parameters are:

1. Let timeouts be the Let timeouts object for be the timeouts object for session ’s timeouts configuration ’s timeouts configuration

2. Return Return success with data with data timeouts . .

9.2 9.2 Set Timeouts Set Timeouts HTTP Method URI Template

The remote end steps , given session , URL variables and parameters are:

1. Let

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

2. Make the session timeouts the new

   Make the session timeouts the new timeouts . .

3. Return

   Return success with data with data null . .

10.1 10.1 Navigate To Navigate To HTTP Method URI Template

If the session is not in a secure TLS If the remote end 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. 's accept insecure TLS flag is true, 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 , given session , URL variables and parameters are:

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

2. Let url be the result of getting the property Let URL be the result of getting a property named " url from the " from parameters argument. .

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

4. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

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

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

7. Navigate the current top-level browsing context to url . session's current top-level browsing context to URL .

8. If url is special except for file and current URL and If URL do not have the same absolute 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 . to wait for navigation to complete .

   2. Try to run the post-navigation checks . to run the post-navigation checks .

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

10. If the current top-level browsing context contains a refresh state pragma directive of If session's 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 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. has begun, and return to the first step of this algorithm.

11. Return Return success with data with data null . .

10.2 10.2 Get Current URL Get Current URL HTTP Method URI Template

The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

4. Return Return success with data url . with data URL .

10.3 10.3 Back HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

4. If the previous step completed results in a If the previous step completed results in a pageHide event firing , wait until event firing , wait until pageShow event fires or for the session page load timeout milliseconds to pass, whichever occurs sooner. 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 If the previous step completed by the session page load timeout being reached, and user prompts have been handled , return error code with error code timeout . .

6. Return Return success with data with data null . .

10.4 10.4 Forward HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

4. If the previous step completed results in a If the previous step completed results in a pageHide event firing, wait until firing, wait until pageShow event fires or for the session page load timeout milliseconds to pass, whichever occurs sooner. 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 If the previous step completed by the session page load timeout being reached, and user prompts have been handled , return error code with error code timeout . .

6. Return Return success with data with data null . .

10.5 10.5 Refresh HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

4. If url is special except for If URL is special except for file : :

   1. Try to wait for navigation to complete . to wait for navigation to complete .

   2. Try to run the post-navigation checks . to run the post-navigation checks .

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

6. Return Return success with data with data null . .

10.6 10.6 Get Title Get Title HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

4. Return Return success with data with data title . .

11.1 11.1 Get Window Handle Get Window Handle HTTP Method URI Template

The remote end steps , given session , URL variables and parameters are:

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

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

11.2 11.2 Close Window Close Window HTTP Method URI Template

The remote end steps , given session , URL variables and parameters are:

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

2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

3. Close the current top-level browsing context . session's current top-level browsing context .

4. If there are no more open top-level browsing contexts , then If there are no more open top-level browsing contexts , then try to close the session . Return the result of running the remote end steps for the Get Window Handles to close the session .

5. Return the result of running the remote end steps for the Get Window Handles command . , with session , URL variables and parameters .

11.3 11.3 Switch To Window Switch To Window HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

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

2. If If handle is is undefined , return error with , return error code invalid argument . 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 If there is an active user prompt , that prevents the focussing of another top-level browsing context , return error code unexpected alert open . with error code unexpected alert open .

4. If handle is equal to the associated window If handle for some top-level browsing is equal to the associated window handle for some top-level browsing context , let context in the current be the that browsing context, and set the current top-level browsing context with session , let context be the that browsing context, and set the current top-level browsing context with and context . Otherwise, return error with .

   Otherwise, return error code no such window . 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. Update any implementation-specific state that would result from the user selecting session 's current browsing context for interaction, without altering OS-level focus.

6. Return Return success with data with data null . .

11.4 11.4 Get Window Handles Get Window Handles HTTP Method URI Template

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

The remote end steps , given session , URL variables and parameters are:

1. Let Let handles be a JSON be a JSON List . .

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

3. Return success with data with data handles . .

11.5 11.5 New Window New Window HTTP Method URI Template

Create a new top-level browsing context .

The remote end steps , given session , URL variables and parameters are:

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

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

3. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

5. Create a new top-level browsing context by running the window open steps with url set to " 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 set to the empty string, and features set to " set to " noopener " and the user agent configured to create a new browsing context. This must be done without invoking the focusing steps for the created browsing context. If type hint has the value " " and the user agent configured to create a new browsing 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 ", and the implementation supports multiple browsing context in the same OS window, the new browsing context should share an OS window with session is " 's current browsing context . If type hint is " window ", and the implementation supports multiple browsing contexts in separate 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. ", and the implementation supports multiple browsing contexts in separate 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 Let handle of the newly created window. be the associated window handle of the newly created window.

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

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

   " handle " The value of "

   The value of handle . .

   " type " The value of "

   The value of type . .

9. Return Return success with data with data result . .

11.6 11.6 Switch To Frame Switch To Frame HTTP Method URI Template

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

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

3. Run the substeps of the first matching condition: Run the substeps of the first matching condition:

   id is is null

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

   2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

   3. Set the current browsing context with the current top-level browsing context . Set the current browsing context with session and the current top-level browsing context .

   id is a is a Number object object

   1. If If id is less than 0 or greater than 2 is less than 0 or greater than 2 ^{16 – 1, return error with} – 1, return error code invalid argument . with error code invalid argument .

   2. If the current browsing context is no longer open , return error with If session 's current browsing context is no longer open , return error code no such window . with error code no such window .

   3. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

   4. Let Let window be the associated window of session be the associated window of the current browsing context 's current browsing context ’s active document . ’s active document .

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

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

   7. Set the current browsing context with child window Set the current browsing context with session and child window ’s browsing context . ’s browsing context .

   id represents a web element represents a web element

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

   2. Handle any user prompts and return its value if it is an error . Try to handle any user prompts with session .

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

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

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

   6. Set the current browsing context with Set the current browsing context with element ’s nested browsing context . ’s nested 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. Update any implementation-specific state that would result from the user selecting session 's current browsing context for interaction, without altering OS-level focus.

5. Return Return success with data with data null . .

11.7 11.7 Switch To Parent Frame Switch To Parent Frame HTTP Method URI Template

The remote end steps are: The remote end steps , given session , URL variables and parameters are:

1. Run the substeps if the current browsing context is already the top-level browsing context : Run the substeps if the current browsing context is already the top-level browsing context :

2. If the current browsing context is no longer open , return error with If session's current parent browsing context is no longer open , return error code no such window . Return success with data null . with error code no such window . If the current parent 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 . Try to handle any user prompts with session .

4. If the current If session 's current parent browsing context is not 's current parent browsing context is not null , set the current browsing context with the current parent browsing context . , set the current browsing context with session and current parent browsing context .

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

6. Return Return success with data with data null . .

11.8 Resizing and positioning windows 11.8 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

WebDriver provides commands in this section can be supported by all remote ends . Support for these for interacting with the operating system window containing session's 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 is determined by the window dimensioning/positioning capability . Where a . Where a command is not supported, an unsupported operation is not supported, an unsupported operation error is returned. 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: State Keyword Default Description 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 ’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 .

A top-level browsing context ’s window rect is defined as a dictionary of the ’s window rect is defined as a dictionary of the screenX , , screenY , , outerWidth and and outerHeight attributes of the attributes of the WindowProxy . The WindowRect object for a .

The WindowRect object for a WindowProxy , , window is a is a object initalised with the following properties: initalised with the following properties:

" x " "

window ’s ’s screenX attribute. attribute.

" y " "

window ’s ’s screenY attribute. attribute.

" width " "

windows ’s ’s outerWidth attribute. attribute.

" height " "

window ’s ’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 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 ’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 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 ’s active document has reached the visible state, or until the operation times out. state, or until the operation times out.