This specification is derived from the popularSelenium WebDriver browser automation framework.Selenium is a long-lived project,and due to its age and breadth of useit has a wide range of expected functionality.This specification uses these expectations to inform its design.Where improvements or clarifications have been made,they have been made with care to allow existing users of Selenium WebDriverto avoid unexpected breakages.

The largest intended group of users of this specificationare software developers and testerswriting automated tests and other tooling,such as monitoring or load testing, that relies on automating a browser.As such, care has been taken to provide commandsthat simplify common tasks such astyping intoandclicking elements.

WebDriver provides a mechanism for others to define extensions to the protocolfor the purposes of automating functionality that cannot be implemented entirelyinECMAScript. This allows otherweb standards to support the automation of new platform features. It alsoallows vendors to expose functionality that is specific to their browser.

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

Where algorithms that return values are fallible, they are written in terms of returning eithersuccess orerror. Asuccess value has an associateddata field which encapsulates the value returned, whereas anerror value has an associatederror code.

When calling a fallible algorithm, the construct “Letresult be the result oftrying to callalgorithm” is equivalent to

1. Lettemp be the result of callingalgorithm.

2. Iftemp is anerror returntemp, otherwise letresult betemp'sdata field.

The result ofgetting a property withname fromobject is defined as being the same as the result of callingObject.[[GetOwnProperty]](name) onobject.

The result ofgetting a property with default with argumentsname anddefault fromobject is defined as being the same as the result of callingObject.[[GetOwnProperty]](name) onobject if that results in a value other thanundefined anddefault otherwise.

Setting a property with argumentsname andvalue onobject is defined as being the same as callingObject.[[Put]](name,value) onobject.

The result ofJSON serialization withobject of type JSONObject is defined as the result of callingstringify(object).

The result ofJSON deserialization withtext is defined as the result of callingparse(text).

The WebDriver protocol is organized intocommands.EachHTTP request with a method and template defined in this specificationrepresents a singlecommand,and therefore each command produces a singleHTTP response.

In response to acommand,aremote end will run a series of actionsknown asremote end steps.These provide the sequences of actions that aremote end takeswhen it receives a particularcommand.

Theremote 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 particularlocal end andremote end with aconnection to which theremote end maywrite bytes andread bytes. However the exact details of how thisconnection works and how it is established are out of scope.

After aconnection is established, theremote end must runthe following steps:

1. While theconnection is not closed:

   1. Read bytes from theconnection until a completeHTTP request can be constructed from the data. Letrequest be arequest constructed from the received data, according to the requirements of [RFC7230]. If it is not possible to construct a completeHTTP request, theremote end must either close theconnection, return an HTTP response with status code 500, or return anerror witherror codeunknown error.

   2. Letrequest match be the result of the algorithm tomatch a request withrequest'smethod andURL as arguments.

   3. Ifrequest match is of typeerror,send an error withrequest match'serror code andcontinue.

      Otherwise, letcommand andURL variables berequest match's data.

   4. Letsession be null.

   5. IfURL variablescontains "session id":

      Note

      This condition is intended to exclude theNew Session andStatuscommands and anyextension commands which do not operate on a particularsession.

      1. Letsession id beURL variables["session id"].

      2. For eachactive session in the list ofactive sessions:

         1. Ifactive session'ssession ID is equal tosession id, then letsession beactive session, and break.

      3. If thesession isnullsend an error witherror codeinvalid session id, thencontinue.

   6. Enqueue a task onremote end'srequest queue to run the following steps:

      1. Ifsession is no longer in the list ofactive sessions, thensend an error witherror codeinvalid session id and return.

      2. Letparameters benull.

      3. Ifrequest'smethod is POST:

         1. Letparse result be the result ofparsing as JSON withrequest'sbody as the argument. If this process throws an exception, return anerror witherror codeinvalid argument and jump back to step 1 in this overall algorithm.

         2. Ifparse result is not anObject,send an error witherror codeinvalid argument and jump back to step 1 in this overall algorithm.

            Otherwise, letparameters beparse result.

      4. Letnavigate result be the result ofwait for navigation to complete withsession.

      5. Ifnavigate result is anerror,send an error witherror code equal tonavigate result'serror code and return.

      6. Letresponse result be the return value obtained by running theremote end steps forcommand withsession,URL variables, andparameters.

      7. Ifresponse result is anerror,send an error witherror code equal toresponse result'serror code and return.

      8. Assert:response result is asuccess.

      9. Letresponse data beresponse result's data.

      10. Send a response with status 200 andresponse data.

When required tosend an error, witherror code and an optionalerror data dictionary, aremote end must run the following steps:

1. Letstatus andname be theerror response data forerror code.

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

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

   Letbody be a new JSONObject initialized with the following properties:

   "error"

   name

   "message"

   message

   "stacktrace"

   stacktrace

4. If theerror data dictionary contains any entries, set the "data" field onbody to a new JSONObject populated with the dictionary.

5. Send a response withstatus andbody as arguments.

When required tosend a response, with argumentsstatus anddata, aremote end must run the following steps:

1. Letresponse be a newresponse.

2. Setresponse'sHTTP status tostatus, andstatus message to the string corresponding to the description ofstatus in thestatus code registry.

3. Set theresponse'sheader withname andvalue with the following values:

   Content-Type

   "application/json; charset=utf-8"

   Cache-Control

   "no-cache"

4. Letresponse'sbody be theUTF-8 encodedJSON serialization of a JSONObject with a key "value" set todata.

5. Letresponse bytes be the byte sequence resulting from serializingresponse according to the rules in [RFC7230].

6. Writeresponse bytes to theconnection.

Request routing is the process of going from anHTTP request to theseries of steps needed to implement thecommand represented by that request.

Aremote end has an associatedURL prefix, which is used as a prefix on all WebDriver-defined URLs on thatremote end. This must either beundefined or apath-absolute URL.

For example aremote end wishing to run alongside other services onexample.com might set itsURL prefix to/wd so that anew sessioncommand would be invoked by sending a POST request to/wd/session, rather than/session.

In order tomatch a request given amethod andURL, the following steps must be taken:

1. Letendpoints be a list containing each row in thetable of endpoints.

2. Remove each entry fromendpoints for which the concatenation of theURL prefix and the entry'sURI template does not have a valid expansion equal toURL'spath.

3. If there are no entries inendpoints, returnerror witherror codeunknown command.

4. Remove each entry inendpoints for which themethod column is not equal tomethod.

5. If there are no entries inendpoints, returnerror witherror codeunknown method.

6. There is now exactly one entry inendpoints; letentry be this entry.

7. LetURI template be the concatenation ofURL prefix withentry'sURI template.

8. Letcommand beentry'scommand.

9. LetURL variables be amap with oneentry for each variable defined inURI template, with the entry name equal to the template variable name, and the entry value being the variable value required to expand theURI template to matchURL'spath.

10. Returnsuccess with datacommand andURL variables.

The followingtable of endpoints lists themethod andURI template for eachendpoint nodecommand.Extension commands are implicitly appended to this table.

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

• "error", containing a string indicating theerror 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 JSONObject with additionalerror data helpful in diagnosing the error.

AGET request to/session/1234/url, where1234 is not thesession id of asession would return anHTTP response with the status 404 and a body of the form:

{"value":{"error":"invalid session id","message":"No active session with ID 1234","stacktrace":""}}

Certain commands may also annotateerrors with additionalerror data. Notably, this is the case for commands which invoke theuser prompt handler, where theuser prompt message may be included in a "text" field:

{"value": {"error":"unexpected alert open","message":"","stacktrace":"","data": {"text":"Message from window.alert"}}}

The following table lists eacherror code, its associatedHTTP status, JSONerror code, and a non-normative description of the error. Theerror response data for a particularerror code is the values of theHTTP Status andJSON Error Code columns for the row corresponding to thaterror code.

Anerror data dictionary is a mapping of string keys to JSON serializable values that can optionally be included witherror objects.

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

Commands defined in this way are calledextension commands and behave no differently than othercommands; each has a dedicated HTTP endpoint and a set ofremote end steps.

Eachextension command has an associatedextension command URI Template that is aURI Template string, and which should bear some resemblance to what the command performs. This value, along with the HTTP method andextension command, is added to thetable of endpoints and thus follows the same rules forrequest routing as that of other built-incommands.

In order to avoid potential resource conflicts with other implementations, vendor-specificextension 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 insection 4.1.2.2 onvendor keywords, as the name for this path element, and include a vendor-chosen UA identifier.

This might lead to a URL of the form/session/5d376174-36f0-11e5-9b9a-6bdf200a3f7f/ms/edge/context, wheresession/{session id} associates the request with the specified session,ms/edge identifies the command as specific to the Edge browser distributed by Microsoft, andcontext describes the functionality that, in the context of Edge, allows alocal end to switch between browser-specific contexts. Requesting this URL will call theextension command'sremote end steps.

Other specifications may defineadditional WebDriver capabilities. Each definedcapability must have acapability name whichis a string not containing a ":" (colon) character,anadditional capability deserializationalgorithm which is a set of steps taking a singleargumentvalue which has a JSON type, returningeithersuccess wrapping the deserialized capability valueorerror.

Anadditional WebDriver capability may also defineamatched capability serialization algorithm,which is a set of steps used to determine if a capability is matchedby the current implementation and provide any computed value to returnto the user. This set of steps takes a singleargumentvalue, which is the output of thecorrespondingadditional capability deserialization algorithm,and returns eithernull to indicate the capabilityis not matched, or a non-null JSON-serializable value if thecapability is matched.

Other specifications may also defineWebDrivernew session algorithms, which are called just after a newsession is created, and before thenew session response is sentto theremote end. These algorithms are calledwithsession representing the WebDriver session that willbe established, andcapabilities, the capabilities object that will be returnedto theremote end. It is permitted for such an algorithm tomodify any entry in the capabilities object with a name that's anadditional WebDriver capability defined by the samespecification.

Remote ends may also introduceextension capabilities that are extracapabilities 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 withextension commands, it is suggested that the key used to denote theextension capability namespace is based on thevendor keywords listed in [CSS21] and precedes the first ":" character in the string.

Extension capabilities are typically used to provide UA orintermediary node specific configuration that is not handled by thetable of standard capabilities.

An examplenew session request body might look like this:

{"capabilities":{"alwaysMatch":{// browser specific configuration"<prefix>:browserOptions":{"binary":"/usr/bin/browser-binary","args":["--start-page=https://example.com"],}}}}

Theproxy configuration capability is a JSONObject nested within the primarycapabilities. Implementations may define additional proxy configuration options, but they must not alter the semantics of those listed below.

Ahost and optional port for ascheme is defined as being a validhost, optionally followed by a colon and a validport. Thehost mayinclude credentials. If the port is omitted andscheme has adefault port, this is the implied port. Otherwise, the port is left undefined.

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

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

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

Theremote end steps todeserialize as a proxy argumentparameter are:

1. Ifparameter is not a JSONObject return anerror witherror codeinvalid argument.

2. Letproxy be a new, emptyproxy configuration object.

3. For each enumerableown property inparameter run the following substeps:

   1. Letkey be the name of the property.

   2. Letvalue be the result ofgetting a property namedname fromparameter.

   3. If there is no matchingkey forkey in theproxy configuration table return anerror witherror codeinvalid argument.

   4. Ifvalue is not one of thevalid values for thatkey, return anerror witherror codeinvalid argument.

   5. Set a propertykey tovalue onproxy.

4. Ifproxy does not have anown property for "proxyType" return anerror witherror codeinvalid argument.

5. If the result ofgetting a property named "proxyType" fromproxy equals "pac", andproxy does not have anown property for "proxyAutoconfigUrl" return anerror witherror codeinvalid argument.

6. Ifproxy has anown property for "socksProxy" and does not have anown property for "socksVersion" return anerror witherror codeinvalid argument.

7. Returnsuccess with dataproxy.

Aproxy configuration object is a JSONObject where each of itsown properties matching keys in theproxy configuration meets the validity criteria for that key.

Toprocess capabilities givenparameters, andsession configuration flagsflags, theendpoint node must take the following steps:

1. Letcapabilities request be the result ofgetting the property "capabilities" fromparameters.

   1. Ifcapabilities request is not a JSONObject, returnerror witherror codeinvalid argument.

2. Letrequired capabilities be the result ofgetting the property "alwaysMatch" fromcapabilities request.

   1. Ifrequired capabilities isundefined, set the value to an empty JSONObject.

   2. Letrequired capabilities be the result oftrying tovalidate capabilities with argumentsrequired capabilities andflag.

3. Letall first match capabilities be the result ofgetting the property "firstMatch" fromcapabilities request.

   1. Ifall first match capabilities isundefined, set the value to aList with a single entry of an empty JSONObject.

   2. Ifall first match capabilities is not aList with one or more entries, returnerror witherror codeinvalid argument.

4. Letvalidated first match capabilities be an emptyList.

5. For eachfirst match capabilities corresponding to an indexed property inall first match capabilities:

   1. Letvalidated capabilities be the result oftrying tovalidate capabilities with argumentsfirst match capabilities andflags.

   2. Appendvalidated capabilities tovalidated first match capabilities.

6. Letmerged capabilities be an emptyList.

7. For eachfirst match capabilities corresponding to an indexed property invalidated first match capabilities:

   1. Letmerged be the result oftrying tomerge capabilities withrequired capabilities andfirst match capabilities as arguments.

   2. Appendmerged tomerged capabilities.

8. For eachcapabilities corresponding to an indexed property inmerged capabilities:

   1. Letmatched capabilities be the result oftrying tomatch capabilities withcapabilities as an argument.

   2. Ifmatched capabilities is notnull, returnsuccess with datamatched capabilities.

9. Returnsuccess with datanull.

When required tovalidate capabilities with argumentcapabilities:

1. Ifcapabilities is not a JSONObject return anerror witherror codeinvalid argument.

2. Letresult be an empty JSONObject.

3. For each enumerableown property incapabilities, run the following substeps:

   1. Letname be the name of the property.

   2. Letvalue be the result ofgetting a property namedname fromcapabilities.

   3. Run the substeps of the first matching condition:

      value isnull

      Letdeserialized be set tonull.

      name equals "acceptInsecureCerts"

      Ifvalue is not aboolean return anerror witherror codeinvalid argument. Otherwise, letdeserialized be set tovalue.

      name equals "browserName"

      name equals "browserVersion"

      name equals "platformName"

      Ifvalue is not astring return anerror witherror codeinvalid argument. Otherwise, letdeserialized be set tovalue.

      name equals "pageLoadStrategy"

      Letdeserialized be the result oftrying todeserialize as a page load strategy with argumentvalue.

      name equals "proxy"

      Letdeserialized be the result oftrying todeserialize as a proxy with argumentvalue.

      name equals "strictFileInteractability"

      Ifvalue is not aboolean return anerror witherror codeinvalid argument. Otherwise, letdeserialized be set tovalue

      name equals "timeouts"

      Letdeserialized be the result oftrying todeserialize as timeouts configuration withvalue.

      name equals "unhandledPromptBehavior"

      Letdeserialized be the result oftrying todeserialize as an unhandled prompt behavior with argumentvalue.

      name is the name of anadditional WebDriver capability

      Letdeserialized be the result oftrying to run theadditional capability deserialization algorithm for the extension capability corresponding toname, with argumentvalue.

      name is the key of anextension capability

      Ifname is known to the implementation, letdeserialized be the result oftrying to deserializevalue in an implementation-specific way. Otherwise, letdeserialized be set tovalue.

      Theremote end is anendpoint node

      Return anerror witherror codeinvalid argument.

   4. Ifdeserialized is notnull,set a property onresult with namename and valuedeserialized.

4. Returnsuccess with dataresult.

Whenmerging capabilities with JSONObject argumentsprimary andsecondary, anendpoint node must take the following steps:

1. Letresult be a new JSONObject.

2. For each enumerableown property inprimary, run the following substeps:

   1. Letname be the name of the property.

   2. Letvalue be the result ofgetting a property namedname fromprimary.

   3. Set a property onresult with namename and valuevalue.

3. Ifsecondary isundefined, returnresult.

4. For each enumerableown property insecondary, run the following substeps:

   1. Letname be the name of the property.

   2. Letvalue be the result ofgetting a property namedname fromsecondary.

   3. Letprimary value be the result ofgetting the propertyname fromprimary.

   4. Ifprimary value is notundefined, return anerror witherror codeinvalid argument.

   5. Set a property onresult with namename and valuevalue.

5. Returnresult.

Whenmatching capabilities given JSONObjectcapabilities, and asession configuration flagsflags, anendpoint node must take the following steps:

1. Letmatched capabilities be a JSONObject with the following entries:

   "browserName"

   ASCII Lowercase name of the user agent as astring.

   "browserVersion"

   The user agent version, as astring.

   "platformName"

   ASCII Lowercase name of the current platform as astring.

   "acceptInsecureCerts"

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

   "strictFileInteractability"

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

   "setWindowRect"

   Boolean indicating whether theremote end supports all of theresizing and positioningcommands.

   "userAgent"

   String containing thedefault User-Agent value.

2. Ifflags contains "http", add the following entries tomatched capabilities:

   "strictFileInteractability"

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

3. Optionally addextension capabilities as entries tomatched capabilities. The values of these may be elided, and there is no requirement that allextension capabilities be added.

   Note

   This allows aremote end to add information that might be useful to alocal 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 capabilityse:screenshot-on-error totrue.

4. For eachname andvalue corresponding tocapabilities'sown properties:

   1. Letmatch value equalvalue.

   2. Run the substeps of the first matchingname:

      "browserName"

      Ifvalue is not a string equal to the "browserName" entry inmatched capabilities, returnsuccess with datanull.

      Note

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

      "browserVersion"

      Comparevalue to the "browserVersion" entry inmatched capabilities using an implementation-defined comparison algorithm. The comparison is to accept avalue that places constraints on the version using the "<", "<=", ">", and ">=" operators.

      If the two values do not match, returnsuccess with datanull.

      Note

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

      Note

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

      "platformName"

      Ifvalue is not a string equal to the "platformName" entry inmatched capabilities, returnsuccess with datanull.

      Note

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

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

      This list is not exhaustive.

      When returningcapabilities fromNew Session, it is valid to return a more specificplatformName, allowing users to correctly identify the Operating System the WebDriver implementation is running on.

      "acceptInsecureCerts"

      Ifaccept insecure TLS flag is set and not equal tovalue, returnsuccess with datanull.

      Note

      If theendpoint node does not supportinsecure TLS certificates and this is the reason no match is ultimately made, it is useful to provide this information to thelocal end.

      "proxy"

      If thehas proxy configuration flag is set, or if the proxy configuration defined invalue is not one that passes theendpoint node's implementation-specific validity checks, returnsuccess with datanull.

      Note

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

      "unhandledPromptBehavior"

      Ifcheck user prompt handler matches withvalue is false, returnsuccess with datanull.

      Otherwise

      • Ifname is the name of anadditional WebDriver capability which defines amatched capability serialization algorithm, letmatch value be the result of running thematched capability serialization algorithm for capabilityname with argumentsvalue, andflags.

      • Otherwise, ifname is the key of anextension capability, letmatch value be the result oftrying implementation-specific steps to match onname withvalue. If the match is not successful, returnsuccess with datanull.

   3. Ifmatch value is not null,set a property onmatched capabilities with namename and valuematch value.

5. Returnsuccess with datamatched capabilities.

In addition to per-session state, aremote end that isanendpoint node also has additional state that is globalacross all sessions.

Anendpoint node has an associatedaccept insecure TLS flag that indicates whether untrusted or self-signed TLS certificates are treated as trusted. The default value of the flag is false if the endpoint doesn't support accepting insecure TLS connections, or unset otherwise.

Anendpoint node has an associatedhas proxy configuration flag that indicates whether the proxy is already configured. The default value of the flag is true if the endpoint doesn't support proxy configuration, or false otherwise.

Tocreate a session, given a JSONObjectcapabilites, andsession configurationflagsflags:

1. Letsession id be the result ofgenerating a UUID.

2. Letsession be a newsession withsession IDsession id, andHTTP flagflags contains "http".

3. Letproxy be the result of getting property "proxy" fromcapabilities and run the substeps of the first matching statement:

   proxy is aproxy configuration object

   Take implementation-defined steps to set the user agent proxy using the extractedproxy configuration. If the defined proxy cannot be configured returnerror witherror codesession not created. Otherwise set thehas proxy configuration flag to true.

   Otherwise

   Set a property ofcapabilities with name "proxy" and a value that is a new JSONObject.

4. Ifcapabilites has a property named "acceptInsecureCerts", set theendpoint node'saccept insecure TLS flag to the result ofgetting a property named "acceptInsecureCerts" fromcapabilities.

5. Letuser prompt handler capability be the result of getting property "unhandledPromptBehavior" fromcapabilities.

6. Ifuser prompt handler capability is not undefined,update the user prompt handler withuser prompt handler capability.

7. Letserialized user prompt handler beserialize the user prompt handler.

8. Set a property oncapabilities with the name "unhandledPromptBehavior", and the valueserialized user prompt handler.

9. Ifflagscontains "http":

   1. Letstrategy be the result of getting property "pageLoadStrategy" fromcapabilities.

      Ifstrategy is a string, set thesession'spage loading strategy tostrategy. Otherwise, set thepage loading strategy tonormal andset a property ofcapabilities with name "pageLoadStrategy" and value "normal".

   2. LetstrictFileInteractability be the result of getting property "strictFileInteractability" fromcapabilities. IfstrictFileInteractability is a boolean, setsession'sstrict file interactability tostrictFileInteractability.

   3. Lettimeouts be the result of getting a property "timeouts" fromcapabilities. Iftimeouts is not undefined, setsession'ssession timeouts totimeouts.

   4. Set a property oncapabilities with name "timeouts" and valueserialize the timeouts configuration withsession'ssession timeouts.

10. Process anyextension capabilities incapabilities in an implementation-defined manner.

11. Run anyWebDriver new session algorithm defined in external specifications, with argumentssession,capabilities, andflags.

12. Appendsession toactive sessions.

13. Ifflags contains "http", appendsession toactive HTTP sessions.

14. Set thewebdriver-active flag to true.

Toclose the session, givensession aremote end must take the following steps:

1. Ifsession'sHTTP flag is set, removesession fromactive HTTP sessions.

2. Removesession fromactive sessions.

3. Perform the following substeps based on theremote end's type:

   Remote end is anendpoint node

   1. If the list ofactive sessions is empty:

      1. Set thewebdriver-active flag to false

      2. Set theuser prompt handler to null.

      3. Unset theaccept insecure TLS flag.

      4. Reset thehas proxy configuration flag to its default value.

      5. Optionally,close alltop-level browsing contexts, withoutprompting to unload.

   Remote end is anintermediary node

   1. Close theassociated session. If this causes anerror to occur, complete the remainder of this algorithm before returning theerror.

4. Perform any implementation-specific cleanup steps.

5. If anerror has occurred in any of the steps above, return theerror, otherwise returnsuccess with datanull.

Closing asession might cause the associated browser process to be killed. It is assumed that any implementation-specific cleanup steps are performedafter the response has been sent back to the client so that theconnection is not prematurely closed.

TheNew Sessioncommandcreates a new WebDriversession with theendpoint node.If the creation fails, asession not createderror is returned.

If theremote end is anintermediary node, it may use the result of thecapabilities processing algorithm to route thenew session request to the appropriateendpoint node. Anintermediary node is free to defineextension capabilities to assist in this process, however, these specific capabilities must not be forwarded to theendpoint node.

If theintermediary 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 requestedcapabilities. Anintermediary node must forward custom, top-level parameters (i.e. non-capabilities) to subsequentremote end nodes.

Anintermediary node might require authentication oncreating a new session. This authentication is an argument to theNew Session command itself and not the user agent'scapabilities. Therefore, the authentication should be passed as a top-level parameter and not embedded incapabilities:

{"user":"alice","password":"hunter2","capabilities": {…}}

However, because anintermediary node cannot forwardextension capabilities specific to that implementation to anendpoint node, the following is also permitted by this specification:

{"capabilities":{"alwaysMatch":{"cloud:user":"alice","cloud:password":"hunter2","platformName":"linux"},"firstMatch":[{"browserName":"chrome"},{"browserName":"edge"}]}}

Once allcapabilities are merged from this example, anendpoint node would receiveNew Session capabilities identical to:

[{"browserName":"chrome","platformName":"linux"},{"browserName":"edge","platformName":"linux"}]

Theremote end steps, givensession,URLvariables andparameters are:

1. If the implementation is anendpoint node, and the list ofactive HTTP sessions is not empty, or otherwise if the implementation is unable to start an additional session, returnerror witherror codesession not created.

2. If theremote end is anintermediary node, take implementation-defined steps that either result in returning anerror witherror codesession not created, or in returning asuccess with data that is isomorphic to that returned byremote ends according to the rest of this algorithm. If anerror is not returned, theintermediary node must retain a reference to thesession created on theupstream node as theassociated session such that commands may be forwarded to thisassociated session on subsequent commands.

   Note

   How this is done is entirely up to the implementation, but typically thesessionId, andURL andURL prefix of theupstreamremote end will need to be tracked.

3. Letflags be a set containing "http".

4. Letcapabilities be the result oftrying toprocess capabilities withparameters andflags.

5. Ifcapabilities's isnull, returnerror witherror codesession not created.

6. Letsession be the result ofcreate a session, withcapabilities, andflags.

7. Letbody be a JSONObject initialized with:

   "sessionId"

   session'ssession ID.

   "capabilities"

   capabilities

8. Setsession'current top-level browsing context to one of theendpoint node'stop-level browsing contexts, preferring thetop-level browsing context that hassystem focus, or otherwise preferring anytop-level browsing context whosevisibility state isvisible.

   Note

   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.

9. Set therequest queue to a newqueue.

10. Returnsuccess with databody.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession is anactive HTTP session,try toclose the session withsession.

2. Returnsuccess with datanull.

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

Theremote end steps, givensession,URLvariables andparameters are:

1. Letbody be a new JSONObject with the following properties:

   "ready"

   Theremote end'sreadiness state.

   "message"

   An implementation-defined string explaining theremote end'sreadiness state.

2. Returnsuccess with databody.

Theremote end steps, givensession,URLvariables andparameters are:

1. Lettimeouts beserialize the timeouts configuration withsession'stimeouts configuration

2. Returnsuccess with datatimeouts.

Theremote end steps, givensession,URLvariables andparameters are:

1. Lettimeouts be the result oftrying todeserialize as timeouts configuration withparameters.

2. Setsession'stimeouts configuration totimeouts.

3. Returnsuccess with datanull.

If theremote end'saccept 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.

To navigate thecurrent top-level browsing context of thesession with ID1 tohttps://example.com, thelocal end would POST to/session/1/url with the body:

{"url":"https://example.com"}

Theremote end steps, givensession,URLvariables andparameters are:

1. LetURL be the result ofgetting a property named "url" fromparameters.

2. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

3. IfURL is not anabsolute URL or is not anabsolute URL with fragment or not alocal scheme, returnerror witherror codeinvalid argument.

4. Try tohandle any user prompts withsession.

5. Lettimeout besession'ssession timeoutspage load timeout.

6. Letcurrent URL besession'scurrent top-level browsing context'sactive document'sURL.

7. Ifcurrent URL andURL do not have the sameabsolute URL andtimeout is not null:

   1. Settimer to a newtimer.

   2. Start the timer withtimer andtimeout.

8. Run these steps, butabort whentimer'stimeout fired flag is set:

   1. Navigatesession'scurrent top-level browsing context toURL.

   2. IfURLis special except forfile andcurrent URL andURL do not have the sameabsolute URL :

      1. Try towait for navigation to complete withsession andtimer.

      2. Try to run thepost-navigation checks.

   3. Set the current browsing context withsession andcurrent top-level browsing context.

   4. Whilesession'scurrent top-level browsing context contains arefresh state pragma directive oftime 1 second or less, run the following steps:

      1. Setcurrent URL tosession'scurrent top-level browsing context'sactive document'sURL.

      2. Wait until the refresh timeout has elapsed and newnavigate ofsession'scurrent top-level browsing context has begun.

      3. SetURL to the destination URL ofsession'scurrent top-level browsing context'sactive document's ongoing navigation.

      4. IfURLis special except forfile andcurrent URL andURL do not have the sameabsolute URL :

         1. Try towait for navigation to complete withsession andtimer.

         2. Try to run thepost-navigation checks.

9. If aborted return anerror witherror codetimeout.

10. Returnsuccess with datanull.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. LetURL be theserialization ofsession'scurrent top-level browsing context'sactive document'sURL.

4. Returnsuccess with dataURL.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. Lettimeout besession'session timeoutspage load timeout.

4. Lettimer be a newtimer.

5. Iftimeout is not null:

   1. Start the timer withtimer andtimeout.

6. Traverse the history by a delta –1 forsession'scurrent browsing context.

7. If the previous step completed results in apageHideevent firing, wait untilpageShowevent fires ortimer'timeout fired flag to be set, whichever occurs first.

8. Iftimer'timeout fired flag is set:

   1. Handle any user prompts.

   2. Returnerror witherror codetimeout.

9. Returnsuccess with datanull.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. Lettimeout besession'session timeoutspage load timeout.

4. Lettimer be a newtimer.

5. Iftimeout is not null:

   1. Start the timer withtimer andtimeout.

6. Traverse the history by a delta 1 forsession'scurrent browsing context.

7. If the previous step completed results in apageHideevent firing, wait untilpageShowevent fires ortimer'timeout fired flag to be set, whichever occurs first.

8. Iftimer'timeout fired flag is set:

   1. Handle any user prompts.

   2. Returnerror witherror codetimeout.

9. Returnsuccess with datanull.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. Initiatean overridden reload ofsession'scurrent top-level browsing context'sactive document.

4. IfURLis special except forfile:

   1. Try towait for navigation to complete withsession.

   2. Try to run thepost-navigation checks.

5. Set the current browsing context withsession andsession'scurrent top-level browsing context.

6. Returnsuccess with datanull.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. Lettitle be thesession'scurrent top-level browsing context'sactive document'stitle.

4. Returnsuccess with datatitle.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Returnsuccess with data being thewindow handle associated withsession'scurrent top-level browsing context.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

2. Try tohandle any user prompts withsession.

3. Closesession'scurrent top-level browsing context.

4. If there are no more opentop-level browsing contexts, thentry toclose the session.

5. Return the result of running theremote end steps for theGet Window Handlescommand, withsession,URL variables andparameters.

Theremote end steps, givensession,URLvariables andparameters are:

1. Lethandle be the result ofgetting the property "handle" fromparameters.

2. Ifhandle isundefined, returnerror witherror codeinvalid argument.

3. If there is an activeuser prompt, that prevents the focusing of anothertop-level browsing context, returnerror witherror codeunexpected alert open.

4. Ifhandle is equal to the associatedwindow handle for sometop-level browsing context, letcontext be the that browsing context, andset the current top-level browsing context withsession andcontext.

   Otherwise, returnerror witherror codeno such window.

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

6. Returnsuccess with datanull.

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

Theremote end steps, givensession,URLvariables andparameters are:

1. Lethandles be aList.

2. For eachtop-level browsing context in theremote end, push the associatedwindow handle ontohandles.

3. Returnsuccess with datahandles.

In order to determine whether or not a particular interaction with the browser opens a new window, one can obtain the set of window handles before the interaction is performed and compare it with the set after the action is performed.

Create a newtop-level browsing context.

Theremote end steps, givensession,URLvariables andparameters are:

1. If the implementation does not support creating new top-level browsing contexts, returnerror witherror codeunsupported operation.

2. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

3. Try tohandle any user prompts withsession.

4. Lettype hint be the result ofgetting the property "type" fromparameters.

5. Create a newtop-level browsing context by running thewindow open steps withURL set to "about:blank",target set to the empty string, andfeatures set to "noopener" and the user agent configured to create a new browsing context. This must be done without invoking thefocusing steps for the created browsing context. Iftype 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 withsession'scurrent browsing context. Iftype 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.

6. Lethandle be the associatedwindow handle of the newly created window.

7. Lettype be "tab" if the newly created window shares an OS-level window withsession'scurrent browsing context, or "window" otherwise.

8. Letresult be a new JSONObject initialized with:

   "handle"

   The value ofhandle.

   "type"

   The value oftype.

9. Returnsuccess with dataresult.

1. Letid be the result ofgetting the property "id" fromparameters.

2. Ifid is notnull, aNumber object, or anObject thatrepresents a web element, returnerror witherror codeinvalid argument.

3. Run the substeps of the first matching condition:

   id isnull

   1. Ifsession'scurrent top-level browsing context isno longer open, returnerror witherror codeno such window.

   2. Try tohandle any user prompts withsession.

   3. Set the current browsing context withsession andsession'scurrent top-level browsing context.

   id is aNumber object

   1. Ifid is less than 0 or greater than 2¹⁶ – 1, returnerror witherror codeinvalid argument.

   2. Ifsession'scurrent browsing context isno longer open, returnerror witherror codeno such window.

   3. Try tohandle any user prompts withsession.

   4. Letwindow be theassociated window ofsession'scurrent browsing context'sactive document.

   5. Ifid is not asupported property index ofwindow, returnerror witherror codeno such frame.

   6. Letchild window be theWindowProxy object obtained by callingwindow.[[GetOwnProperty]] (id).

   7. Set the current browsing context withsession andchild window'sbrowsing context.

   idrepresents a web element

   1. Ifsession'scurrent browsing context isno longer open, returnerror witherror codeno such window.

   2. Try tohandle any user prompts withsession.

   3. Letelement be the result oftrying toget a known element withsession andid.

   4. Ifelement is not aframe oriframe element, returnerror witherror codeno such frame.

   5. Set the current browsing context withsession andelement'scontent navigable'sactive browsing context.

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

5. Returnsuccess with datanull.

Theremote end steps, givensession,URLvariables andparameters are:

1. Ifsession'scurrent browsing context is already thetop-level browsing context:

   1. Ifsession'scurrent browsing context isno longer open, returnerror witherror codeno such window.

   2. Returnsuccess with datanull.

2. Ifsession'scurrent parent browsing context isno longer open, returnerror witherror codeno such window.

3. Try tohandle any user prompts withsession.

4. Ifsession'scurrent parent browsing context is notnull,set the current browsing context withsession andcurrent parent browsing context.

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

6. Returnsuccess with datanull.

WebDriver providescommands for interacting with the operating system window containingsession'scurrent 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 allremote ends. Support for thesecommands is determined by thewindow dimensioning/positioningcapability. Where acommand is not supported, anunsupported operationerror is returned.

Thetop-level browsing context has an associatedwindow 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 thetop-level browsing context'sOS window cannot enter either of thewindow states, or if thisconcept is not applicable on the current system, the default statemust benormal.

TheWindowRect object foraWindowProxy,window is anObject initializedwith the following properties:

"x"

window'sscreenX attribute.

"y"

window'sscreenY attribute.

"width"

windows'souterWidth attribute.

"height"

window'souterHeight attribute.

Tomaximize the window, given an operating system level window with an associatedtop-level browsing context, run the implementation-specific steps to transition the operating system level window into themaximized 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.

Toiconify the window, given an operating system level window with an associatedtop-level browsing context, run implementation-specific steps to transition the operating system level window into theminimized window state. Do not return from this operation until thevisibility state of thetop-level browsing context'sactive document has reached thehidden state, or until the operation times out.

Torestore the window, given an operating system level window with an associatedtop-level browsing context, run implementation-specific steps to restore or unhide the window to the visible screen. Do not return from this operation until thevisibility state of thetop-level browsing context'sactive document has reached thevisible state, or until the operation times out.

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

Aninteractable element is anelement which is eitherpointer-interactable orkeyboard-interactable.

Apointer-interactable element is defined to be the firstelement, defined by thepaint order found at thecenter point of its rectangle that is inside theviewport, excluding the size of any rendered scrollbars.

Akeyboard-interactable element is anyelement that has afocusable area, is abody element, or is thedocument element.

Anelement'sin-view center point is the origin position of the rectangle that is the intersection between the element's firstDOMRect ofgetClientRects() and theinitial viewport. It can be calculated this way:

1. Letrectangle be the first object of theDOMRect collection returned by callinggetClientRects() onelement.

2. Letleft bemax(0,min(x coordinate,x coordinate +width dimension)).

3. Letright bemin(innerWidth,max(x coordinate,x coordinate +width dimension)).

4. Lettop bemax(0,min(y coordinate,y coordinate +height dimension)).

5. Letbottom bemin(innerHeight,max(y coordinate,y coordinate +height dimension)).

6. Letx befloor((left +right) ÷ 2.0).

7. Lety befloor((top +bottom) ÷ 2.0).

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

Anelementelement isdisabled if the following steps return true:

1. Ifelement is anoption element orelement is anoptgroup element:

   1. For eachinclusive ancestorancestor ofelement:

      1. Ifancestor is anoptgroup element orancestor is aselect element, andancestor isactually disabled, return true.

   2. Return false.

2. Returnelement isactually disabled.

Anelement isin view if it is a member of its ownpointer-interactable paint tree, given the pretense that itspointer events are not disabled.

Anelement isobscured if thepointer-interactable paint tree at itscenter point is empty, or the first element in this tree is not aninclusive descendant of itself.

This ascertains if theelement'sin-view center point would be possible tointeract with.

For example, thepaint tree at this button'scenter point, the red square, is not itself the button or adescendant of the button. In other words, it is not aninclusive descendant. This makes the buttonobscured:

foobar

On the other hand, thecenter point of the following select list is the thirdoption element, because unlike a drop-down list,<select multiple>'s options are individually visible and painted. Because the option is adescendant of theselect element, it isnotobscured:

firstsecondthirdfourth

Anelement'spointer-interactable paint tree is produced this way:

1. Ifelement isnot in the same tree assession'scurrent browsing context'sactive document, return an empty sequence.

2. Letrectangles be theDOMRect sequence returned by callinggetClientRects().

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

4. Letcenter point be thein-view center point of the first indexed element inrectangles.

5. Return theelements from point given the coordinatescenter point.

Ashadow root is an abstraction used to identify ashadow root when it is transported via theprotocol, betweenremote andlocal ends.

Theshadow root identifier is the string constant "shadow-6066-11e4-a52e-4f735466cecf".

An ECMAScriptObjectrepresents a shadow root if it has ashadow root identifierown property.

Toget a known shadow root givensession andreference:

1. If notnode reference is known withsession,session'scurrent browsing context, andreference returnerror witherror codeno such shadow root.
2. Letnode be the result ofget a node withsession,session'scurrent browsing context, andreference.
3. Ifnode is not null andnode does not implementShadowRoot returnerror witherror codeno such shadow root.
4. Ifnode is null ornodeis detached returnerror witherror codedetached shadow root.
5. Returnsuccess with datanode.

Toget or create a shadow root reference givensession andshadow root:

1. Assert:element implementsShadowRoot.
2. Return the result oftrying toget or create a node reference withsession,session'scurrent browsing context, andelement.

Theshadow root reference object forsession andshadow root is given by:

1. Letidentifier be theshadow root identifier.

2. Letreference be the result ofget or create a shadow root reference withsession andshadow root.

3. Return a JSONObject initialized with a property with nameidentifier and valuereference.

When required todeserialize a shadow root by a JSONObjectobject thatrepresents a shadow root:

1. Ifobject has noown propertyshadow root identifier, returnerror witherror codeinvalid argument.

2. Letreference be the result ofgetting theshadow root identifier property fromobject.

3. Ifreference is not aString, return anerror witherror codeinvalid argument.

4. Letshadow be the result oftrying toget a known shadow root withsession andreference.

5. Returnsuccess with datashadow.

Ashadow rootis detached if itsnode document is not theactive document or if the element node referred to as itshostis stale.

TheFind Element,Find Elements,Find Element From Element,Find Elements From Element,Find Element From Shadow Root, andFind Elements From Shadow Rootcommands 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.

When required tofind givensession,start node,using andvalue, aremote end must run the following steps:

1. Letlocation strategy be equal tousing.

2. Letselector be equal tovalue.

3. Lettimeout besession'ssession timeouts'implicit wait timeout.

4. Lettimer be a newtimer.

5. Iftimeout is not null:

   1. Start the timer withtimer andtimeout.

6. Letelements returned be an emptyList.

7. Whileelements returned is empty andtimer'stimeout fired flag is not set:

   1. Setelements returned to the result oftrying to call the relevantelement location strategy with argumentsstart node, andselector.

   2. If aDOMException,SyntaxError,XPathException, or other error occurs during the execution of theelement location strategy, returnerrorinvalid selector.

8. Letresult be an emptyList.

9. For eachelement inelements returned, append theweb element reference object forsession andelement, toresult.

10. Returnsuccess with dataresult.

let body = session.find.css("#toremove");session.execute("arguments[0].remove()", [body]);

Tocalculate the absolute positiongivensession andelement:

1. Letrect be the value returned by callinggetBoundingClientRect().

2. Letwindow be theassociated window ofsession'scurrent top-level browsing context.

3. Letx be (scrollX ofwindow +rect'sx coordinate).

4. Lety be (scrollY ofwindow +rect'sy coordinate).

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

To determine ifnode isnot in the same tree as anothernode,other, run the following substeps:

1. If thenode'snode document is notother'snode document, return true.

2. Return true if the result of calling thenode'scompareDocumentPosition() withother as argument isDOCUMENT_POSITION_DISCONNECTED (1), otherwise return false.

Anelement'scontainer is:

option element in a validelement context

optgroup element in a validelement context

Theelement'selement context, which is determined by:

1. Letdatalist parent be the firstdatalist element reached by traversing the tree in reverse order fromelement, orundefined if the root of the tree is reached.

2. Letselect parent be the firstselect element reached by traversing the tree in reverse order fromelement, orundefined if the root of the tree is reached.

3. Ifdatalist parent isundefined, theelement context isselect parent. Otherwise, theelement context isdatalist parent.

option element in an invalidelement context

The element does not have a container.

Otherwise

The container is theelement itself.