Copyright © 2017 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
WebDriver is a remote control interface that enables introspection and control of user agents. It provides a platform- and language-neutral wire protocol as a way for out-of-process programs to remotely instruct the behaviour of web browsers.
Provided is a set of interfaces to discover and manipulate DOM elements in web documents and to control the behaviour of a user agent. It is primarily intended to allow web authors to write tests that automate a user agent from a separate controlling process, but may also be used in such a way as to allow in-browser scripts to control a — possibly separate — browser.
The standard forms part of the Web Testing Activity that authors a larger set of tools commonly used for testing.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Browser Testing and Tools Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-browser-tools-testing@w3.org (subscribe, archives). All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHOULD”, “ SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in [RFC2119]. The key word “OPTIONALLY” in the normative parts of this document is to be interpreted with the same normative meaning as “MAY” and “OPTIONAL”.
Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent.
This specification relies on several other underlying specifications.
The following terms are defined in the Content Security Policy Level 3 specification: [CSP3]
The following terms are defined in the Document Object Model specification: [DOM]
getElementsByTagName
HTMLCollection
NodeList
querySelector
querySelectorAll
Text
node
The following attributes are defined in the DOM Parsing and Serialisation specification: [DOM-PARSING]
The following attributes are defined in the UI Events specification: [UI-EVENTS]
The following attributes are defined in the UI Events Code specification: [UIEVENTS-CODE]
The following attributes are defined in the UI Events Code specification: [UIEVENTS-KEY]
The following terms are defined in the ECMAScript Language Specification: [ECMA-262]
The following terms are defined in the WHATWG Fetch specification: [FETCH]
The following terms are defined in the WHATWG Fullscreen specification: [FULLSCREEN]
The following terms are defined in the HTML specification: [HTML]
activeElement
attribute on Document
body
element
multiple
attribute
Document
object
Window
object
innerText
input
event applies
input
event
Navigator object
setSelectionRange
value
attribute
The HTML specification also defines a number of elements which this specification has special-cased behaviour for:
The following types are also defined in the HTML specification, and referenced here:
canvas
’s height attribute
canvas
’ width attribute
Window
object
WindowProxy
exotic object
readOnly
attribute
showModalDialog()
type
attribute
confirm
alert
print
prompt
The HTML Editing APIs specification defines the following terms: [EDITING]
The following events are also defined in the HTML specification:
The “data” URL scheme specification defines the following terms: [RFC2397]
To be HTTP compliant, it is supposed that the implementation supports the relevant subsets of [ RFC7230], [RFC7231], [RFC7232], [RFC7234], and [RFC7235].
The following terms are defined in the Cookie specification: [RFC6265]
The following terms are defined in the Hypertext Transfer Protocol (HTTP) Status Code Registry:
The specification uses URI Templates. [URI-TEMPLATE]
visibility
property
display
property
ScrollIntoViewOptions
To be SOCKS Proxy and SOCKS authentication compliant, it is supposed that the implementation supports the relevant subsets of [ RFC1928] and [RFC1929].
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
The following terms are defined in the Document Object Model XPath standard [XPATH]
In equations, all numbers are integers, addition is represented by “+”, subtraction is represented by “−”, and bitwise OR by “|”. The characters “(” and “)” are used to provide logical grouping in these contexts.
The shorthand min(value, value[, value]) returns the smallest item of two or more values. Conversely, the shorthand max(value, value[, value]) returns the largest item of two or more values.
A Universally Unique IDentifier (UUID) is a 128 bits long URN that requires no central registration process. [RFC4122]. Generating a UUID means Creating a UUID From Truly Random or Pseudo-Random Numbers [RFC4122], and serializing it as appropriate for the callee.
The Unix Epoch is a value that approximates the number of seconds that have elapsed since the Epoch, as described by The Open Group Base Specifications Issue 7 section 4.15 (IEEE Std 1003.1).
An Integer is a Number that is unchanged under the ToInteger operation.
The initial value of a javascript property is the value defined by the platform for that property i.e. the value it would have in the absence of any shadowing by content script.
The browser chrome is a non-normative term to describe the user interface of the user agent. Examples of browser chrome elements include but are not limited to: toolbars (such as a bookmark toolbar), menus (such as the file menu), buttons (such as the back button) and decorations (such as security and certificate indicators).
The webdriver
IDL attribute of the
interface must return the value of the webdriver-active flag, which is initially false.
Navigator
This property allows websites to determine that the user agent is under control by WebDriver, and can be used to help mitigate denial-of-service attacks.
The WebDriver protocol consists of communication between:
The local end represents the client side of the protocol, which is usually in the form of language-specific libraries providing an API on top of the WebDriver protocol. This specification does not place any restrictions on the details of those libraries above the level of the wire protocol.
Define the requirements on the local end somewhere.
For remote ends the standard defines two broad conformance classes, known as node types:
A remote end’s readiness state is for each node type said to be:
False if it is known to be in a state in which attempting to create a new session would fail. Otherwise true.
False if the maximum active sessions is equal to the length of the list of active sessions or there is a current user prompt present. Otherwise true.
If the intermediary node is a multiplexer that manages multiple endpoint nodes, this might indicate its ability to purvey more sessions, for example if it has hit its maximum capacity.
WebDriver remote ends must provide an HTTP compliant wire protocol where the endpoints map to different commands.
As this standard only defines the remote end protocol, it puts no demands to how local ends should be implemented. Local ends are only expected to be compatible to the extent that they can speak the remote end’s protocol; no requirements are made upon their exposed user-facing API.
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 "Let temp be the result of calling algorithm. If temp is an error return temp, otherwise let result be temp's data field.
The result of getting a property with name from an Object is defined as the result of calling the [[GetOwnProperty]] internal method of with property name name.
The result of setting a property with name and value to an Object is defined as calling the [[Put]] internal method with name name and value value.
The result of JSON serialization with object of type JSON Object and calling the [[Stringify]] function with argument object.
The result of JSON deserialization with text is defined as the result of calling the [[Parse]] function with text.
The WebDriver protocol is organised into commands. Each HTTP request with a method and template defined in this specification represents a single command and therefore each command produces a single HTTP response. In response to a command, a remote end will run a series of actions against the remote browser.
Each command defined in this specification has an associated list of remote end steps. This provides the sequence of actions that a remote end takes when it receives a particular command.
The remote end acts as a HTTP server reading requests from the client and writing responses, typically over TCP socket. For the purposes of this specification we model the data transmission between a particular local end and remote end with a connection to which the remote end may write bytes and read bytes. However the exact details of how this connection works and how it is established are out of scope.
After such a connection has been established, a remote end MUST run the following steps:
Should mention what happens if it can’t be decoded as HTTP. Note that Fetch isn’t quite right because it doesn’t specify how to construct a request from network data, or serialize a response.
Read bytes from the connection until a complete HTTP request can be constructed from the data. Let request be a request constructed from the received data, according to the requirements of [RFC7230].
Let request match be the result of the algorithm to match a request with request’s method and URL as arguments.
If request match is of type error, send an error with request match’s error code and jump to step 1.
Otherwise, let command and url variables be request match’s data.
Let session id be the corresponding variable from url variables.
If command is not New Session:
If session id is not equal to the ID of any session in the list of active sessions, send an error with error code invalid session id, then jump to step 1 in this overall algorithm.
Otherwise, let the current session be the session with ID session id.
If request’s method is POST:
Let parse result be the result of parsing as JSON with request’s body as the argument.
If parse result is an error or if it is a success but its associated data 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’s data.
Otherwise, let parameters be null.
Let response result be the return value obtained by running the remote end steps for command with url variables as arguments.
If response result is an error, send an error with error code equal to response result’s error code and jump back to step 1 in this overall algorithm.
Otherwise, if response result is a success, let response data be response result’s data.
Send a response with status 200 and response data.
Jump to step 1.
When required to send an error, with error code, a remote end must run the following steps:
Let http status and name be the error response data for error code.
Let message be an implementation-defined string containing a human-readable description of the reason for the error.
Let stacktrace be an implementation-defined string containing a stack trace report of the active stack frames at the time when the error occurred.
Really need a better way to construct JSON literals.
Let data be a new JSON Object initialised with the following properties:
error
message
stacktrace
Send a response with status and data as arguments.
When required to send a response, with arguments status and data, a remote end must run the following steps:
Let response be a new response.
Set response’s HTTP status to status, and status message to the string corresponding to the description of status in the status code registry.
Set the response's header with name and value with the following values:
Content-Type
"
application/json; charset=utf-8
"
cache-control
"
no-cache
"
If data is not null, let response’s
body be a JSON Object with a key value
set to the JSON Serialization of data.
Let response bytes be the byte sequence resulting from serializing response according to the rules in [RFC7230].
Write response bytes to the connection.
Request routing is the process of going from a HTTP request to the series of steps needed to implement the command represented by that request.
A remote end has an associated URL prefix, which is used as a prefix on all WebDriver-defined URLs on that remote end. This must either be undefined or an path-absolute URL.
In order to match a request given a method and URL, the following steps must be taken:
Let endpoints be a list containing each row in the table of endpoints.
Remove each entry from endpoints for which the concatenation of the URL prefix and the entry’s URI template does not match URL’s path.
If there are no entries in endpoints, return error with error code unknown command.
Remove each entry in endpoints for which the method column is not an exact case-sensitive match for method.
If there are no entries in endpoints, return error with error code unknown method.
There is now exactly one entry in endpoints; let entry be this entry.
Let parameters be the result of extracting the variables from URL using entry’s URI template.
Let command be entry’s command.
Return success with data command and parameters.
The following table of endpoints lists the method and URI template for each endpoint node command.
Method | URI Template | Command |
---|---|---|
POST | /session | New Session |
DELETE | /session/{session id} | Delete Session |
GET | /status | Status |
GET | /session/{session id}/timeouts | Get Timeouts |
POST | /session/{session id}/timeouts | Set Timeouts |
POST | /session/{session id}/url | Go |
GET | /session/{session id}/url | Get Current URL |
POST | /session/{session id}/back | Back |
POST | /session/{session id}/forward | Forward |
POST | /session/{session id}/refresh | Refresh |
GET | /session/{session id}/title | Get Title |
GET | /session/{session id}/window | Get Window Handle |
DELETE | /session/{session id}/window | Close Window |
POST | /session/{session id}/window | Switch To Window |
GET | /session/{session id}/window/handles | Get Window Handles |
POST | /session/{session id}/frame | Switch To Frame |
POST | /session/{session id}/frame/parent | Switch To Parent Frame |
GET | /session/{session id}/window/rect | Get Window Rect |
POST | /session/{session id}/window/rect | Set Window Rect |
POST | /session/{session id}/window/maximize | Maximize Window |
POST | /session/{session id}/window/minimize | Minimize Window |
POST | /session/{session id}/window/fullscreen | Fullscreen Window |
GET | /session/{session id}/element/active | Get Active Element |
POST | /session/{session id}/element | Find Element |
POST | /session/{session id}/elements | Find Elements |
POST | /session/{session id}/element/{element id}/element | Find Element From Element |
POST | /session/{session id}/element/{element id}/elements | Find Elements From Element |
GET | /session/{session id}/element/{element id}/selected | Is Element Selected |
GET | /session/{session id}/element/{element id}/attribute/{name} | Get Element Attribute |
GET | /session/{session id}/element/{element id}/property/{name} | Get Element Property |
GET | /session/{session id}/element/{element id}/css/{property name} | Get Element CSS Value |
GET | /session/{session id}/element/{element id}/text | Get Element Text |
GET | /session/{session id}/element/{element id}/name | Get Element Tag Name |
GET | /session/{session id}/element/{element id}/rect | Get Element Rect |
GET | /session/{session id}/element/{element id}/enabled | Is Element Enabled |
POST | /session/{session id}/element/{element id}/click | Element Click |
POST | /session/{session id}/element/{element id}/clear | Element Clear |
POST | /session/{session id}/element/{element id}/value | Element Send Keys |
GET | /session/{session id}/source | Get Page Source |
POST | /session/{session id}/execute/sync | Execute Script |
POST | /session/{session id}/execute/async | Execute Async Script |
GET | /session/{session id}/cookie | Get All Cookies |
GET | /session/{session id}/cookie/{name} | Get Named Cookie |
POST | /session/{session id}/cookie | Add Cookie |
DELETE | /session/{session id}/cookie/{name} | Delete Cookie |
DELETE | /session/{session id)/cookie | Delete All Cookies |
POST | /session/{session id}/actions | Perform Actions |
DELETE | /session/{session id}/actions | Release Actions |
POST | /session/{session id}/alert/dismiss | Dismiss Alert |
POST | /session/{session id}/alert/accept | Accept Alert |
GET | /session/{session id}/alert/text | Get Alert Text |
POST | /session/{session id}/alert/text | Send Alert Text |
GET | /session/{session id}/screenshot | Take Screenshot |
GET | /session/{session id}/element/{element id}/screenshot | Take Element Screenshot |
Errors are represented in the WebDriver protocol with a HTTP response with a HTTP status in the 4xx or 5xx range, and a JSON body containing details of the error. This JSON body has three fields:
error
, containing a string indicating the error type;
message
, containing an implementation-defined string with a human readable description of the kind of error that occurred; and stacktrace
, containing an implementation-defined string with a stack trace report of the active stack frames at the time when the error occurred.
The following table lists each error code, its associated HTTP status, JSON error
code, and a non-normative description of the error. The error response data for a particular error code is the values of the HTTP Status and JSON Error Code columns for the row corresponding to that error code.
Error Code | HTTP Status | JSON Error Code | Description |
---|---|---|---|
element click intercepted | 400 | element click intercepted
|
The Element Click command could not be completed because the element receiving the events is not the same element that was requested clicked. |
element not selectable | 400 | element not selectable
|
An attempt was made to select an element that cannot be selected. |
element not interactable | 400 | element not interactable
|
A command could not be completed because the element is not pointer- or keyboard interactable. |
insecure certificate | 400 | insecure certificate
|
Navigation caused the user agent to hit a certificate warning, which is usually the result of an expired or invalid TLS certificate. |
invalid argument | 400 | invalid argument
|
The arguments passed to a command are either invalid or malformed. |
invalid cookie domain | 400 | invalid cookie domain
|
An illegal attempt was made to set a cookie under a different domain than the current page. |
invalid coordinates | 400 | invalid coordinates
|
The coordinates provided to an interactions operation are invalid. |
invalid element state | 400 | invalid element state
|
A command could not be completed because the element is in an invalid state, e.g. attempting to click an element that is no longer attached to the document. |
invalid selector | 400 | invalid selector
|
Argument was an invalid selector. |
invalid session id | 404 | invalid session id
|
Occurs if the given session id is not in the list of active sessions, meaning the session either does not exist or that it’s not active. |
javascript error | 500 | javascript error
|
An error occurred while executing JavaScript supplied by the user. |
move target out of bounds | 500 | move target out of bounds
|
The target for mouse interaction is not in the browser’s viewport and cannot be brought into that viewport. |
no such alert | 400 | no such alert
|
An attempt was made to operate on a modal dialog when one was not open. |
no such cookie | 404 | no such cookie
|
No cookie matching the given path name was found amongst the associated cookies of the current browsing context’s active document. |
no such element | 404 | no such element
|
An element could not be located on the page using the given search parameters. |
no such frame | 400 | no such frame
|
A request to switch to a frame could not be satisfied because the frame could not be found. |
no such window | 400 | no such window
|
A request to switch to a window could not be satisfied because the window could not be found. |
script timeout | 408 | script timeout
|
A script did not complete before its timeout expired. |
session not created | 500 | session not created
|
A new session could not be created. |
stale element reference | 400 | stale element reference
|
A command failed because the referenced element is no longer attached to the DOM. |
timeout | 408 | timeout
|
An operation did not complete before its timeout expired. |
unable to set cookie | 500 | unable to set cookie
|
A request to set a cookie’s value could not be satisfied. |
unable to capture screen | 500 | unable to capture screen
|
A screen capture was made impossible. |
unexpected alert open | 500 | unexpected alert open
|
A modal dialog was open, blocking this operation. |
unknown command | 404 | unknown command
|
A command could not be executed because the remote end is not aware of it. |
unknown error | 500 | unknown error
|
An unknown error occurred in the remote end while processing the command. |
unknown method | 405 | unknown method
|
The requested command matched a known URL but did not match an method for that URL. |
unsupported operation | 500 | unsupported operation
|
Indicates that a command that should have executed properly cannot be supported for some reason. |
The protocol is designed to allow extension to meet vendor-specific needs. Commands that are specific to a user agent 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 name that is an ASCII lower alpha string, and which should bear some resemblance to what the command performs. The name is used to form an extension command’s URL.
The extension command’s extension command URL is a URL composed of the extension command prefix, followed by "/
", and the extension command’s name. The extension command URL, 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.
An extension command prefix is an ASCII lower alpha string that forms a URL path part, separating extension commands from other commands in order to avoid potential resource conflicts with other implementations. It is suggested that vendors use their vendor prefixes without additional characters as outlined in [CSS21], notably in section 4.1.2.2 on vendor keywords, as the name for this path element, and include a vendor-chosen UA identifier.
Remote ends may also introduce
extension capabilities that are extra capabilities used to provide configuration or fulfill other vendor-specific needs. Extension capabilities’ key must contain a ":
" (colon) character, denoting an implementation specific namespace. The value can be arbitrary JSON types.
As with extension commands, it is suggested that the key used to denote the extension capability namespace is based on the vendor keywords listed in [CSS21] and preceeds the first ":
" character in the string.
WebDriver capabilities are used to communicate the features supported by a given implementation. The local end may use capabilities to define which features it requires the remote end to satisfy when creating a new session. Likewise, the remote end uses capabilities to describe the full feature set for a session.
The following table of standard capabilities enumerates the capabilities each implementation MUST support. An implementation MAY define additional extension capabilities.
Capability | Key | Value Type | Description |
---|---|---|---|
Browser name | "browserName "
|
string | Identifies the user agent. |
Browser version | "browserVersion "
|
string | Identifies the version of the user agent. |
Platform name | "platformName "
|
string | Identifies the system or operating system of the endpoint node. |
Platform version | "platformVersion "
|
string | Identifies the system version of the endpoint node. |
Accept insecure TLS certificates | "acceptInsecureCerts "
|
boolean | Indicates whether untrusted and self-signed TLS certificates are implicitly trusted on navigation for the duration of the session. |
Page load strategy | "pageLoadStrategy "
|
string | Defines the current session’s page load strategy. |
Proxy configuration | "proxy "
|
JSON Object | Defines the current session’s proxy configuration. |
Session timeouts configuration | "timeouts "
|
JSON Object | Describes the timeouts imposed on certain session operations. |
Unexpected Alert Behaviour | "unexpectedAlertBehaviour "
|
string | Describes the current session's user prompt handler. |
The proxy configuration capability is a JSON Object nested within the primary capabilities. Implementations may define additional proxy configuration options, but they must not alter the semantics of those listed below.
Key | Value Type | Description | Valid values |
---|---|---|---|
"proxyType "
|
string | Indicates the type of proxy configuration. | "pac ", "noproxy ", "
autodetect ", "system ", or "manual ".
|
"proxyAutoconfigUrl "
|
string | Defines the URL for a proxy auto-config file if "proxyType " is equal to "pac ". [URL]
|
|
"ftpProxy "
|
string | Defines the proxy host for FTP traffic when the "proxyType " is equal to "manual ".
|
|
"ftpProxyPort "
|
number | Defines the proxy port for FTP traffic when the "proxyType " is equal to "manual ".
|
|
"httpProxy "
|
string | Defines the proxy host for HTTP traffic. If a URL is passed through this property, set "httpProxy " to the host and "httpProxyPort " to the port when the "proxyType " is equal to "manual ".
|
|
"httpProxyPort "
|
number | Defines the proxy port for HTTP traffic when the "proxyType " is equal to "manual ". If "httpProxyPort " is defined in "httpProxy " and from this property, return error with error code invalid argument.
|
|
"sslProxy "
|
string | Defines the proxy host for encrypted TLS traffic when the "proxyType " is equal to "manual ". If a URL is passed through this property, set "sslProxy " to the host and "sslProxyPort " to the port.
|
|
"sslProxyPort "
|
number | Defines the proxy port for ssl traffic when the "proxyType " is equal to "manual ". If "sslProxyPort " is defined in "sslProxy " and from this property, return error with error code invalid argument.
|
|
"socksProxy "
|
string | Defines the proxy host for a SOCKS proxy when the "proxyType " is equal to "manual ". If a URL is passed through this property, set "socksProxy " to the host and "socksProxyPort " to the port.
|
|
"socksProxyPort "
|
number | Defines the proxy port for a SOCKS proxy when the "proxyType " is equal to "manual ". If "socksProxyPort " is defined in "socksProxyPort " and from this property, return error with error code invalid argument.
|
|
"socksVersion "
|
number | Defines the SOCKS proxy version when the "proxyType " is equal to "manual ".
|
|
"socksUsername "
|
string | Defines the username used when authenticating with a SOCKS proxy when the "proxyType " is equal to "manual ".
|
|
"socksPassword "
|
string | Defines the password used when authenticating with a SOCKS proxy, when the "proxyType " is equal to "manual ", and is not returned with capabilities to the local end.
|
The session timeouts configuration capability is a JSON Object nested within the primary capabilities. It consists of the properties listed in the table below. These values may be changed after creating a new session using the Set Timeouts command.
Key | Value Type | Description |
---|---|---|
"implicit "
|
number | Specifies the session implicit wait timeout. |
"page load "
|
number | Specifies the session page load timeout. |
"script "
|
number | Specifies the session script timeout. |
When processing capabilities with argument parameters, the endpoint node must take the following steps:
Let capabilities request be the result of getting a property named "capabilities
" from parameters.
If capabilities request is not a JSON object, return error with error code invalid argument.
Let required capabilities be the result of getting a property named "alwaysMatch
" from capabilities request.
If required capabilities is undefined, set the value to an empty JSON Object.
If required capabilities is not a JSON Object, return error with error code invalid argument.
Let desired capabilities be the result of getting a property named "firstMatch
" from capabilities request.
If desired capabilities is undefined, set the value to a JSON List with a single entry of an empty JSON Object.
If desired capabilities is not a JSON List, return error with error code invalid argument.
Let matched capabilities be null
.
For each current desired capabilities corresponding to an indexed property in desired capabilities until matched capabilities is no longer null
or there are no longer any entries to process:
If current desired capabilities is not a JSON Object, return error with error code invalid argument.
Let merged capabilities be the result of merging capabilities with required capabilities and current desired capabilities as arguments.
If merged capabilities is an error, return the merged capabilities error.
Set matched capabilities to the result of matching capabilities with merged capabilities as an argument.
Return matched capabilities.
When merging capabilities with JSON Object arguments primary and secondary, an endpoint node must take the following steps:
Let result be a JSON Object with the same entries as primary.
If secondary is undefined, return result.
For each entry corresponding to an indexed property in secondary, if the name of entry is also the name of an entry in result, return error with error code invalid argument. Otherwise, add entry to result.
Return result.
When matching capabilities with JSON Object argument capabilities, an endpoint node must take the following steps:
Let matched capabilities be a JSON Object with the following entries:
browserName
"
browserVersion
"
platformName
"
platformVersion
"
acceptInsecureCerts
"
For each capability name corresponding to a property in capabilities:
Let capability value be the value of property capability name in capabilities.
Run the substeps of the first matching capability name:
browserName
"
If capability value is null, undefined, or equal to the string "*
", it is considered a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to the "browserName
" entry in matched capabilities, return null.
browserVersion
"
If capability value is null, undefined, or equal to the string "*
", it is to be considered a match for the entry in matched capabilities.
Otherwise, compare capability value to the "
browserVersion
" entry in matched capabilities using an implementation-defined comparison algorithm. The comparison is to accept a capability value that places constraints on the version using the "<
", "
<=
", ">
", and ">=
" operators.
If the two values do not match, return null.
Version comparison is left as an implementation detail since each user agent will likely have conflicting methods of encoding the user agent version and standardizing these schemes is beyond the scope of this specification.
platformName
"
If capability value is null, undefined, or equal to the string "*
", it is considered a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to the "platformName
" entry in
matched capabilities, return null.
platformVersion
"
If capability value is null, undefined, or equal to the string "*
", it is considered a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to the "platformVersion
" entry in
matched capabilities, return null.
acceptInsecureCerts
"
If capability value is not a boolean, return error with error code invalid argument.
If capability value is true
and the endpoint node does not support insecure TLS certificates, return null.
Otherwise, set the "acceptInsecureCerts
" entry in
matched capabilities to capability value.
pageLoadStrategy
"
If capability value is not a string, return error with error code invalid argument.
Otherwise, set the "pageLoadStrategy
" entry in
matched capabilities to capability value.
proxy
"
If capability value is not a proxy configuration, return error with error code invalid argument.
If the endpoint node does not support the proxy configuration defined in capability value, return null.
Otherwise, set the "proxy
" entry in
matched capabilities to capability value.
timeouts
"
If capability value is not a session timeouts configuration object, return error with error code invalid argument.
Otherwise, set the "timeouts
" entry in
matched capabilities to capability value.
If capability name is not recognized by the endpoint node, return null.
Let processed value be the result of implementation specific steps to match on capability name with capability value.
If processed value is an error, return processed value.
Otherwise, create a new entry in matched capabilities with name capability name and value processed value.
Return matched capabilities.
A session is equivalent to a single instantiation of a particular user agent, including all its child browsers. WebDriver gives each session a unique session ID that can be used to differentiate one session from another, allowing multiple user agents to be controlled from a single HTTP server, and allowing sessions to be routed via a multiplexer (known as an intermediary node).
A session is started when a New Session is invoked. It is an error to send any commands before starting a session, or to continue to send commands after the session has been closed. Maintaining session continuity between requests to the remote end requires passing a session ID.
A WebDriver session represents the connection between a local end and a specific remote end. A remote end that is not an intermediary node has at most one active session at a given time.
The session is set up at the invocation of a New Session, and torn down at some later point; either explicitly by invoking Delete Session, or implicitly when Close Window is called at the last remaining top-level browsing context.
A remote end has an associated list of active sessions, which is a list of all sessions that are currently started.
Requests, except New Session requests, have an associated current session, which is the session in which that request's command will run.
A remote end has an associated maximum active sessions (an integer) that defines the number of active sessions that are supported. This may be “unlimited” for intermediary nodes, but must be exactly one for a remote end that is an endpoint node.
A session has an associated session ID (a UUID) used to uniquely identify this session. Unless stated otherwise it is null.
A session has an associated current browsing context, which is the browsing context against which commands will run.
A session has an associated current top-level browsing context, which is the current browsing context if it itself is a top-level browsing context, and otherwise is the top-level browsing context of the current browsing context.
A session has an associated session script timeout that specifies a time to wait for scripts to run. If equal to null then session script timeout will be indefinite. Unless stated otherwise it is 30,000 milliseconds.
A session has an associated session page load timeout that specifies a time to wait for the page loading to complete. Unless stated otherwise it is 300,000 milliseconds.
A session has an associated session implicit wait timeout that specifies a time to wait in milliseconds for the element location strategy when retreiving elements and when waiting for an element to become interactable when performing element interaction . Unless stated otherwise it is zero milliseconds.
A session has an associated page loading strategy, which is one of none, normal, and eager. Unless stated otherwise, it is normal.
A session has an associated secure TLS state that indicates whether untrusted or self-signed TLS certificates should be trusted for the duration of the WebDriver session. If it is unset, this indicates that certificate- or TLS errors that occur upon navigation should be suppressed. The state can be unset by providing an "acceptInsecureCerts
" capability with the value true. Unless stated otherwise, it is set.
A session has an associated user prompt handler.
A session has an associated input state.
A session has an associated input cancel list.
When asked to close the session, a remote end must take the following steps:
Set the webdriver-active flag to false.
Close any top-level browsing contexts associated with the session, without prompting to unload.
Remove the current session from active sessions.
Perform any implementation-specific cleanup steps.
Closing a session might cause the associated browser process to be killed. It is assumed that any implementation-specific cleanup steps are performed after the response has been sent back to the client so that the connection is not prematurely closed.
HTTP Method | Path Template |
---|---|
POST | /session |
The New Session command creates a new WebDriver session with the endpoint node. If the maximum active sessions has been reached, there is a problem processing the given capabilities, or the provisioning of a remote end is impossible, a session not created error is returned.
If the remote end is an intermediary node, it MAY use the result of the processing capabilities algorithm to route the new session request to the appropriate endpoint node. An intermediary node MAY also define custom capabilities to assist in this process, however, these capabilities MUST NOT be forwarded to the endpoint node. Furthermore, if the intermediary node requires additional information unrelated to user agent features, it is RECOMMENDED that this information be passed as top-level parameters and not part of the requested capabilities. An intermediary node MAY forward custom, top-level parameters (i.e. non-capabilities) to subsequent remote end nodes.
The remote end steps are:
If the remote end is an intermediary node, take implementation-defined steps that either result in returning an error with error code session not created, or in returning a success with data that is isomorphic to that returned by remote ends according to the rest of this algorithm.
If the maximum active sessions is equal to the length of the list of active sessions, return error with error code session not created.
If there is a current user prompt, return error with error code session not created.
Let capabilities result be the result of processing capabilities with parameters as an argument.
If capabilities result is an error, return error with error code session not created and the error data from capabilities result.
If capabilities result is null, return error with error code session not created.
Let capabilities be capabilities result’s data.
Let session id be the result of generating a UUID.
Let session be a new session with the session ID of session id.
Set the current session to session.
Append session to active sessions.
Let body be a JSON Object initialised with:
sessionId
capabilities
Initialise the following from capabilities:
Let strategy be the result of getting property "
pageLoadStrategy
" from capabilities.
If strategy is a string, set the current session's page loading strategy to strategy. Otherwise, set the page loading strategy to normal.
Let proxy be the result of getting property "
proxy
" from capabilities.
If proxy is a proxy configuration object, take implementation-defined steps to set the user agent proxy using the extracted proxy configuration. If the defined proxy cannot be configured, return error with error code session not created.
Let timeouts be the result of getting property "
timeouts
" from capabilities.
If timeouts is a session timeouts configuration object:
If timeouts has a numeric property with key "
implicit
", set the current session's
session implicit wait timeout to the value of property "
implicit
". Otherwise, set the
session implicit wait timeout to 0 (zero) milliseconds.
If timeouts has a numeric property with key "
page load
", set the current session's
session page load timeout to the value of property "
page load
". Otherwise, set the
session page load timeout to 300,000 milliseconds.
If timeouts has a numeric property with key "
script
", set the current session's
session script timeout to the value of property "
script
". Otherwise, set the
session script timeout to 30,000 milliseconds.
Apply changes to the user agent for any implementation defined capabilities selected during the processing capabilities step.
Set the webdriver-active flag to true.
Return success with data body.
HTTP Method | Path Template |
---|---|
DELETE | /session/{session id} |
The Delete Session command closes any top-level browsing contexts associated with the current session, terminates the connection, and finally closes the current session.
The remote end steps are:
Return success with data null.
HTTP Method | Path Template |
---|---|
GET | /status |
The Status command returns information about whether a remote end is in a state in which it can create new sessions and can additionally include arbitrary meta information that is specific to the implementation.
The readiness state is represented by the ready
property of the body, which is false if an attempt to create a session at the current time would fail. However, the value true does not guarantee that a new session request will succeed.
Implementations may optionally include additional meta information as part of the body, but the top-level properties
ready
and message
are reserved and must not be overwritten.
The remote end steps are:
Let body be a new JSON Object with the following properties:
ready
The remote end’s readiness state.
message
An implementation-defined string explaining the remote end’s readiness state.
Return success with data body.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/timeouts |
The Get Timeout command gets timeouts associated with the current session.
The remote end steps are:
Let body be a new JSON Object.
Set a property of body with name "script"
and value equal to the session
script timeout.
Set a property of body with name "page load"
and value equal to the session
page load timeout.
Set a property of body with name "implicit"
and value equal to the session
implicit wait timeout.
Return success with data body.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/timeouts |
The Set Timeouts command sets timeouts associated with the current session. The timeouts that can be controlled are listed in the table of session timeouts below.
The following table of session timeouts enumerates the different timeout types that may be set. The keywords given in the first column maps to the timeout type given in the second.
Keyword | Type | Brief description |
---|---|---|
"script "
|
session script timeout | Determines when to interrupt a script that is being evaluated. |
"page load "
|
session page load timeout | Provides the timeout limit used to interrupt navigation of the browsing context. |
"implicit "
|
session implicit wait timeout | Gives the timeout of when to abort locating an element. |
The remote end steps are:
If parameters is not a JSON Object, return error with error code invalid argument.
For each key and value of parameters’s own properties:
Find the timeout type from the table of session timeouts by looking it up by its keyword key.
If no keyword matches key, return error with error code invalid argument.
If value is not an integer, or it is less than 0 or greater than 264 – 1, return error with error code invalid argument.
Set timeout type’s value.
Return success with data null.
Many WebDriver commands happen in the context of either the current browsing context or current top-level browsing context. The current top-level browsing context is represented in the protocol by its associated window handle. A top-level browsing context is selected using the Switch To Window command. Once this is done, a specific browsing context can be selected using the Switch to Frame command.
The use of the term “window” to refer to a top-level browsing context is legacy and doesn’t correspond with either the operating system notion of a “window” or the DOM Window
object.
A browsing context is said to be no longer open if it has been discarded.
Each browsing context has an associated
window handle (string) uniquely identifying it. It must not be "current
".
The web window identifier is the string constant "window-fcc6-11e5-b4f8-330a88ab9d7f
".
The web frame identifier is the string constant "frame-075b-4da1-b6ba-e579c2d3230a
".
The JSON Serialization of the WindowProxy
object is the JSON Object obtained by applying the following algorithm to the given WindowProxy
object window:
Let identifier be the web window identifier if the associated browsing context of window is a top-level browsing context.
Otherwise let it be the web frame identifier.
Return a JSON Object initialised with the following properties:
Associated window handle of the window’s browsing context.
In accordance with the focus section of the [HTML] specification, commands are unaffected by whether the operating system window has focus or not.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/window |
The Get Window Handle command returns the window handle for the current top-level browsing context. It can be used as an argument to Switch To Window.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Return success with data being the window handle associated with the current top-level browsing context.
HTTP Method | Path Template |
---|---|
DELETE | /session/{session id}/window |
The remote end steps for the Close Window command are:
If the current top-level browsing context is no longer open, return error with error code no such window.
This can prompt unload, in which case the operation really failed.
If there are no more open top-level browsing contexts, then close the session.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window |
The Switch To Window command is used to select the current top-level browsing context for the current session, i.e. the one that will be used for processing commands.
The remote end steps are:
If there is an active user prompt, that due to the uniqueness of the user agent prevents the focussing of another top-level browsing context, return error with error code unsupported operation.
Let handle be the result of
getting a property named "handle
" from the parameters argument.
If handle is equal to the associated window handle for some top-level browsing context in the current session, set the session’s current browsing context to that browsing context, and return success with data null.
Otherwise, return error with error code no such window.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/window/handles |
The Get Window Handles command returns a list of window handles for every open top-level browsing context. The order in which the window handles are returned is arbitrary.
The remote end steps are:
Let handles be a JSON List.
For each top-level browsing context in the remote end, push the associated window handle onto handles.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/frame |
The Switch To Frame command is used to select the current top-level browsing context or a child browsing context of the current browsing context to use as the current browsing context for subsequent commands.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let id be the result of
getting a property named "id
" from the parameters argument.
Run the substeps of the first matching condition:
Set the current browsing context to the current top-level browsing context.
Number
object
If id is less than 0 or greater than 216 – 1, return error with error code no such frame.
Let window be the associated window of the current browsing context’s active document.
If id is not a supported property index of window, return error with error code no such frame.
Let child window be the WindowProxy
object obtained by determining the value of an indexed property of window with index id.
Set the current browsing context to new window’s browsing context.
Let element result be the result of getting a known element by UUID reference id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
If element is not a
or frame
element, return error with error code no such frame.
iframe
Set the current browsing context to element’s nested browsing context.
Return error with error code no such frame.
Return success with data null.
WebDriver is not bound by the same origin policy, so it is always possible to switch into child browsing contexts, even if they are different origin to the current browsing context.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/frame/parent |
The Switch to Parent Frame command sets the current browsing context for future commands to the parent of the current browsing context.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
If the current browsing context is not equal to the current top-level browsing context, set the current browsing context to the parent browsing context of the current browsing context.
Return success with data null.
WebDriver provides commands for interacting with the operating system window containing the current top-level browsing context. Because different operating system’s window managers provide different abilities, not all of the commands in this section can be supported by all remote ends. Where a command is not supported, an unsupported operation error is returned.
A top-level browsing context’s window rect is defined as a dictionary of the screenX, screenY,
width
and height
attributes of the WindowProxy
. Its JSON representation is the following:
x
WindowProxy
’s screenX attribute.
y
WindowProxy
’s screenY attribute.
width
Width of the top-level browsing context’s outer dimensions, including any browser chrome and externally drawn window decorations in CSS reference pixels.
height
Height of the top-level browsing context’s outer dimensions, including any browser chrome and externally drawn window decorations in CSS reference pixels.
In some user agents the operating system’s window dimensions including decorations, are provided by the proprietary window.outerWidth
and window.outerHeight
[DOM] properties.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/window/rect |
The Get Window Rect command returns the size and position on the screen of the operating system window corresponding to the current top-level browsing context.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Return success with the JSON serialization of the current top-level browsing context’s window rect.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window/Rect |
The Set Window Rect command alters the size and the position of the operating system window corresponding to the current top-level browsing context.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
If the remote end does not support the Set Window Rect command for the current top-level browsing context for any reason, return error with error code unsupported operation.
If the properties width
or height
or
x
or y
from the parameters are not integers, or less than 0 or greater than 264 – 1, return error with error code invalid argument.
Let width be the result of
getting a property named width
from the parameters argument, else let it be null
.
Let height be the result of
getting a property named height
from the parameters argument, else let it be null
.
Let x be the result of getting a property named y
from the parameters argument, else let it be null.
Let y be the result of getting a property named x
from the parameters argument, else let it be null.
If the top-level browsing context’s document hidden
attribute is true
run the implementation specific steps that will set the top-level browsing context document hidden
attribute to false
.
If width and height are not null:
Set the width, in CSS reference pixels, of the operating system window containing the current top-level browsing context, including any browser chrome and externally drawn window decorations to a value that is as close as possible to width.
Set the height, in CSS reference pixels, of the operating system window containing the current top-level browsing context, including any browser chrome and externally drawn window decorations to a value that is as close as possible to height.
If x and y are not null:
Run the implementation-specific steps to set the position of the operating system level window containing the current top-level browsing context to the position given by the x and y coordinates.
Return success with the JSON serialization of the current top-level browsing context’s window rect.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window/maximize |
The Maximize Window command invokes the window manager-specific “maximize” operation, if any, on the window containing the current top-level browsing context. This typically increases the window to the maximum available size without going full-screen.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
If the remote end does not support the Maximize Window command for the current top-level browsing context for any reason, return error with error code unsupported operation.
Run the implementation-specific steps to increase the dimensions of the operating system level window containing the current top-level browsing context to the maximum available size allowed by the window manager.
Return success with the JSON serialization of the current top-level browsing context’s window rect.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window/minimize |
The Minimize Window command invokes the window manager-specific “minimize” operation, if any, on the window containing the current top-level browsing context. This typically hides the window in the system tray.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
If the remote end does not support the Minimize Window command for the current top-level browsing context for any reason, return error with error code unsupported operation.
Run the implementation-specific steps to hide the current top-level browsing context from the visible screen.
Return success with the JSON serialization of the current top-level browsing context’s window rect.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window/fullscreen |
The Fullscreen Window command invokes the window manager-specific “full screen” operation, if any, on the window containing the current top-level browsing context. This typically increases the window to the size of the physical display and can hide browser chrome elements such as toolbars.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
If the remote end does not support fullscreen return error with error code unsupported operation.
Call fullscreen an element with the current top-level browsing context’s active document’s document element.
Return success with the JSON serialization of the current top-level browsing context’s window rect.
A web element is an abstraction used to identify an element when it is transported across the protocol, between remote- and local ends.
The web element identifier is a constant with the string "element-6066-11e4-a52e-4f735466cecf
".
Each element has an associated web element reference (a UUID) that uniquely identifies the element across all browsing contexts. The web element reference for every element representing the same element is the same.
An ECMAScript Object represents a web element if it has a web element identifier own property holding a UUID value.
Each browsing context has an associated list of known elements. When the browsing context is discarded, the list of known elements is discarded along with it.
To get a known element by a UUID reference, return success with the known element which web element reference matches reference. If there are none, return error with error code no such element.
To create a web element reference for an element:
For each known element of the current browsing context’s known elements:
If known element equals element, return success with known element’s web element reference.
Let new reference be the result of generating a UUID.
Set element’s web element reference to new reference.
Append element to the known elements of the current browsing context.
Return success with data element’s web element reference.
The JSON Serialization of an element is a JSON Object where the web element identifier key is mapped to the element’s web element reference.
When required to deserialise a web element by a JSON Object object that represents a web element:
If object has no own property web element identifier, return error with error code invalid argument.
Let reference be the result of getting the web element identifier property from object.
Let element result be the result of getting a known element by UUID reference.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
Return success with data element.
A stale element is a reference to a node that has been disconnected from the current browsing context’s DOM. To determine if an element is stale, run the following substeps:
Let document be the current browsing context’s document element.
If element is not in the same tree as document, return true.
Otherwise return false.
An element is
scrolled into view by calling scrollIntoView with the ScrollIntoViewOptions
{block: "end", inline: "nearest"}
.
An element is considered editable if one or more of the following conditions are met:
element is an input
element for which hasAttribute
"checked"
is false
and for which the input
event applies.
element is a textarea
element.
element is content editable.
An element is said to have pointer events disabled if the resolved value of its "pointer-events
" style property is "none
".
An element is to be considered read only if it is an input
element whose readOnly
attribute is set.
In order to determine if an element can be interacted with using pointer actions, WebDriver performs hit-testing to find if the interaction will be able to reach the requested element.
An interactable element is an element which is either pointer-interactable or keyboard-interactable.
A pointer-interactable element is defined to be the first non-transparent element, defined by the paint order found at the centre point of its rectangle that is inside the viewport, excluding the size of any rendered scrollbars.
A keyboard-interactable
element is defined to be any element that has a focusable area, or is the body
element. In the case of the body
element all keyboard interactions must be targeted to its ownerDocument
.
An element’s in-view centre point is the centre point of the area of the first DOM client rectangle that is inside the viewport. It can be calculated this way, given an element, here called rectangle, off a
sequence:
DOMRect
Let rectangle be the first element of the
sequence returned by calling getClientRects on element.
DOMRect
Let left be (max(0, min(x coordinate, x coordinate + width dimension))).
Let right be (min(innerWidth, max(x coordinate, x coordinate + width dimension))).
Let top be (max(0, min(y coordinate, y coordinate + width dimension))).
Let bottom be (min(innerHeight, max(y coordinate, y coordinate + height dimension))).
Let x be (0.5 × (left + right).
Let y be (0.5 × (top + bottom).
Return x and y as a pair.
In order to produce a pointer-interactable elements tree from an element:
If element is not in the same tree as the current browsing context’s active document, return an empty sequence.
Let rectangles be the
sequence returned by calling getClientRects on element.
DOMRect
If rectangles has the length of 0, return an empty sequence.
Let centre point be the in-view centre point of element given the first indexed element of rectangles.
Return the elements from point given the coordinates centre point.
To get the first pointer-interactable element given a pointer-interactable elements tree, return with success the first element which style property opacity
has the computed value of "1"; otherwise return an error.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/active |
Get Active Element returns the active element of the current browsing context’s document element.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let active element be the active element of the current browsing context’s document element.
Let active web element be the JSON Serialization of active element.
Return success with data active web element.
The Find Element, Find Elements, Find Element From Element, and Find Elements From Element commands allow lookup of individual elements and collections of elements. Element retrieval searches are performed using pre-order traversal of the document’s nodes that match the provided selector’s expression. Elements are serialised and returned as web elements.
When required to find with arguments start node, using and value, a remote end must run the following steps:
Let end time be the current time plus the session implicit wait timeout.
Let location strategy be equal to using.
Let selector be equal to value.
Let result be an empty JSON List.
Let elements returned be the result of the relevant element location strategy call with arguments start node, and selector.
DOMException
, SyntaxError
,
XPathException
, or other error occurs during the execution of the element
location stratgey, return error invalid selector.
If elements returned is empty and the current time is less than end time return to step 5. Otherwise, continue to the next step.
Let result be an empty JSON List.
For each element in elements returned:
Append to result the JSON Serialization of the element.
Return result.
An element location strategy is an enumerated attribute deciding what technique should be used to search for elements in the current browsing context. The following table lists the keywords and states defined for this attribute:
State | Keyword |
---|---|
CSS selector | "css selector "
|
Link text selector | "link text "
|
Partial link text selector | "partial link text "
|
Tag name | "tag name "
|
XPath selector | "xpath "
|
To find a web element with the CSS Selector strategy the following steps need to be completed:
Return elements.
To find a web element with the Link Text strategy the following steps need to be completed:
Let elements be the result of calling querySelectorAll, with argument a
elements, with the context object equal to the start node.
Let result be an empty NodeList.
For each element in elements:
Let rendered text be the value that would be returned via a call to Get Element Text for element.
Let trimmed text be the result of stripping leading and trailing whitespace from rendered text.
If trimmed text equals selector, append element to result.
Return result.
The Partial link text strategy is very similar to the Link Text strategy, but rather than matching the entire string, only a substring needs to match. That is, return all a
elements with rendered text that contains the selector expression.
To find a web element with the Partial Link Text strategy the following steps need to be completed:
Let elements be the result of calling querySelectorAll, with argument a
elements, with the context object equal to the start node.
Let result be an empty NodeList.
For each element in elements:
Let rendered text be the value that would be returned via a call to Get Element Text for element.
If rendered text contains selector, append element to result.
Return result.
To find a web element with the Tag
Name strategy return the result of calling start
node's getElementsByTagName
with the argument selector.
To find a web element with the XPath Selector strategy the following steps need to be completed:
Return the result of calling
, with arguments selector, context object equal to the start node.
evaluate
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element |
The Find Element command is used to find an element in the current browsing context that can be used for future commands.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Let start node be the current browsing context’s document element.
Let location strategy be the result of getting a property called "using
".
If location strategy is undefined, return error with error code invalid argument.
Let selector be the result of getting a property called "value
".
If selector is undefined, return error with error code invalid argument.
Let result be the result of Find with start node, location strategy, and selector.
If result is empty, return error with error code no such element. Otherwise, return the first element of result.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/elements |
The Find Elements command is used to find elements in the current browsing context that can be used for future commands.
If the current browsing context is no longer open, return error with error code no such window.
Let start node be the current browsing context’s document element.
Let location strategy be the result of getting a property called "using
".
If location strategy is undefined, return error with error code invalid argument.
Let selector be the result of getting a property called "value
".
If selector is undefined, return error with error code invalid argument.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/element |
The Find Element From Element command is used to find an element from a web element in the current browsing context that can be used for future commands.
If the current browsing context is no longer open, return error with error code no such window.
Let start node be the result of getting a known element by UUID reference.
Let location strategy be the result of getting a property called "using
".
If location strategy is undefined, return error with error code invalid argument.
Let selector be the result of getting a property called "value
".
If selector is undefined, return error with error code invalid argument.
If result is empty, return error with error code no such element. Otherwise, return the first element of result.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/elements |
The Find Elements From Element command is used to find elements from a web element in the current browsing context that can be used for future commands.
If the current browsing context is no longer open, return error with error code no such window.
Let start node be the result of getting a known element by UUID reference.
Let location strategy be the result of getting a property called "using
".
If location strategy is undefined, return error with error code invalid argument.
Let selector be the result of getting a property called "value
".
If selector is undefined, return error with error code invalid argument.
To calculate the absolute position of element:
Let x and y both be 0.
While element’s offsetParent is not null:
Set x to (x + element’s offsetLeft).
Set y to (y + element’s offsetTop).
Set element to element’s offsetParent.
Return a pair of (x, y).
When a node is said to be not in the same tree as another node, other, the following steps must be taken:
If the node’s ownerDocument attribute is not other, return true.
If the result of calling the node’s compareDocumentPosition with other as argument is DOCUMENT_POSITION_DISCONNECTED (1), return true.
Return false.
An element’s container is:
option
element in a valid element context
optgroup
element in a valid element context
The element’s element context, meaning its immediate parent node in reverse tree-order originating from element that is either a datalist
element or a select
element.
option
element in an invalid element context
The element does not have a container.
The container is the element itself.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/selected |
Is Element Selected determines if the referenced element is selected or not. This operation only makes sense on input
elements of the Checkbox- and Radio Button states, or option
elements.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
Let selected be the value corresponding to the first matching statement:
input
element
with a type
attribute
in the Checkbox- or Radio Button state
The result of element’s checkedness.
option
element
The result of element’s selectedness.
Return success with data selected.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/attribute/{name} |
The Get Element Attribute command will return the attribute of a web element.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
If name is undefined, return error with error code invalid argument.
"true
" (string) if the element has the attribute, otherwise null.
The result of getting an attribute by name name.
Return success with data result.
Please note that the behaviour of this command deviates from the behaviour of getAttribute in [DOM], which in the case of a set boolean attribute would return an empty string. The reason this command returns true as a string is because this evaluates to true in most dynamically typed programming languages, but still preserves the expected type information.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/property/{name} |
The Get Element Property command will return the result of getting a property of an element.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
Let property be the result of calling the [[GetProperty]] internal method of element with property name name.
Let result be the value of property if not undefined, or null.
Return success with data result.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/css/{property name} |
The Get Element CSS Value command retrieves the computed value of the given CSS property of the given web element.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID parameter element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
Let computed value be the computed value of parameter property name from element’s style declarations if the current browsing context’s
document type is not "xml
", else let it be "".
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/text |
The Get Element Text command intends to return an element’s text “as rendered”. This is equivalent to calling element.innerText
. An element’s rendered text is also used for locating a
elements by their
link text and partial link text.
For historical reasons, all user agents appear to have implemented different sets of heuristics for approximating what is considered rendered text. WebDriver relies on the unofficial draft of the innerText
specification, but please be aware that there may be compliance issues between different user agents for this command. It is expected that innerText
will land soon in HTML.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID parameter element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
Let rendered text be the result of getting innerText
of element.
Return success with data rendered text.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/name |
The Get Element Tag Name command returns the qualified tag name name of the given web element.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference parameter element id.
If element result is an error, return element result.
Let element be element result’s data.
If element is stale, return error with error code stale element reference.
Let qualified name be the result of getting element’s tagName content attribute.
Return success with data qualified name.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/rect |
The Get Element Rect command returns the dimensions and coordinates of the given web element. The returned value is a dictionary with the following members:
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference parameter element id.
If element result is an error, return element result.
Let element be element result’s data.
If the element is stale, return error with error code stale element reference.
Calculate the absolute position of element and let it be coordinates.
Let rect be element’s bounding rectangle.
Let body be a new JSON Object initialised with:
x
y
width
height
Return success with data body.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/enabled |
Is Element Enabled determines if the referenced element is enabled or not. This operation only makes sense on form controls.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference element id.
If element result is a success, let element be element result’s data.
Otherwise, return element result.
If element is stale, return error with error code stale element reference.
Let enabled be a boolean initially set to true if the current browsing context’s
document type is not "xml
".
Otherwise, let enabled to false and jump to the last step of this algorithm.
Set enabled to false if a form control is disabled.
Return success with data enabled.
The element interaction commands provide a high-level instruction set for manipulating form controls. Unlike Actions, they will implicitly scroll elements into view and check that it is an interactable element.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/click |
The Element Click command scrolls into view the element and clicks the in-view centre point. If the element is not pointer-interactable, an element not interactable error is returned.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Let element result be the result of getting a known element by UUID reference element id.
Let element be element result’s data if it is a success. Otherwise return element result.
If the element is an input
element in the file upload state or it does not have a container element, return error with error code invalid argument.
Scroll into view the element’s container element.
Wait in an implementation-specific way up to the session implicit wait timeout for the container to become pointer-interactable.
If element from point for the in-view centre point of element is not equal to the element’s container, return error with error code element click intercepted.
If element’s container is not pointer-interactable, return error with error code element not interactable.
Run the substeps of the first step that case-insensitively matches the element's tag name:
Matching on element:
option
element
with a multiple
attribute
Toggle element’s selectedness state.
option
element
Set element’s selectedness state to true.
Ensure all correct events are fired.
Run interaction steps on coordinate.
If the click causes navigation:
Run the post-navigation checks and return its value if it is an error.
Wait for navigation to complete and return its value if it is an error.
Note that one may not know if a click causes navigation. It is safe to run the post-navigation checks and waiting for the navigation to complete even though navigation did not occur.
Return success with data null.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/clear |
The Element Clear command
scrolls into view an editable element, or an input
element whose type
attribute is File and then attempts to clear its selected files or text content.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Let element result be the result of getting a known element by UUID reference element id.
Let element be element result’s data if it is a success. Otherwise return element result.
If element is not editable return an error with error code invalid element state.
Scroll into view the element.
Wait in an implementation-specific way up to the session implicit wait timeout for element to become interactable.
If element is not interactable, return error with error code element not interactable.
If element is disabled, read only, or has pointer events disabled, return error with error code invalid element state.
Return success with data null.
When required to clear a content editable element a remote end must run the following steps:
If element's innerHTML
IDL
attribute is an empty string do nothing and return.
Run the focusing steps for element.
Set element's innerHTML
IDL
attribute to an empty string.
Fire an input
event.
Run the unfocusing steps for the element.
When required to clear an editable element a remote end must run the following steps:
If element's value is an empty string do nothing and return.
Run the focusing steps for element.
Run element's reset algorithm.
Fire an input
event.
Run the unfocusing steps for the element.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/value |
The Element Send Keys command scrolls into view the form control element and then sends the provided keys to the element. In case the element is not keyboard-interactable, an element not interactable error is returned.
The key input state used for input by the command may be cleared mid-way through "typing" by sending the null key, which is "U+E000 (NULL)".
When required to clear the modifier key state with an argument of undo actions and keyboard a remote end must run the following steps:
If keyboard is not a key input source return an error with error code invalid argument.
For each action corresponding to an indexed property in undo actions:
If action is not an action object of type
"key"
and subtype
"keyUp"
return an error with error code invalid argument.
Dispatch a keyUp action with arguments action and keyboard's key input state.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts, and return its value if it is an error.
Let element result be the result of getting a known element by UUID reference element id.
Let element be element result’s data if it is a success. Otherwise return element result.
Wait in an implementation-specific way up to the session implicit wait timeout for element to become keyboard-interactable.
If element is not keyboard-interactable, return error with error code element not interactable.
Scroll into view the element.
If element is not the active element:
Run the focusing steps for the element.
Set the text insertion caret using set selection range with using current text length as the 2 parameters passed in.
Let text be the result of getting a property
text
from the parameters argument.
If text is not a string, return an error with error code invalid argument.
If element is an input
element whose
type
attribute is File:
Let files be the result of splitting text on the newline ('\n'
) character.
If files is of 0 length, return an error with error code invalid argument.
Let multiple equal the result of calling hasAttribute("multiple")
on element.
if multiple is false
and the length of files is not equal to 1 return an error with error code invalid argument.
Verify that each file given by the user exists. If any do not, return error with error code invalid argument.
Complete implementation specific steps equivalent to setting the
selected files on the input
. If multiple is true
files are be appended to element's selected files.
Fire an input
event.
Jump to the last step in this overall set of steps.
Let keyboard be a new key input source.
Let undo actions be an empty list.
For each grapheme cluster in text:
Let key to type be the result of processing keys with argument grapheme cluster.
Let keydown action be an action object constructed with arguments keyboard's id, "key"
, and "keyDown"
.
Set the value
property of keydown
action to key to type.
Dispatch a keyDown action with arguments keydown action and keyboard's key input state.
Let keyup action be a copy of keydown
action with the subtype property changed to "keyUp"
.
Run the substeps in the first matching statement:
Clear the modifier key state with arguments undo actions and keyboard. If an error is returned, return that error.
Remove keyboard from the current session's input state
Return success with data null.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/source |
The Get Page Source command returns a string serialisation of the DOM of the current browsing context active document.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts and return its value if it is an error.
Let source be the result returned from the
outerHTML
IDL Attribute of the document element of the current browsing context active document.
If source is null:
Let source be the result of serialising to string the the current browsing context active document.
Return success with data source.
When required to JSON deserialise with argument value, and optional argument seen, a remote end must run the following steps:
If seen was not provided, let seen be an empty set.
Jump to the first appropriate step below:
null
,
or has type Boolean,
Number
or String:
Return success with data value.
Return the deserialised web element from value.
Return the result of running the clone an object algorithm with arguments value and seen, and the JSON deserialise algorithm as the clone algorithm.
Return error with error code javascript error.
When required to make a JSON clone with argument value, a remote end must run the following steps:
Let seen be an empty set.
Return the result of calling the internal JSON clone algorithm with arguments value and seen.
When required to run the internal JSON clone algorithm with arguments value and seen, a remote end must return the value of the first matching statement, matching on value:
Success with data null.
Success with data value.
If the element is stale, return error with error code stale element reference.
Otherwise, return success with the JSON Serialization of the web element value.
WindowProxy
object
If the associated browsing context of the WindowProxy
object in value has been discarded, return error with error code stale element reference.
Otherwise return success with the JSON Serialization of value.
If value is in seen, return error with error code javascript error.
Add value to seen.
Produce the value of running the clone an object algorithm with arguments value and seen, and the internal JSON clone algorithm as the clone algorithm.
Error with error code javascript error.
When required to clone an object with arguments value and seen and clone algorithm, run the following steps:
Let result be the value of the first matching statement, matching on value:
NodeList
HTMLCollection
Array
A new Array
object, which length
property has the result of getting a property named "length
" from value.
A new Object object.
For each enumerable own property in value, run the following substeps:
Let name be the name of the property.
Let source property value be the result of getting a property named name from value. If doing so causes script to be run, and that script throws an exception, return error with error code javascript error.
Let cloned property result be the result of calling the clone algorithm with arguments source property value and seen.
If cloned property result is a success, set a property of result with name name and value equal to cloned property result’s data.
Otherwise, return cloned property result.
The steps for extracting the script arguments from a request are:
If the current browsing context is no longer open, return error with error code no such window.
Let script be the result of
getting a property named script
from the parameters argument.
If script is not a String, return error with error code invalid argument.
Let args be the result of
getting a property named args
from the parameters argument.
If args is not an Object or its [[Class]] internal property is not Array or Object, return error with error code invalid argument.
Let arguments be a List consisting of a json deserialization of each item in args with the order preserved.
Return success with data script and arguments.
The rules to execute a function body are as follows. The algorithm will return success with the JSON representation of the function’s return value, or an error if the evaluation of the function results in a JavaScript exception being thrown or at any point during its execution an unhandled user prompt appears.
If at any point during the algorithm a user prompt appears, the user prompt handler must be invoked. If its return value is an error, it must immediately return with that error and abort all subsequent substeps of this algorithm.
Let window be the associated window of the current browsing context’s active document.
Let environment settings be the environment settings object for window.
Let script environment be the script execution environment for JavaScript obtained from environment settings.
If body is not parsable as a FunctionBody or if parsing detects an early error, return error with error code javascript error.
If body begins with a directive prologue that contains a use strict directive then let strict be true, otherwise let strict be false.
Using the script execution environment script environment, let function be the result of calling create a function object with parameter list of an empty List, body body, scope of the global environment, and strict flag strict.
Let script be a new script.
Let script’s code entry-point be function.
Let script’s settings object object be script settings.
Invoke the [[Call]] internal method of function, providing window as the this value and parameters as the argument values. If doing so does not produce an exception, let result be success with data set to the return value from this function call. Otherwise let result be error with error code javascript error.
If result is an error, return result.
Otherwise let json data be a JSON clone of result’s data.
Return success with data json data.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/execute/sync |
The Execute Script command executes a JavaScript function in the context of the current browsing context and returns the return value of the function.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts, and return its value if it is an error.
Let script arguments be the result of extracting the script arguments from a request with argument parameters.
If script arguments is an error, return script arguments.
Let body and arguments be script arguments’ data.
Let result be the result of calling execute a function body, with arguments body and arguments.
Wait for execute a function body to return or for session script timeout milliseconds to expire, whichever happens sooner.
If the previous step completed due to the session script timeout being reached, return error with error code script timeout.
If result is an error, return result.
Otherwise let value be result’s data.
Return success with data value.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/execute/async |
The Execute Async Script command causes JavaScript to execute as an anonymous function. Unlike the Execute Script command, the result of the function is ignored. Instead an additional argument is provided as the final argument to the function. This is a function that, when called, returns its first argument as the response.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts, and return its value if it is an error.
Let script arguments be the result of extracting the script arguments from a request with argument parameters.
If script arguments is an error, return script arguments.
Let body and arguments be script arguments’ data.
This next step might not quite set up all the right machinery.
Let webdriver callback result be a flag which can have three values:
unset
, expired
, or set
, with the set
value having associated data. Initially it is in the unset
state.
Let callback be a function whose [[Call]] internal method runs the execute async script callback algorithm initialized with argument webdriver callback result.
Append callback to arguments.
Let result be the result of calling execute a function body with arguments body and arguments.
If result is an error, return result.
Wait for webdriver callback result to enter the set
state, or for session script timeout milliseconds to expire, whichever happens sooner.
If the previous step completed due the session script timeout being reached, set webdriver callback result to expired
and return error with error code script timeout.
Otherwise, let result be webdriver callback result’s data.
If result is an error, return result.
Let value be result’s data.
Return success with data value.
The execute async script callback algorithm is initialized with a single argument webdriver callback state. It defines a function with a single optional argument result. When this function is called, the following steps are run:
If webdriver callback state is not in the unset
state, return undefined
.
If result is not present, let result be null
.
Let json result be a JSON clone of result.
Set the webdriver callback state to set
with data json result.
Return undefined
.
Expand these examples
The Actions API provides a low-level interface for providing virtualised device input to the web browser. Conceptually, the actions API divides time into a series of ticks. The local end sends a series of actions which correspond to the change in state, if any, of each input device during each tick. For example, pressing a key is represented by an action chain consisting of a single key input device and two ticks, the first containing a keyDown action, and the second a keyUp action, whereas a pinch-zoom input is represented by an action chain consisting of a three ticks and two pointer input devices of type touch, each performing a sequence of actions pointerDown, followed by pointerMove, and then pointerUp.
Move this note:
An input source is a virtual device providing input events. Each input source has an associated input id, which is a string that identifies the particular device, and a source type which determines the kind of input the device can provide. As with real devices, virtual devices are stateful; this state is recorded in an input device state object associated with each device.
A null input source is an input source that is not associated with a specific physical device. Null input sources support the following actions:
Action | Non-normative Description |
---|---|
pause | Used with an integer argument to specify the duration of a tick, or as a placeholder to indicate that an input source does nothing during a particular tick. |
A key input source is an input source that is associated with a keyboard-type device. A key input source supports the same pause action as a null input source plus the following actions:
Action | Non-normative Description |
---|---|
keyDown | Used to indicate that a particular key should be held down. |
keyUp | Used to indicate that a depressed key should be released. |
A pointer input source is an input source that is associated with a pointer-type input device. Such an input source has an associated subtype specifying exactly which kind of pointing device it is associated with. A pointer input source supports the same pause action as a null input source plus the following actions:
Action | Non-normative Description |
---|---|
pointerDown | Used to indicate that a pointer should be depressed in some way e.g. by holding a button down (for a mouse) or by coming into contact with the active surface (for a touch or pen device). |
pointerUp | Used to indicate that a pointer should be released in some way e.g. by releasing a mouse button or moving a pen or touch device away from the active surface. |
pointerMove | Used to indicate a location on the screen that a pointer should move to, either in its active (pressed) or inactive state. |
pointerCancel | Used to cancel a pointer action. |
A tick is the basic unit of time over which actions can be performed. During a tick, each input source has an assigned action — possibly a noop pause action — which may result in changes to the user agent internal state and eventually cause DOM events to be fired at the page. The next tick begins after the user agent has had a chance to process all DOM events generated in the current tick.
Waiting asynchronously means waiting for something to occur whilst allowing the browser to continue processing the event loop.
At the lowest level, the behaviour of actions is intended to mimic the remote end's behaviour with an actual input device as closely as possible, and the implementation strategy may involve e.g. injecting synthesized events into a browser event loop. Therefore the steps to dispatch an action will inevitably end up in implementation-specific territory. However there are certain content observable effects that must be consistent across implementations. To accomodate this, the specification requires that remote ends perform implementation-specific action dispatch steps, along with a list of events and their properties. This list is not comprehensive; in particular the default action of the input source may cause additional events to be generated depending on the implementation and the state of the browser (e.g. input events relating to key actions when the focus is on an editable element, scroll events, etc.).
The objects and properties defined in this section are spec-internal constructs and do not correspond to ECMAScript objects. For convenience the same terminology is used for their manipulation.
Each session has an associated input state table. This is a map between input id and the device state for that input source, with one entry for each active input source.
Each session also has an associated input cancel list, which is a list of actions. This list is used to manage dispatching events when resetting the state of the input sources. For simplicity the algorithms described here only append actions to the list and rely on the fact that the reset operations are idempotent.
A null input source has a corresponding null input state object. This is always an empty object.
A key input source has a corresponding key input
state object. This is an object with a property, pressed
, which is a set of strings representing currently pressed keys and properties alt
, shift
, ctrl
, and meta
, which are Booleans.
When required to create a new key input state
object, an implementation must return a key input
state object with the pressed
property set to the empty set and alt
, shift
, ctrl
, and meta
all set to false
.
A pointer input source has a corresponding pointer
input state object. This consists of a subtype
property, which has the possible values "mouse"
, "pen"
, and "touch"
, a primary
property which is a boolean, a pressed
property which is a set of unsigned integers, an x
property which is an unsigned integer, and a y
property which is an unsigned integer.
When required to create a new pointer input state object with arguments subtype and primary an implementation must return a pointer input state object with subtype
set to subtype, primary
set to primary, pressed
set to an empty set and both x
and y
set to 0
.
The corresponding input state type for a label action type is given by the following table:
Action type | Input state |
---|---|
"none "
|
null input state |
"key "
|
key input state |
"pointer "
|
pointer input state |
The algorithm for extracting an action chain from a request takes the JSON Object representing an action chain, validates the input, and returns a data structure that is the transpose of the input JSON, such that the actions to be performed in a single tick are grouped together.
When required to extract an action chain with argument parameters, a remote end must run the following steps:
If the current browsing context is no longer open, return error with error code no such window.
Let actions be the result of getting a property from parameters named actions
.
If actions is undefined or is not an Array, return error with error code invalid argument.
Let actions by tick be an empty List.
For each value action sequence corresponding to an indexed property in actions:
Let input source actions be the result of trying to process an input source action sequence with argument action sequence.
For each action in input source actions:
Return success with data actions by tick.
When required to process an input source action sequence, with argument action sequence, a remote end must run the following steps:
Let type be the result of getting a property named type
from actions sequence.
If type is not "key"
, "pointer"
, or "none"
, return an error with
error code invalid argument.
Let id be the result of getting a
property named id
from actions
sequence.
If id is undefined let id be a new UUID. Otherwise if id is not a String return error with error code invalid argument.
Let action items be the result of getting a property named actions
from action sequence.
If action items is not an Array, return error with error code invalid argument.
If type is equal to "pointer"
, let parameters data be the result of getting a property named parameters from action sequence. Then let parameters be the result of trying to process pointer
parameters with argument parameters
data.
If the current session's input state already has an entry corresponding to input id id and that entry has a type different to the corresponding input state type for type, then return error with error code invalid argument.
Let actions be a new list.
For each action item in action items:
If action item is not an Object return error with error code invalid argument.
If type is "none"
let action be the result of trying to process a null action with parameters id, and action item.
Otherwise, if type is "key"
let action be the result of trying to process a key action with parameters id, and action item.
Otherwise, if type is "pointer"
let action be the result of trying to process a pointer
action with parameters id, parameters, and action item.
Append action to actions.
Return success with data actions.
The default pointer parameters consist of an object with property pointerType
set to mouse
and primary
set to true
.
When required to process pointer parameters with argument parameters data, a remote end must perform the following steps:
Let parameters be the default pointer parameters.
If parameters data is undefined, return success with data parameters.
If parameters data is not an Object return error with error code invalid argument.
Let pointer type be the result of getting
a property named pointerType
from parameters data.
If pointer type is not undefined:
If pointer type does not have one of the values "mouse"
, "pen"
, or "touch"
return error with
error code invalid argument.
Set the pointerType
property of parameters to pointer type.
Let primary be the result of getting a property named primary
from parameters
data.
If primary is not undefined:
If primary is not a Boolean return error with error code invalid argument.
Set the primary
property of parameters to primary.
Return success with data parameters.
A action object constructed with arguments id, type, and subtype is an object with property id
set to id,
type
set to type and subtype
set to subtype. Specific action objects have further properties added by other algorithms in this specification.
When required to process a null action with arguments id and action item, a remote end must perform the following steps:
Let subtype be the result of getting a property named type
from action item.
If subtype is not "pause"
return error with error code invalid argument.
Let action be an action object constructed with arguments id,
"none"
, and subtype.
Let result be the result of trying to process a pause action with arguments action item, and action.
Return result.
When required to process a key action with arguments id and action item, a remote end must perform the following steps:
Let subtype be the result of getting a property named type
from action item.
If subtype is not one of the values "keyUp"
, "keyDown"
, or "pause"
, return an error with
error code invalid argument.
Let action be an action object constructed with arguments id,
"key"
, and subtype.
If subtype is "pause"
; let result be the result of trying to
process a pause action with arguments action
item, and action, and return
result.
Let key be the result of getting a property named value
from action item.
If key is not a String containing a single unicode code point or grapheme cluster? return error with error code invalid argument.
Set the value
property on action to key.
Return success with data action.
When required to process a pointer action with arguments id, parameters, and action item, a remote end must perform the following steps:
Let subtype be the result of getting a property named type
from action item.
If subtype is not one of the values pause
, "pointerUp"
,
"pointerDown"
, "pointerMove"
, or "pointerCancel"
return an error with
error code invalid argument.
If the current session's input state already has an entry corresponding to input
id id and that entry has a subtype
property with value different to subtype return error with
error code invalid argument.
Let action be an action object constructed with arguments id,
"pointer"
, and subtype.
If subtype is "pause"
; let result be the result of trying to
process a pause action with arguments action
item, and action, and return
result.
Set the pointerType
property of action equal to the pointerType
property of parameters.
Set the primary
property of action equal to the primary
property of parameters.
If subtype is "pointerUp"
or "pointerDown"
, process a pointer up or
pointer down action with arguments action
item, and action. If doing so results in an error, return that error.
If subtype is "pointerMove"
process a pointer move
action with arguments action item, and action. If doing so results in an error, return that error
If subtype is "pointerCancel"
process a
pointer cancel action. If doing so results in an
error, return that error
Return success with data action.
When required to process a pause action with arguments action item, and action, a remote end must run the following steps:
Let duration be the result of getting a property named duration
from action
item.
If duration is not undefined and duration is not an Integer greater than or equal to 0, return error with error code invalid argument.
Set the duration
property of action to duration.
Return success with data action.
When required to process a pointer up or pointer down action with arguments action item, and action, a remote end must run the following steps:
Let button be the result of getting a property named button
from action
item.
If button is not an Integer greater than or equal to 0 return error with error code invalid argument.
Set the button
property of action to button.
Return success with data null
When required to process a pointer move action with arguments action item, and action, a remote end must run the following steps:
Let duration be the result of getting a property named duration
from action
item.
If duration is not undefined and duration is not an Integer greater than or equal to 0, return error with error code invalid argument.
Set the duration
property of action to duration.
Let origin be the result of getting a property named origin
from action item.
If origin is undefined let
origin equal "viewport"
.
If origin is not equal to "viewport"
or
"pointer"
and origin is not an Object that represents a web element, return error with
error code invalid argument.
Set the origin
property of action to origin.
Let x be the result of getting a property named x
from action
item.
If x is not undefined or is not an Integer return error with error code invalid argument.
Set the x
property of action to x.
Let y be the result of getting a property named y
from action
item.
If y is not undefined or is not an Integer return error with error code invalid argument.
Set the y
property of action to y.
Return success with data null.
The algorithm to dispatch actions takes a list of actions grouped by tick, and then causes each action to be run at the appropriate point in the sequence.
When asked to dispatch actions with argument actions by tick, a remote end must run the following steps:
For each item tick actions in actions by tick:
Let tick duration be the result of computing the tick duration with argument tick actions.
Dispatch tick actions with arguments tick actions and tick duration. If this results in an error return that error.
Wait until the following conditions are all met:
There are no pending asynchronous waits arising from the last invocation of the dispatch tick actions steps.
The user agent event loop has spun enough times to process the DOM events generated by the last invocation of the dispatch tick actions steps.
At least tick duration milliseconds have passed.
Return success with data null.
When required to compute the tick duration with argument tick actions, a remote end must take the following steps:
Let max duration be 0.
For each action object in tick actions:
let duration be undefined.
If action object has subtype
property set to "pause"
or
action object has type
property set to "pointer"
and subtype
property set to "pointerMove"
, let duration be equal to the duration
property of action
object.
If duration is not undefined, and duration is greater than max duration let max duration be equal to duration.
Return max duration.
When required to dispatch tick actions with arguments tick actions and tick duration, a remote end must run the following steps:
For each action object in tick actions:
Let source id be equal to the value of action object's id
property.
Let source type be equal to the value of action object's type
property.
If the current session's input state doesn't have a property corresponding to source id, then let the property corresponding to source id be a new object of the corresponding input state type for source type.
Let device state be the device state corresponding to source id in the current session’s input state object.
Let algorithm be the value of the column
dispatch action algorithm from the following table of dispatch action algorithms that matches the
source type and the action object's
subtype
property, to a dispatch action algorithm.
source type | subtype property
|
Dispatch action algorithm |
---|---|---|
"none"
|
"pause"
|
Dispatch a pause action |
"key"
|
"pause"
|
Dispatch a pause action |
"key"
|
"keyDown"
|
Dispatch a keyDown action |
"key"
|
"keyUp"
|
Dispatch a keyUp action |
"pointer"
|
"pause"
|
Dispatch a pause action |
"pointer"
|
"pointerDown"
|
Dispatch a pointerDown action |
"pointer"
|
"pointerUp"
|
Dispatch a pointerUp action |
"pointer"
|
"pointerMove"
|
Dispatch a pointerMove action |
"pointer"
|
"pointerCancel"
|
Dispatch a pointerCancel action |
Return the result of running algorithm with arguments source id, action object, device state and tick duration
When required to dispatch a pause action with arguments source id, action object, input state and tick duration a remote end must run the following steps:
Return success with data null.
The normalised key value for a raw key key is, if key appears in the table below, the string value in the second column on the row containing key's unicode code point in the first column, otherwise it is key.
key's codepoint | Normalised key value |
---|---|
\uE000 |
"Unidentified" |
\uE001 |
"Cancel" |
\uE002 |
"Help" |
\uE003 |
"Backspace" |
\uE004 |
"Tab" |
\uE005 |
"Clear" |
\uE006 |
"Return" |
\uE007 |
"Enter" |
\uE008 |
"Shift" |
\uE009 |
"Control" |
\uE00A |
"Alt" |
\uE00B |
"Pause" |
\uE00C |
"Escape" |
\uE00D |
" " |
\uE00E |
"PageUp" |
\uE00F |
"PageDown" |
\uE010 |
"End" |
\uE011 |
"Home" |
\uE012 |
"ArrowLeft" |
\uE013 |
"ArrowUp" |
\uE014 |
"ArrowRight" |
\uE015 |
"ArrowDown" |
\uE016 |
"Insert" |
\uE017 |
"Delete" |
\uE018 |
";" |
\uE019 |
"=" |
\uE01A |
"0" |
\uE01B |
"1" |
\uE01C |
"2" |
\uE01D |
"3" |
\uE01E |
"4" |
\uE01F |
"5" |
\uE020 |
"6" |
\uE021 |
"7" |
\uE022 |
"8" |
\uE023 |
"9" |
\uE024 |
"*" |
\uE025 |
"+" |
\uE026 |
"," |
\uE027 |
"-" |
\uE028 |
"." |
\uE029 |
"/" |
\uE031 |
"F1" |
\uE032 |
"F2" |
\uE033 |
"F3" |
\uE034 |
"F4" |
\uE035 |
"F5" |
\uE036 |
"F6" |
\uE037 |
"F7" |
\uE038 |
"F8" |
\uE039 |
"F9" |
\uE03A |
"F10" |
\uE03B |
"F11" |
\uE03C |
"F12" |
\uE03D |
"Meta" |
\uE040 |
"ZenkakuHankaku" |
\uE050 |
"Shift" |
\uE051 |
"Control" |
\uE052 |
"Alt" |
\uE053 |
"Meta" |
\uE054 |
"PageUp" |
\uE055 |
"PageDown" |
\uE056 |
"End" |
\uE057 |
"Home" |
\uE058 |
"ArrowLeft" |
\uE059 |
"ArrowUp" |
\uE05A |
"ArrowRight" |
\uE05B |
"ArrowDown" |
\uE05C |
"Insert" |
\uE05D |
"Delete" |
The code for key is the value in the last column of the following table on the row with key in either the first or second column, if any such row exists, otherwise it is undefined
.
Key | Alternate Key | code |
---|---|---|
"`" |
"~" |
"Backquote" |
"\" |
"|" |
"Backslash" |
"\uE003" |
|
"Backspace" |
"[" |
"{" |
"BracketLeft" |
"}" |
"]" |
"BracketRight" |
"," |
"<" |
"Comma" |
"0" |
")" |
"Digit0" |
"1" |
"!" |
"Digit1" |
"2" |
"@" |
"Digit2" |
"3" |
"#" |
"Digit3" |
"4" |
"$" |
"Digit4" |
"5" |
"%" |
"Digit5" |
"6" |
"^" |
"Digit6" |
"7" |
"&" |
"Digit7" |
"8" |
"*" |
"Digit8" |
"9" |
"(" |
"Digit9" |
"=" |
"+" |
"Equal" |
"<" |
">" |
"IntlBackslash" |
"a" |
"A" |
"KeyA" |
"b" |
"B" |
"KeyB" |
"c" |
"C" |
"KeyC" |
"d" |
"D" |
"KeyD" |
"e" |
"E" |
"KeyE" |
"f" |
"F" |
"KeyF" |
"g" |
"G" |
"KeyG" |
"h" |
"H" |
"KeyH" |
"i" |
"I" |
"KeyI" |
"j" |
"J" |
"KeyJ" |
"k" |
"K" |
"KeyK" |
"l" |
"L" |
"KeyL" |
"m" |
"M" |
"KeyM" |
"n" |
"N" |
"KeyN" |
"o" |
"O" |
"KeyO" |
"p" |
"P" |
"KeyP" |
"q" |
"Q" |
"KeyQ" |
"r" |
"R" |
"KeyR" |
"s" |
"S" |
"KeyS" |
"t" |
"T" |
"KeyT" |
"u" |
"U" |
"KeyU" |
"v" |
"V" |
"KeyV" |
"w" |
"W" |
"KeyW" |
"x" |
"X" |
"KeyX" |
"y" |
"Y" |
"KeyY" |
"z" |
"Z" |
"KeyZ" |
"-" |
"_" |
"Minus" |
"." |
">" |
"Period" |
"'" |
""" |
"Quote" |
";" |
":" |
"Semicolon" |
"/" |
"?" |
"Slash" |
"\uE00A" |
|
"AltLeft" |
"\uE052" |
|
"AltRight" |
"\uE009" |
|
"ControlLeft" |
"\uE051" |
|
"ControlRight" |
"\uE006" |
|
"Enter" |
"\uE03D" |
|
"OSLeft" |
"\uE053" |
|
"OSRight" |
"\uE008" |
|
"ShiftLeft" |
"\uE050" |
|
"ShiftRight" |
" " |
"\uE00D" |
"Space" |
"\uE004" |
|
"Tab" |
"\uE017" |
|
"Delete" |
"\uE010" |
|
"End" |
"\uE002" |
|
"Help" |
"\uE011" |
|
"Home" |
"\uE016" |
|
"Insert" |
"\uE01E" |
|
"PageDown" |
"\uE01F" |
|
"PageUp" |
"\uE015" |
|
"ArrowDown" |
"\uE012" |
|
"ArrowLeft" |
"\uE014" |
|
"ArrowRight" |
"\uE013" |
|
"ArrowUp" |
"\uE00C" |
|
"Escape" |
"\uE031" |
|
"F1" |
"\uE032" |
|
"F2" |
"\uE033" |
|
"F3" |
"\uE034" |
|
"F4" |
"\uE035" |
|
"F5" |
"\uE036" |
|
"F6" |
"\uE037" |
|
"F7" |
"\uE038" |
|
"F8" |
"\uE039" |
|
"F9" |
"\uE03A" |
|
"F10" |
"\uE03B" |
|
"F11" |
"\uE03C" |
|
"F12" |
"\uE01A" |
"\uE05C" |
"Numpad0" |
"\uE01B" |
"\uE056" |
"Numpad1" |
"\uE01C" |
"\uE05B" |
"Numpad2" |
"\uE01D" |
"\uE055" |
"Numpad3" |
"\uE01E" |
"\uE058" |
"Numpad4" |
"\uE01F" |
|
"Numpad5" |
"\uE020" |
"\uE05A" |
"Numpad6" |
"\uE021" |
"\uE057" |
"Numpad7" |
"\uE022" |
"\uE059" |
"Numpad8" |
"\uE023" |
"\uE054" |
"Numpad9" |
"\uE024" |
|
"NumpadAdd" |
"\uE026" |
|
"NumpadComma" |
"\uE028" |
"\uE05D" |
"NumpadDecimal" |
"\uE029" |
|
"NumpadDivide" |
"\uE007" |
|
"NumpadEnter" |
"\uE024" |
|
"NumpadMultiply" |
"\uE026" |
|
"NumpadSubtract" |
The key location for key is the value in the last column in the table below on the row with key appears in the first column, if such a row exists, otherwise it is 0
.
key's codepoint | Description | Location |
---|---|---|
\uE007 |
Enter | 1 |
\uE008 |
Left Shift | 1 |
\uE009 |
Left Control | 1 |
\uE00A |
Left Alt | 1 |
\uE01A |
Numpad 0 | 3 |
\uE01B |
Numpad 1 | 3 |
\uE01C |
Numpad 2 | 3 |
\uE01D |
Numpad 3 | 3 |
\uE01E |
Numpad 4 | 3 |
\uE01F |
Numpad 5 | 3 |
\uE020 |
Numpad 6 | 3 |
\uE021 |
Numpad 7 | 3 |
\uE022 |
Numpad 8 | 3 |
\uE023 |
Numpad 9 | 3 |
\uE024 |
Numpad * | 3 |
\uE025 |
Numpad + | 3 |
\uE026 |
Numpad , | 3 |
\uE027 |
Numpad - | 3 |
\uE028 |
Numpad . | 3 |
\uE029 |
Numpad / | 3 |
\uE03D |
Left Meta | 1 |
\uE050 |
Right Shift | 2 |
\uE051 |
Right Control | 2 |
\uE052 |
Right Alt | 2 |
\uE053 |
Right Meta | 2 |
\uE054 |
Numpad PageUp | 3 |
\uE055 |
Numpad PageDown | 3 |
\uE056 |
Numpad End | 3 |
\uE057 |
Numpad Home | 3 |
\uE058 |
Numpad ArrowLeft | 3 |
\uE059 |
Numpad ArrowUp | 3 |
\uE05A |
Numpad ArrowRight | 3 |
\uE05B |
Numpad ArrowDown | 3 |
\uE05C |
Numpad Insert | 3 |
\uE05D |
Numpad Delete | 3 |
When required to dispatch a keyDown action with arguments action object and input state a remote end must run the following steps:
Let raw key be equal to action
object's value
property.
Let key be equal to the normalised key value for raw key.
If the input state's pressed
property contains key, let repeat be true, otherwise let repeat be false.
Let code be the code for raw key.
Let location be the key location for raw key.
Let charCode, keyCode and which be the implementation-specific values of the charCode
, keyCode
and which
properties appropriate for a key with key key and location location on a 102 key US keyboard, following the guidelines in [UI-EVENTS].
If key is "Alt"
, let device state's alt
property be true.
If key is "Shift"
, let device state's shift
property be true.
If key is "Control"
, let device state's ctrl
property be true.
If key is "Meta"
, let device state's meta
property be true.
Add key to the set corresponding to input state's pressed
property.
Append a copy of action object with the subtype property changed to keyUp to current session's input cancel list.
Perform
implementation-specific action dispatch steps equivalent to pressing a key on the keyboard in accordance with the requirements of [UI-EVENTS], and producing the following events, as appropriate, with the specified properties. This will always produce events including at least a keyDown
event.
keyDown
with properties:
Attribute | Value |
---|---|
key |
key |
code |
code |
location |
location |
altKey |
device
state's alt property
|
shiftKey |
device
state's shift property
|
ctrlKey |
device
state's ctrl property
|
metaKey |
device
state's meta property
|
repeat |
repeat |
isComposing |
false |
charCode |
charCode |
keyCode |
keyCode |
which |
which |
keyPress
, with properties:
Attribute | Value |
---|---|
key |
key |
code |
code |
location |
location |
altKey |
device
state's alt property
|
shiftKey |
device
state's shift property
|
ctrlKey |
device
state's ctrl property
|
metaKey |
device
state's meta property
|
repeat |
repeat |
isComposing |
false |
charCode |
charCode |
keyCode |
keyCode |
which |
which |
Return success with data null.
When required to dispatch a keyUp action with arguments action object and input state a remote end must run the following steps:
Let raw key be equal to action
object's value
property.
Let key be equal to the normalised key value for raw key.
If the input state's pressed
property does not contain key, return.
Let code be the code for raw key.
Let location be the key location for raw key.
Let charCode, keyCode and which be the implementation-specific values of the charCode
, keyCode
and which
properties appropriate for a key with key key and location location on a 102 key US keyboard, following the guidelines in [
UI-EVENTS].
If key is "Alt"
, let device state's alt
property be false.
If key is "Shift"
, let device state's shift
property be false.
If key is "Control"
, let device state's ctrl
property be false.
If key is "Meta"
, let device state's meta
property be false.
Remove key from the set corresponding to input state's pressed
property.
Perform implementation-specific action dispatch steps equivalent to releasing a key on the keyboard in accordance with the requirements of [UI-EVENTS], and producing at least the following events with the specified properties:
keyup
, with properties:
Attribute | Value |
---|---|
key |
key |
code |
code |
location |
location |
altKey |
device
state's alt property |
shiftKey |
device
state's shift property |
ctrlKey |
device
state's ctrl property |
metaKey |
device
state's meta property |
repeat |
false |
isComposing |
false |
charCode |
charCode |
keyCode |
keyCode |
which |
which |
Return success with data null.
When required to get a global key state with argument key, a remote end must run the following steps:
pressed
property contains key return true.
Return false.
When required to dispatch a pointerDown action with arguments source id, action object, input state and tick duration a remote end must run the following steps:
Let pointerType be equal to action
object's pointerType
property.
Let button be equal to action
object's button
property.
If the input state's pressed
property contains button return success with data null.
Let primary be equal to action object's
primary
property.
Let x be equal to input state's
x
property.
Let y be equal to input state's
y
property.
Add button to the set corresponding to input state's pressed
property, and let buttons be the resulting value of that property.
Append a copy of action object with the subtype property changed to pointerUp to the current session's input cancel list.
Perform implementation-specific action dispatch steps equivalent to pressing the button numbered button on the pointer with ID source id, having type type pointerType at viewport x coordinate x, viewport y coordinate y, with buttons buttons depressed, in accordance with the requirements of [ UI-EVENTS] and [POINTER-EVENTS], with primary determining whether the pointer is regarded as a primary pointer and thus generates legacy mouse events. Type specific properties for the pointer that are not exposed through the webdriver API must be set to the default value specified for hardware that doesn't support that property.
Return success with data null.
When required to dispatch a pointerUp action with arguments source id, action object, input state and tick duration a remote end must run the following steps:
Let pointerType be equal to action
object's pointerType
property.
Let button be equal to action
object's button
property.
If the input state's pressed
property does not contain button return success with data null.
Let primary be equal to action object's
primary
property.
Let x be equal to action object's
x
property.
Let y be equal to action object's
y
property.
Let alt be the result of getting a
global key pressed state with argument "Alt"
.
If key is "Shift"
, let device state's shift
property be true.
If key is "Control"
, let device state's ctrl
property be true.
If key is "Meta"
, let device state's meta
property be true.
Remove button from the set corresponding to input state's pressed
property, and let buttons be the resulting value of that property.
Perform implementation-specific action dispatch steps equivalent to releasing the button numbered button on the pointer of ID source id having type type pointerType at viewport x coordinate x, viewport y coordinate y, with buttons buttons depressed, in accordance with the requirements of [ UI-EVENTS] and [POINTER-EVENTS], with primary determining whether the pointer is regarded as a primary pointer and thus generates legacy mouse events. Type specific properties for the pointer that are not exposed through the webdriver API must be set to the default value specified for hardware that doesn't support that property.
Return success with data null.
When required to dispatch a pointerMove action with arguments source id, action object, input state and tick duration a remote end must run the following steps:
Let x offset be equal to the x
property of action object.
Let y offset be equal to the y
property of action object.
Let start x be equal to the x
property of input state.
Let start y be equal to the y
property of input state.
Let origin be equal to the origin
property of action
object.
Run the substeps of the first matching value of origin:
"viewport"
Let x equal x offset and y equal y offset.
"pointer"
Let x equal start x + x offset and y equal start y + y offset.
Let element be equal to the result of trying to get a known element with argument origin.
Let x element and y element be the result of calculating the in-view centre point of element.
Let x equal x element + x offset, and y equal y element + y offset.
If x is less than 0 or greater than the width of the viewport in CSS reference pixels, then return error with error code move target out of bounds.
If y is less than 0 or greater than the height of the viewport in CSS reference pixels, then return error with error code move target out of bounds.
Let duration be equal to action
object's duration
property if it is not undefined
, or tick duration otherwise.
If duration is greater than 0 and inside any implementation-defined bounds, asynchronously wait for an implementation defined amount of time to pass.
Perform a pointer move with arguments source id, input state, duration, start x, start y, x, y.
When required to perform a pointer move with arguments source id, input state, duration, start x, start y, target x and target y, an implementation must run the following steps:
Let subtype equal the subtype
property of input state.
Let time delta be the time since the beginning of the current tick, measured in milliseconds on a monotonic clock.
Let duration ratio be the ratio of time deta and duration, if duration is greater than 0, or 1 otherwise.
If duration ratio is 1, or close enough to 1 that the implementation will not further subdivide the move action, let last be true. Otherwise let last be false
.
If last is true, let x equal target x and y equal target y.
Otherwise let x equal an approximation to duration ratio × (target x - start x) + start x, and y equal an approximation to duration ratio × (target y - start y) + start y.
Let current x equal the x
property of input state.
Let current y equal the y
property of input state.
If x is not equal to current x or y is not equal to current y, run the following steps:
Let buttons be equal to input state's buttons
property.
Perform
implementation-specific action dispatch steps equivalent to moving the pointer with ID source id having type pointerType from viewport x coordinate current x, viewport y coordinate y to viewport x coordinate x and viewport y coordinate y, with buttons buttons depressed, in accordance with the requirements of [UI-EVENTS] and [POINTER-EVENTS], with primary determining whether the pointer is regarded as a primary pointer and thus generates legacy mouse events. Type specific properties for the pointer that are not exposed through the WebDriver API must be set to the default value specified for hardware that doesn't support that property. In the case where the pointerType is "pen"
or "touch"
, and buttons is empty, this may be a no-op. For a pointer of type "mouse"
, this will always produce events including at least a pointerMove
event.
Let input state's x
property equal x and y
property equal y.
If last is true, return.
Asynchronously wait for an implementation defined amount of time to pass.
Perform a pointer move with arguments source id, input state, duration, start x, start y, target x, target y.
When required to dispatch a pointerCancel action with arguments source id, action object, input state and tick duration a remote end must run the following steps:
Perform implementation-specific action dispatch steps equivalent to cancelling the any action of the pointer with ID source id having type pointerType, in accordance with the requirements of [UI-EVENTS] and [ POINTER-EVENTS].
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/actions |
This section is non-normative.
The remote end steps are:
If the current browsing context is no longer open, return error with error code no such window.
Handle any user prompts. If this results in an error, return that error.
Let actions by tick be the result of trying to extract an action chain with argument parameters.
Dispatch actions with argument actions by tick. If this results in an error return that error.
Return success with data null.
HTTP Method | Path Template |
---|---|
DELETE | /session/{session id}/actions |
The Release Actions command is used to release all the keys and pointer buttons that are currently depressed. This causes events to be fired as if the state was released by an explicit series of actions. It also clears all the internal state of the virtual devices.
The remote end steps are:
Let undo actions be equal to the current session's input cancel list in reverse order.
Dispatch tick actions with arguments undo actions and duration 0.
Let the current session's input cancel list be an empty List.
Let the current session's input state be an empty map.
Return success with data null.
This section is non-normative
This chapter describes interaction with various types of user prompts. The common denominator for user prompts is that they are modal windows requiring users to interact with them before the event loop is unpaused and control is returned to the current top-level browsing context.
By default user prompts are not handled automatically unless a user prompt handler has been defined. When a user prompt appears, it is the task of the subsequent command to handle it. If the subsequent requested command is not one listed in this chapter, an unexpected alert open error will be returned.
User prompts that are spawned from beforeunload
event handlers, are dismissed implicitly upon navigation, regardless of the defined user prompt handler.
The following table of simple dialogs enumerates all supported simple dialogs, along with the commands that are allowed to interact with it as a non-normative reference:
Definition | Dialog | Interactions |
---|---|---|
Alert | window.alert
|
Accept Alert Dismiss Alert Get Alert Text |
Confirm | window.confirm
|
Dismiss Alert Accept Alert Get Alert Text |
Prompt | window.prompt
|
Dismiss Alert Accept Alert Get Alert Text Send Alert Text |
The current user prompt is said to be the active user prompt, which can be one of the entries on the table of simple dialogs, the window.print
dialog, or a dialog spawned by showModalDialog()
should this be supported by the user agent.
To dismiss the current user prompt, do so as if the user would click the Cancel or OK button, whichever is present, in that order.
To accept the current user prompt, do so as if the user would click the OK button.
A user prompt handler is an enumerated attribute defining what action the remote end must take when a user prompt is encountered. This is defined by the unexpected alert behaviour capability. The following table lists the keywords and states for the attribute:
Keyword | State | Description |
---|---|---|
"dismiss "
|
Dismiss state | All simple dialogs encountered should be dismissed. |
"accept "
|
Accept state | All simple dialogs encountered should be accepted. |
In order to handle any user prompts a remote end must take the following steps:
If there is no current user prompt, abort these steps and return success.
Run the substeps of the first matching user prompt handler:
Return error with error code unexpected alert open.
Return success.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/alert/dismiss |
The Dismiss Alert command dismisses a simple dialog if present. A request to dismiss an alert user prompt, which may not necessarily have a dismiss button, has the same effect as accepting it.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
If there is no current user prompt, return error with error code no such alert.
Return success with data null.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/alert/accept |
The Accept Alert command accepts a simple dialog if present.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
If there is no current user prompt, return error with error code no such alert.
Return success with data null.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/alert/text |
The Get Alert Text command returns the message of the current user prompt. If there is no current user prompt, it returns with null.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
If there is no current user prompt, return error with error code no such alert.
Let message be the text message associated with the current user prompt, or otherwise be null.
Return success with data message.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/alert/text |
The Send Alert Text command sets the text field prompt to a given value, and only makes sense on window.prompt
.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
If there is no current user prompt, return error with error code no such alert.
Run the substeps of the first matching current user prompt:
Return error with error code element not interactable.
Do nothing.
Return error with error code unsupported operation.
Let character array be the result of
getting a property value
from the parameters argument.
Let text be the result of joining together each item in character array to a string.
Set the current user prompt’s text field value to the value of text.
Return success with data null.
Screenshots are a mechanism for providing additional visual diagnostic information. They work by dumping a snapshot of the initial viewport’s framebuffer as a lossless PNG image. It is returned to the local end as a Base64 encoded string.
WebDriver provides the Take Screenshot command to capture the top-level browsing context’s initial viewport, and a command Take Element Screenshot for doing the same with the visible region of an element’s bounding rectangle after it has been scrolled into view.
In order to draw a bounding box from the framebuffer, given a rectangle:
If either the initial viewport’s width or height is 0 CSS reference pixels, return error with error code unable to capture screen.
Let paint width be the initial viewport’s width – min(rectangle x coordinate, rectangle x coordinate + rectangle width dimension).
Let paint height be the initial viewport’s height – min(rectangle y coordinate, rectangle y coordinate + rectangle height dimension).
Let canvas be a new canvas
element, and set its width and height to paint width and paint height, respectively.
Let context, a canvas context mode, be the result of invoking the 2D context creation algorithm given canvas as the target.
Complete implementation specific steps equivalent to drawing the region of the framebuffer specified by the following coordinates onto context:
Return success with canvas.
To encode as Base64
a canvas
element:
If the canvas
element’s bitmap’s
origin-clean flag is set to false, return error with error code unable to capture screen.
If the canvas
element’s bitmap has no pixels (i.e. either its horizontal dimension or vertical dimension is zero) then return error with error code unable to capture screen.
Let file be
a serialisation of the canvas
element’s bitmap as a file, using "image/png
" as an argument.
Let index be the index of ",
" in data url.
Let encoded string be a substring of data url using (index + 1) as the start argument.
Return success with data encoded string.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/screenshot |
The Take Screenshot command takes a screenshot of the top-level browsing context’s viewport.
The remote end steps are:
If the current top-level browsing context is no longer open, return error with error code no such window.
Let screenshot result be the result of calling draw a bounding box from the framebuffer, given root rect as an argument.
If screenshot result is an error, return screenshot result.
Let canvas be a canvas
element of screenshot result’s data.
Let encoding result be the result of encoding as Base64 canvas.
If encoding result is an error, return encoding result.
Let encoded string be encoding result’s data.
Return success with data encoded string.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/screenshot |
The Take Element Screenshot command takes a screenshot of the visible region encompassed by the bounding rectangle of an element. If given a parameter argument scroll
that evaluates to false, the element will not be scrolled into view.
If the current browsing context is no longer open, return error with error code no such window.
Let scroll be true if it is undefined.
Let element result be the result of getting a known element by UUID reference parameter element id.
If element result is an error, return element result.
Let element be element result’s data.
Let element rect be element’s rectangle.
If asked to scroll, scroll into view the element.
Let screenshot result be the result of calling draw a bounding box from the framebuffer, given element rect as an argument.
If screenshot result is an error, return screenshot result.
Let canvas be a canvas
element of screenshot result’s data.
Let encoding result be the result of encoding as Base64 canvas.
If encoding result is an error, return encoding result.
Let encoded string be encoding result’s data.
Return success with data encoded string.
It is advisable that remote ends create a new profile when creating a new session. This prevents potentially sensitive session data from being accessible to new sessions, ensuring both privacy and preventing state from bleeding through to the next session.
A user agent can rely on a command-line flag or a configuration option to test whether to enable WebDriver, or alternatively make the user agent initiate or confirm the connection through a privileged content document or control widget, in case the user agent does not directly implement the HTTP endpoints.
It is strongly suggested that user agents require users to take explicit action to enable WebDriver, and that WebDriver remains disabled in publicly consumed versions of the user agent.
To prevent arbitrary machines on the network from connecting and creating sessions, it is suggested that only connections from loopback devices are allowed by default.
The remote end can include a configuration option to limit the accepted IP range allowed to connect and make requests. The default setting for this might be to limit connections to the IPv4 localhost CIDR range 127.0.0.0/8
and the IPv6 localhost address ::1
. [RFC4632]
It is also suggested that user agents make an effort to visually distinguish a user agent session that is under control of WebDriver from those used for normal browsing sessions. This can be done through a browser chrome element such as a “door hanger”, colorful decoration of the OS window, or some widget element that is prevalent in the window so that it easy to identify automation windows.
Although WebDriver does not define a primitive to ascertain the visibility of an element in the viewport, we acknowledge that it is an important feature for many users. Here we include a recommended approach which will give a simplified approximation of an element’s visibility, but please note that it relies only on tree-traversal, and only covers a subset of visibility checks.
The visibility of an element is guided by what is perceptually visible to the human eye. In this context, an element's displayedness does not relate to the visibility
or display
style properties.
The approach recommended to implementors to ascertain an element's visibility is based on crude approximations about its nature and relationship in the tree. An element is in general to be considered visible if any part of it is drawn on the canvas within the bounderies of the viewport.
When asked to normalize style pixel values to floating point for a value s of the type string:
Let trimmed string be a substring of s where the suffix "px
" is removed.
Let pixels be the result of parsing trimmed string as a float.
If pixels is not a float or the previous operation did not succeed, return 0.0
.
Round off pixels using a ceiling function so that it has no more than four decimals.
Return pixels.
To normalize style pixel values to floating point is almost equivalent to calling parseFloat from [ECMA-262] with the exception that non-valid float return values are returned as 0.0
.
This algorithm is not the same as the one used by Selenium. To provide backwards compatibility, we should change it to be an accurate description of what Selenium does.
The element displayed algorithm is a boolean state where true signifies that the element is displayed and false signifies that the element is not displayed. To compute the state on element:
If the attribute hidden
is set, return false.
If the computed value of the display
style property is "none", return false.
Not really sure what this means, needs review:
If it has a [CSS3-2D-TRANSFORMS] or [CSS3-3D-TRANSFORMS] style property that gives a negative X or Y coordinates to the canvas, return false.
If element is the document's root element, that is document.documentElement
:
If the computed value of the background-color
property is "transparent", run these substeps:
If element is an html
element, and the computed value of the
background-color
style property of the first
body
element descendant of the element in
tree order, relative to that element, is also "transparent", return false. Otherwise return true.
If element is an option
element or optgroup
element, and element's parent node is a select
element:
Apply the element displayed algorithm on element's parent node.
If the return value is false, abort these steps and return that value.
If element is a map
element:
Let any images visible be a boolean initially set to false.
For each img
element, image element, in the document with a name
attribute matching the value of element's usemap
attribute, run these substeps:
Run the element displayed algorithm on image element and set any images visible to any images visible bitwise OR its return value.
If any images visible is true, abort these steps and return its value.
If element is an area
element:
For each ancestral element parent, in tree order:
If parent is a map
element, apply the element displayed algorithm on it.
If the return value is false, abort these steps and return that value.
Otherwise apply step 7.1 on parent.
If it has equal to or more than one direct descendant elements:
Let visible children be a boolean initially set to false.
For each direct descendant element child:
Let rectangle be child’s bounding rectangle.
If the value of the height
property of rectangle is greater than zero CSS reference pixels, and the value of the width
property of rectangle is greater than zero CSS reference pixels:
Set visible children to visible children bitwise OR true.
For each ancestral element parent, in tree order:
Apply the element displayed algorithm to parent.
If the return value is false, abort these steps and return that value.
If parent is a block element box and the computed values of either overflow-x
or overflow-y
is "hidden":
Let parent dimensions be the rectangle that is the first element of the
sequence returned by calling getClientRects on parent.
DOMRect
Let element dimensions be the rectangle that is the first element of the DOMRect
sequence returned by calling getClientRects on element.
Let parent style be the computed style of parent.
Return false if any the following conditions evaluate to false:
element dimension's top
is less than (parent dimension's bottom
− the normalized style pixel float value of parent style's borderBottomWidth
).
element dimension's bottom
is less than (parent dimension's top
− the normalized style pixel float value of parent style's borderTopWidth
).
element dimension's left
is less than (parent dimension's right
− the normalized style pixel float value of parent style's borderRightWidth
casted as a float).
element dimension's right
is less than (parent dimension's left
− the normalized style pixel float value of parent style's borderLeftWidth
casted as a float).
Run step 10 on the parent elements of parent, if any.
Return true.
There have been a lot of people that have helped make browser automation possible over the years and thereby furthered the goals of this standard. In particular, thanks goes to the Selenium Open Source community, without which this standard would never have been possible.
This standard is authored by Aleksey Chemakin, Andreas Tolfsen, Andrey Botalov, Clayton Martin, Daniel Wagner-Hall, David Burns, Eran Messeri, Erik Wilde, Gábor Csárdi, James Graham, Jason Juang, Jason Leyba, John Jansen, Luke Inman-Semerau, Maja Frydrychowicz, Malini Das, Marc Fisher, Ondřej Machulda, Randall Kent, Seva Lotoshnikov, Simon Stewart, Titus Fortner, and Vangelis Katsikaros. The work is coordinated and edited by David Burns and Simon Stewart.
Thanks to Berge Schwebs Bjørlo, Malcolm Rowe, Michael[tm] Smith, Philippe Le Hégaret, Robin Berjon, Ross Patterson, and Wilhelm Joys Andersen for proofreading and suggesting areas for improvement.