Copyright © 2015 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 http://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.
The standard defines four broad conformance classes:
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.
This specification relies on several other underlying specifications.
The following terms are defined in the Document Object Model specification: [DOM]
The following attributes are defined in the DOM Parsing and Serialisation specification: [DOM-PARSING]
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 HTML specification: [HTML]
activeElement
attribute on Document
Document
object
Window
object
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
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]
The following terms are defined in the Cookie specification: [RFC6265]
cookie-string
name
field
value
field
expiry-time
field
domain
field
path
field
secure-only-flag
field
http-only-flag
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
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]
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.
An ASCII string is a string in the range U+0000 to U+007F, inclusive.
A Universally Unique IDentifier (UUID) is a 128 bits long URN that requires no central registration process. [RFC4122]
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.
WebDriver remote ends must provide an HTTP-based, RESTish 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 requierements 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.
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 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.
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.
If data is not null, let response’s body be the result of serializing as JSON with data as the argument.
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 |
POST | /session/{session id}/url | Get |
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}/window/fullscreen | Fullscreen Window |
POST | /session/{session id}/window/maximize | Maximize Window |
POST | /session/{session id}/window/size | Set Window Size |
GET | /session/{session id}/window/size | Get Window Size |
POST | /session/{session id}/frame | Switch To Frame |
POST | /session/{session id}/frame/parent | Switch To Parent Frame |
POST | /session/{session id}/element | Find Element |
POST | /session/{session id}/element/{element id}/element | Find Element From Element |
POST | /session/{session id}/elements | Find Elements |
POST | /session/{session id}/element/{element id}/elements | Find Elements From Element |
GET | /session/{session id}/element/active | Get Active 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}/execute/sync | Execute Script |
POST | /session/{session id}/execute/async | Execute Async Script |
GET | /session/{session id}/cookie/{name} | Get 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}/timeouts | Set Timeout |
POST | /session/{session id}/actions | Actions |
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}/sendKeys | Element Send Keys |
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 occured;
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 not selectable | 400 | element not selectable
| An attempt was made to select an element that cannot be selected. |
element not visible | 400 | element not visible
| An element command could not be completed because the element is not visible on the page. |
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 element coordinates | 400 | invalid element coordinates
| The coordinates provided to an interactions operation are invalid. |
invalid element state | 400 | invalid element state
| An element 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 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
| An element 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 a lowercased ASCII 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 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.
The remote end’s extension prefix is a lowercased ASCII string that forms a URL path element, separating extension commands from other commands 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.
WebDriver capabilities allow the local end to specify what features it requires the remote end to fulfill to be able to create a new session.
When processing capabilities with argument parameters a remote end must run the following steps:
Let server capabilities be a JSON Object with the following entries:
browserName
"
browserVersion
"
platformName
"
platformVersion
"
acceptSslCerts
"
Let required capabilities be the result of getting a property
named requiredCapabilities
from capabilities.
Let desired capabilities be the result of getting a property
named desiredCapabilities
from capabilities.
Let length be the length of required capabilities.
Let k be 0.
While k < length:
Let capability be the entry in required capabilities at index k.
If the name of the capability is among the names of entries in desired capabilities, remove the corresponding entry from desired capabilities.
Let unmet capabilities be an empty JSON List.
Let unprocessed capabilities be a JSON Object that contains all entries from required capabilities and all entries from desired capabilities.
Let j be 0.
Let capabilties length be the length of unprocessed capabilities.
While j < capabilities length:
Let unprocessed capability be the entry at index j in unprocessed capabilities.
If during the steps below the unprocessed capability equals an entry in required capabilities and name of unprocessed capability entry among the names of entries in server capabilities and the values do not match do the following:
Append a string containing the property name and the differences between the values.
Let browser name be the result of getting a property
named browserName
from unprocessed capability.
If browser name is undefined move to the next step.
Let browser version be the result of getting a property
named browserVersion
from unprocessed capability.
If browser version is undefined move to the next step.
Let platform name be the result of getting a property
named platformName
from unprocessed capability.
If platform name is undefined move to the next step.
Let platform version be the result of getting a property
named platformVersion
from unprocessed capability.
If platform version is undefined move to the next step.
Let proxy be the result of getting a property
named proxy
from unprocessed capability.
If proxy is undefined move to the next step.
If proxy is defined and not a map,
append a string saying that a JSON Object is required,
else call set the proxy passing in proxy.
Let page load strategy be the result of getting a property
named pageLoadStrategy
from unprocessed capability.
If page load strategy is undefined,
then set the entry pageLoadStrategy
in server capabilities to normal.
If the length of unmet capabilities is not equal to 0, return session not created with data unmet capabilities.
Return server capabilities.
To set the proxy from a JSON Object proxy:
Let proxy type be the result of
getting a property named proxyType
from proxy.
Switch on proxy type:
pac
"
If the implementation supports proxy autoconfiguration, set the implementation’s autoproxy configuration URL to proxy autoconfiguration url.
Otherwise return an error with error code invalid argument.
noproxy
"
Set the proxy to No Proxy using implementation defined steps. If this can not be set during this process return error.
autodetect
"
Set the proxy to Auto-Detect proxy setting from the network using implementation defined steps. If this can not be set during this process return error.
system
"
Set the proxy to use system proxy settings using implementation defined steps. If this can not be set during this process return error.
manual
"
Let ftp proxy be the result of getting a property
named ftpProxy
from proxy.
Let ftp proxy port be the result of getting a property
named ftpProxyPort
from proxy.
Let http proxy be the result of getting a property
named httpProxy
from proxy.
Let http proxy port be the result of getting a property
named httpProxyPort
from proxy.
Let ssl proxy be the result of getting a property
named sslProxy
from proxy.
Let ssl proxy port be the result of getting a property
named sslProxyPort
from proxy.
Let socks proxy be the result of getting a property
named socksProxy
from proxy.
Let socks proxy port be the result of getting a property
named socksProxyPort
from proxy.
If socks proxy and socks proxy port is defined:
Let socks version be the result of getting a property
named socksVersion
from proxy.
Let socks username be the result of getting a property
named socksUsername
from proxy.
Let socks password be the result of getting a property
named socksPassword
from proxy.
Follow implementation defined steps to set the proxy using defined variables from previous steps. If there are items that can not be set during this process return error.
Return error with error code invalid argument.
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, or the top-level browsing context for which the current browsing context is an ancestor browsing context.
The top-level browsing context is said to be no longer open if it has been discarded.
Each top-level browsing context has an associated window handle, which is a string uniquely identifying that browsing context. This string is implementation defined but MUST not be "current".
A session has an associated session script timeout that specifies a time to wait for scripts to run. 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 for the implicit element location strategy when locating elements using Find Element and Find Elements. 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 user prompt handler.
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, that is if the endpoint node already has a current session, 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, they are allowed to freely use the capabilities data e.g. to select a specific browser to test based on a combination of the required and desired capabilities. Typically the New Session response from the endpoint node selected in this process will then be relayed directly to the local end, as outlined in step 1 of the remote end steps.
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 be the result of getting a property
named "capabilities
" from the parameters argument.
Let capabilities result be the result of processing capabilities with capabilities as an argument.
If capabilities result is an error, 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 if not set while processing capabilities:
Set the current session’s session script timeout to 30,000 milliseconds.
Set the current session’s session page load timeout to 300,000 milliseconds.
Set the current session’s session implicit wait timeout to 0 (zero) milliseconds.
Set the current session’s page loading strategy to normal.
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 |
---|---|
POST | /session/{session id}/timeouts |
The Set Timeout command sets timeouts associated with the current session. The timeouts that can be controlled are the session script timeout, the session page load timeout, and the session implicit wait timeout.
The following table of session timeouts lists pairs of different timeouts that may be changed with the string codes used to identify them:
Type | Identifier |
---|---|
session script timeout | "script "
|
session page load timeout | "page load "
|
session implicit wait timeout | "implicit "
|
The remote end steps for the Set Timeout command are:
For each row in the table of session timeouts, enumerated as type and identifier:
If parameters does not have an own property identifier, continue to the next entry.
Let timeout be the result of getting a property using identifier from parameters.
If timeout is of the
Number
type
and a non-negative integer,
set the type timeout to
timeout’s value in milliseconds.
Otherwise, return error with error code invalid argument.
Return success.
Warning: This section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
Capability Name | Type |
secureSsl | boolean |
WebDriver implementations MUST support users accessing sites served via HTTPS. Access to those sites using self-signed or invalid certificates, and where the certificate does not match the serving domain MUST be the same as if the HTTPS was configured properly.
The reason for this is that implementations of this spec are often used for testing. It's a sorry fact that many QA engineers and testers are asked to verify that apps work on sites that have insecure HTTPS configurations.
The exception to requirement is if the Capabilities
used to initialize has the WebDriver session had
the capability secureSsl
set to true.
In this case, implementations MAY choose to make accessing a site
with bad HTTPS configurations cause a WebDriverException
to be thrown.
Remote end implementations MUST
return an unknown error error code in this case.
If this is the case, the Capabilities describing the session
MUST also set the secureSsl
capability to "true".
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 notaion of a “window”
or the DOM Window
object.
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.
Let data be a new JSON Object.
Set the property "value
" on data
to the value of 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 top-level 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 arbitary.
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.
Let body be a JSON object
with the property "value
" set to 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.
Note that representing a web element will have to do the same document checks, or something.
Let element be the result of getting a known element by UUID id.
If element is not a frame
or iframe
element,
return error with error code no such frame.
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 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.
HTTP Method | Path Template |
---|---|
GET | /session/{sessionId}/window/size |
The Get Window Size command returns the size 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.
Let width be 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.
Let height be the height in CSS reference pixels of the operating system window containing the current top-level browsing context, including any browser chrome and any externally drawn window decorations.
Let body be a new JSON Object initialised with:
width
"
height
"
Return success with data body.
In some user agents the dimensions of the browser
including window decorations are provided by
the proprietary window.outerWidth
and window.outerHeight
properties.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/window/size |
The Set Window Size command alters the size 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 Size command for the current top-level browsing context for any reason, return error with error code unsupported operation.
Let width be the result of
getting a property named width
from the parameters argument.
Let height be the result of
getting a property named height
from the parameters argument.
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.
Return success with data null.
The specification does not guarantee that the resulting window size will exactly match that which was requested. In particular the implementation is expected to clamp values that are larger than the physical screen dimensions, or smaller than the minimum window size. Particular implemetations may have other limitations such as not being able to resize in single-pixel increments.
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.
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 UI 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 the Fullscreen Window command for the current top-level browsing context for any reason, return error with error code unsupported operation.
Run the implementation-specific steps, which should have the effect of making the dimensions of the window containing the current top-level browsing context as close as possible to the dimensions of the display containing the window, and may hide browser-provided UI such as toolbars.
Return success with data null.
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 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 new 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.
When asked to serialize the element element:
Let object be a new JSON Object with properties:
Value of element’s web element reference.
Return object.
When required to deserialize the 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().
An element is considered editable
if it is either an input
element
whose type
attribute is not in the
Button,
Hidden,
Image Button,
Reset Button,
or Submit Button states,
or a textarea
element,
or 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.
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 visible width be element’s bounding rectangle’s (max(x coordinate, x coordinate + width dimension) – the current browsing context’s innerWidth).
Let visible height be element’s bounding rectangle’s (max(y coordinate, y coordinate + height dimension) – the current browsing context’s innerWidth).
Let vertical centre offset be (visible width / 2.0).
Let horizontal centre offset be (visible height / 2.0).
Let centre point be a pair of element’s (rectangle x coordinate + horizontal centre offset) and (rectangle y coordinate + vertical centre offset).
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 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.
Let active element be the active element of the current browsing context’s document element.
Let active web element be the serialization of the element active element.
Return success with data active web element.
The Find Element and Find Elements commands allows look up of individual and a collection of elements, respectively. Elements are serialised and returned as web elements. Web element references are needed to interact with individual elements.
An element location strategy is an enumerated attribute which decides 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 "
|
XPath selector | "xpath "
|
Warning: This rest of this section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
Strategy name: css selector
If a browser supports the
CSS Selectors API ([SELECTORS-API]) it MUST support locating elements by
CSS Selector. If the browser does not support the browser CSS Selector spec it MAY choose to implement locating
by this mechanism. If the browser can support locating elements by CSS Selector, it MUST set the "cssSelector" capability to boolean true when responding to the newSession(). Elements MUST be returned in the same order as if "querySelectorAll
" had been called with the Locator
's value
. Compound selectors are allowed.
Finding elements by ecmascript is covered in the ecmascript part of this spec.
Strategy name: link text
This strategy MUST be supported by all WebDriver implementations.
This strategy MUST return all "a" elements with visible text exactly and case sensitively equal to the term being searched for.
This is equivalent to:
elements = driver.find_elements(by = By.TAG_NAME, value = "a") result = [] for element in elements: text = element.text if text == search_term: result.append(element)
Where "search_term" is the link text being searched for, and "result" contains the list of elements to return.
Strategy name: partial link text
This strategy MUST be supported by all WebDriver implementations.
This strategy is very similar to link text, but rather than matching the entire string, only a subset needs to match. That is, this MUST return all "a" elements with visible text that partially or completely and case sensitively matches the term being searched for.
This is equivalent to:
elements = driver.find_elements(by = By.TAG_NAME, value = "a") result = [] for element in elements: text = element.text if text.search(seach_term) != -1: result.append(element)
Where "search_term" is the link text being searched for, and "result" contains the list of elements to return.
Strategy name: xpath
All WebDriver implementations MUST support finding elements by XPath 1.0 [XPATH] with the edits from section 3.3 of the [html51] specification made. If no native support is present in the browser, a pure JS implementation MAY be used. When called, the returned values MUST be equivalent of calling "evaluate" function from [DOM-LEVEL-3-XPATH] with the result type set to ORDERED_NODE_SNAPSHOT_TYPE (7).
When the findElement() or findElements() WebDriver Command is called the following must be parameters after the local end has made a request to the remote end:
Invalid Selector
Warning: This section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element |
If id is empty:
no such element
If an error is returned from Element Location Strategy do the following.(todo describe how the error is returned)
invalid selector
{"element-6066-11e4-a52e-4f735466cecf": id}
{ "value": {"element-6066-11e4-a52e-4f735466cecf": id} }
When searching from an element from another element the following algorithm should be used:
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/element |
If id is empty:
no such element
If an error is returned from Element Location Strategy do the following.(todo describe how the error is returned)
invalid selector
{"element-6066-11e4-a52e-4f735466cecf": id}
{ "value": {"element-6066-11e4-a52e-4f735466cecf": id} }
Warning: This section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
When there is a need to find multiple elements on a document that we can return to the local end we use the following algorithm:
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/elements |
{"element-6066-11e4-a52e-4f735466cecf": id}
to result{ "value": [{"element-6066-11e4-a52e-4f735466cecf": id}, {"element-6066-11e4-a52e-4f735466cecf": id}] }
When there is a need to search from an element to find the next WebElement we use the following algorithm:
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/elements |
{"element-6066-11e4-a52e-4f735466cecf": id}
to result{ "value": [{"element-6066-11e4-a52e-4f735466cecf": id}, {"element-6066-11e4-a52e-4f735466cecf": id}] }
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.
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
elements
of the Checkbox- and Radio Button states,
or input
elements.
option
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.
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
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.
Let body be a JSON Object
with the "value
" member set to selected.
Return success with data body.
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 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.
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.
Let body be a JSON Object
with the "value
" member set to result.
Return success with data body.
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 a element.
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.
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.
Let body be a JSON Object
with the "value
" property set to result.
Return success with data body.
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 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.
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 "".
Let body be a JSON Object with
the "value
" member set to computed value.
Warning: This section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
There is concern that element text visibility is not something WebDriver should define because there does not exist enough platform primitives to future-proof it. Specifically this relates to technologies such as web components and shadow DOM. Note that a decision on this matter will also affect the future of the elements selector strategies for link text and partial link text.
HTTP Method | Path Template |
---|---|
GET | /session/{session id}/element/{element id}/text |
The following definitions are used in this section:
\s
.
[^\S\xa0]
[\x20\t\u2028\u2029]
.The expected return value is roughly what a text-only browser would display. The algorithm for determining this text is as follows:
Let lines
equal an empty array. Then:
head
element of the document, return an empty string otherwise carry on with the algorithm below.text
equal the nodeValue
property of descendent. Then:
text
.text
to a single newline (greedily matching (\r\n|\r|\n)
to a single \n)text
with a single space character (\x20). If the parent's effective CSS whitespace style is 'pre' or 'pre-wrap' replace each horizontal whitespace character with a non-breaking space character (\xa0). Otherwise replace each sequence of horizontal whitespace characters except non-breaking spaces (\xa0) with a single space characterlast(lines)
ends with a space character and text
starts with a space character, trim the first character of text
.text
to last(lines)
in-placelines
and continuelast(lines)
is not '', push '' to lines
.last(lines)
does not end with whitespace append a single space character to last(lines)
[Note: Most innerText implementations append a \t here]lines
If the ELEMENT
does not represent a Document element
, or it represents a Document element
that is no longer attached to the document's node tree, then the WebDriver implementation MUST immediately abort the command and return a stale element reference
error. If the top level browsing context currently receiving commands is no longer open a no such window
error MUST be raised.
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 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.
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.
Let body be a JSON Object
with the "value
" member set to qualified name.
Return success with data body.
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 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.
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 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.
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.
Let body be a JSON object
with the "value
" member set to enabled.
Return success with data body.
The element interaction commands provide a high-level instruction set for manipulating form controls. Unlike the Actions interface, 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 then attempts to click the centre of its visible area. In case the element is not displayed, an element not visible error is returned.
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 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 displayed, return error with error code element not visible.
Scroll into view the element.
Get the element’s bounding box and calculate centre position.
Run interaction steps on coordinate.
Return success with data null.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/clear |
The Element Clear command scrolls into view a submittable element excluding buttons or editable element, and then attempts to clear its value, checkedness, or text content.
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 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 displayed, return error with error code element not visible.
If element is disabled, non-editable, read only, or has pointer events disabled, return error with error code invalid element state.
Scroll into view the element.
If element is editable,
set its innerHTML
IDL attribute to an empty string.
Otherwise:
type
attribute:
Set the checkedness to false.
Set the value to an empty string.
Return success with data null.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/sendKeys |
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 displayed, an element not visible error is returned.
Should this also work for contenteditable
elements?
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 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 displayed, return error with error code element not visible.
Scroll into view the element.
Interact with the element.
Return success with data null.
When required to JSON deserialize 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 result of running the deserialize the web element algorithm with object value.
Return the result of running the clone an object algorithm with arguments value and seen, and the JSON deserialize 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.
Serialize the element with argument 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, switching 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.
When required to execute a function body with arguments body and arguments, a remote end must run the following steps:
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 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.
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.
If result is an error, return result.
Otherwise let value be result’s data.
Let data be a new JSON Object.
Set the property "value
" of data
to value.
Return success with data data.
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 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.
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.
Let data be a new JSON Object.
Set the property value
of data
to value.
Return success with data data.
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
.
Warning: This section has not yet been redefined to match the routing requests model, and uses old concepts and definitions. Please do not rely on it yet.
The WebDriver API offers two ways of interacting with elements, either with a set of low-level "do as I say" actions, or a high-level "do as I mean" set of actions. The former are offered to allow precise emulation of user input. The latter are offered as a convenience to cover the common case, and can conceivably be implemented on top of the lower level primitive operations.
Interactions can be used to emulate single input actions as well as
multiple, simultaneous actions.
Activation triggers generated by the WebDriver API User SHOULD be indistinguishable from those generated by a real user interacting with the browser. In particular, the dispatched events will have the isTrusted attribute set to true. The most robust way to dispatch these events is by creating them in the browser implementation itself. Sending OS-specific input messages to the browser's window has the disadvantage that the browser being automated may not be properly isolated from a user accidentally modifying input source state; use of an OS-level accessibility API has the disadvantage that the browser's window must be focused, and as a result, multiple tests cannot run in parallel.
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/actions |
Use symbols?
The "source" member will hold a string value to represent the input source. Implementations MUST support "keyboard", "mouse", and "touch", and can be extended for any other input source.
id
This is a locally-assigned unique identifier. It will be used by the remote end to differentiate dispatched actions. For example, if you have a "touch" action with id "1" to represent one finger actively pressed on a screen, then you can dispatch another "touch" action with id "2" to represent a second finger on a screen, acting simultaneously.
actions
This holds a list of objects, where each object represents a low-level command. The list order dictates the order in which each command will be dispatched. Each command MUST have a 'name' member, whose value will hold the name of the command. More information on each command is in the action commands section.
So the structure will look as follows:
[ { "source": "string", "id": "string", "actions": [ { "name": "string: name of action primitive", ... parameters to action commands... }, ] } ]
HTTP Method | Path Template |
---|---|
DELETE | /session/{session id}/actions |
Or MAY, since we can default to 0 on remote end?
The "pause" action MUST take in a parameter named "duration" which will be the time to wait either in milliseconds or using a symbol. This action is used to indicate a period of time to wait between actions, and will also be used to indicate a period of inaction in parallel action chains.
If you wish to use a system specific wait period, please use the following symbols:
The following are actions that must be implemented for both "mouse" and "touch" input sources. Any future pointer-based source must implement these actions.
NOTE: conflating mouse and touch causes the pointerMove/pointerDown to events to be confusing and lacks verisimilitude: If you want to tap at element1, then that would mean 'put finger down on element1, remove finger from element1', for a tap, we have to decide if we want to send 'pointerMove, pointerDown, pointerUp' or 'pointerDown, pointerUp'. The latter matches the touch events sent (touchStart,touchEnd), and makes sense for touchscreens because there is no active button state (http://www.w3.org/TR/pointerevents/#glossary) until you dispatch a touchstart. sending a JSON structure with pointerMove, pointerDown, pointerUp for something that gets mapped to touchstart/touchend feels inelegant. We can enforce the following instead:
The ramifications of this proposal would be that pointerDown must accept the parameters that pointerMove does (ie: ELEMENT, etc.).
pointerMove
The "pointerMove" action is used to move the pointer to a specific location on a page. In "mouse" sources, this would dispatch a "mouseMove" event. In "touch" sources, then if there is an active pointerDown action, this will generate a "touchmove" or "pointermove" event. For "touch" sources, pointerMove must not be called before pointerDown, since pointer sources only have move events once they are active on the screen.
When sending a "pointerMove", one of the following parameter sets MUST be used:
Viewport, or top-left of root element?
pointerDown
The "pointerDown" action is used to start an interaction on the page. In "mouse" sources, this would mean "mouseDown", in "touch" sources, this would mean "touchstart" or "pointerdown".
For "touch" sources, the following parameters must be passed:
For "mouse" sources, the following parameter must be passed:
Link to button chart
pointerUp
The "pointerUp" action is used to start an interaction on the page. In "mouse" sources, this would mean "mouseUp", in "touch" sources, this would mean dispatching an event like "touchend" or "pointerup".
Takes no parameters
pointerCancel
The "pointerMove" action is used to cancel an active pointer on the page. In "mouse" sources, this would mean "mouseUp", in "touch" sources, it implies cancelling the current action if possible by dispatching an event like "touchcancel" or "pointercancel".
Parallel actions are those that have more than one action acting simultaneously on the browser. An example of this is using multiple fingers to operate on a tablet screen at the same time.
Dispatching a parallel action also uses the actions endpoint. In order to send a parallel action, append multiple dictionaries to the list of dictionary objects. Each dictionary will hold all the actions from one input source. The list of actions each dictionary contains will be executed together in ticks, by stepping through each input source's action list in order and executing each step simultaneously.
The best way to understand this is through an example. Imagine we have two fingers acting on a touchscreen. One finger will press down on element1 at the same moment that another finger presses down on element2. Once these actions are done, the first finger will wait 5 seconds while the other finger moves to element3. Then both fingers release from the touchscreen.
To execute these actions, we must send the "actions" endpoint two dictionary objects in the JSON list of dictionaries, one for each finger. We must use the "id" key of each object to uniquely identify each finger. The "actions" key will hold all the actions the input source will take.
The JSON for this set of actions is as follows:
[ { "source": "touch", "id": "1", "actions": [ { "name": "pointerDown", "ELEMENT": "element1" }, { "name": "pause", "duration": 0 }, { "name": "pointerUp" } ] }, { "source": "touch", "id": "2", "actions": [ { "name": "pointerDown", "ELEMENT": "element2" }, { "name": "pointerMove", "ELEMENT": "element3" }, { "name": "pointerUp" } ] } ]
When the remote end receives this, it will look at each input source's action lists. It will dispatch the first action of each source together, then the second actions together, and lastly, the final actions together.
The diagram below displays when each action gets executed. "Source 1" is the first finger, and "source 2" is the second.
There is no limit to the number of input sources, and there is no restriction regarding the length of each input's action list. Meaning, there is no requirement that all action lists have to be the same length. It is possible for one input source's action list may have more actions than another. As an example, imagine having two fingers on a touchscreen. The first finger will press on element1 while the second presses on element2, then the first will release the touchscreen while the second finger moves to element3, and finally the second finger releases from the touchscreen. In this case, the action list for the first finger contains 2 actions (pointerDown, pointerUp), and the action list for the second finger contains 3 (pointerDown, pointerMove, pointerUp). In this case, the JSON will look like this:
[ { "source": "touch", "id": "1", "actions": [ { "name": "pointerDown", "ELEMENT": "element1" }, { "name": "pointerUp" } ] }, { "source": "touch", "id": "2", "actions": [ { "name": "pointerDown", "ELEMENT": "element2" }, { "name": "pointerMove", "ELEMENT": "element3" }, { "name": "pointerUp" } ] } ]
And the execution of each action will be done as follows:
Specific timing for the actions can also be expressed. The "pause" action can be used to either a) indicate a specific amount of time an input source must wait, or b) can be used to signify that the current input source must wait until all other actions in the tick are completed. For the former case, the current tick being executed must wait for the longest pause to complete. For example, in this diagram:
The remote end will dispatch the pointerDown actions in the first tick. In the second tick, since source 1 declares a pause of 5 seconds, the remote end will dispatch the pointerUp event for source 2, and will wait 5 seconds before moving on to executing the third tick.
In the event that one tick contains multiple pause durations, the remote end will wait the maximum duration before moving on to executing the next tick.
As noted before, "pause" can be used to signify inaction during a tick. If "pause" is declared without a time period, then the input source will not have any actions executed in the containing tick. As an example:
During tick 2, source 1 will have its pointerMove action dispatched, while source 2 will do nothing.
These higher level commands SHOULD be built on top of the low level commands, and implement a user friendly way of interacting with a page in a way that models common user expectations.
A requirement for key-based interaction with an element is that it is interactable. Typing into an element is permitted if one of the following conditions is met:
activeElement
. In
addition to focusable elements, this allows typing to the BODY
element.contentEditable
attribute set or the containing document is in designMode
.Prior to any keyboard interaction, an attempt to shift focus to the element MUST be attempted if the element does not currently have the focus. This is the case if one of the following holds:
activeElement
.In case focusing is needed, the implementation MUST follow the focusing steps as described in the focus management section of the [HTML] spec. The focus MUST NOT leave the element at the end of the interaction, other than as a result of the interaction itself (i.e. when the tab key is sent).
HTTP Method | Path Template |
---|---|
POST | /session/{session id}/element/{element id}/value |
Let value be an array of characters that will be typed into a WebElement.
Sends a sequence of keyboard events representing the keys in the value parameter.
Caret positioning: If focusing was needed, after following the focusing steps, the caret MUST be positioned at the end of the text currently in the element. At the end of the interaction, the caret MUST be positioned at the end of the typed text sequence, unless the keys sent position it otherwise (e.g. using the LEFT key).
There are four different types of keys that are emulated:
When emulating user input, the implementation MUST generate
the same sequence of events that would have been produced if a real user was
sitting in front of the keyboard and typing the sequence of characters. In
cases where there is more than one way to type this sequence, the
implementation MUST choose one of the valid ways. For example, typing AB
may be achieved by:
Or by simply turning on the CAPS LOCK first.
The implementation MAY use the following algorithm to generate the events. If the implementation is using a different algorithm, it MUST adhere to the requirements listed below.
For each key, key in value, do
keydown
, keypress
and keyup
events with
key as
the character to emulatekeydown
, keypress
and keyup
events with
uppercaseKey as the character to emulatekeydown
event of the Shift key.
keydown
, keypress
and keyup
events with
key as
the character to emulatekeyup
event of the Shift key.
keydown
, keypress
and keyup
events with
key as the character to emulatekeyup
event of modifierkeydown
event of modifierkeyup
events of all modifier keys currently held
down.keydown
, keypress
and keyup
events for the special key.Once keyboard input is complete, an implicit NULL key is sent unless the final character is the NULL key.
Any implementation MUST comply with these requirements:
keydown
event is generated before the entire
sequence of uppercase letters.keydown
event is
generated. After each letter or symbol, a Shift keyup
event is
generated.keydown
event MUST NOT be generated. In that
case, a Shift keyup
event MUST NOT be generated implicitly by the
implementation.sendKeys
call and the appropriate keyup
events
generated
The value parameter contains a mix of printable characters and pressable keys that aren't text. Pressable keys that aren't text are stored in the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. The following table describes the mapping between PUA and key:
Key | Code | Type |
---|---|---|
NULL | \uE000 | NULL |
CANCEL | \uE001 | Special key |
HELP | \uE002 | Special key |
BACK_SPACE | \uE003 | Special key |
TAB | \uE004 | Special key |
CLEAR | \uE005 | Special key |
RETURN | \uE006 | Special key |
ENTER | \uE007 | Special key |
SHIFT | \uE008 | Modifier |
CONTROL | \uE009 | Modifier |
ALT | \uE00A | Modifier |
PAUSE | \uE00B | Special key |
ESCAPE | \uE00C | Special key |
SPACE | \uE00D | Special key |
PAGE_UP | \uE00E | Special key |
PAGE_DOWN | \uE00F | Special key |
END | \uE010 | Special key |
HOME | \uE011 | Special key |
ARROW_LEFT | \uE012 | Special key |
ARROW_UP | \uE013 | Special key |
ARROW_RIGHT | \uE014 | Special key |
ARROW_DOWN | \uE015 | Special key |
INSERT | \uE016 | Special key |
DELETE | \uE017 | Special key |
SEMICOLON | \uE018 | Special key |
EQUALS | \uE019 | Special key |
NUMPAD0 | \uE01A | Special key |
NUMPAD1 | \uE01B | Special key |
NUMPAD2 | \uE01C | Special key |
NUMPAD3 | \uE01D | Special key |
NUMPAD4 | \uE01E | Special key |
NUMPAD5 | \uE01F | Special key |
NUMPAD6 | \uE020 | Special key |
NUMPAD7 | \uE021 | Special key |
NUMPAD8 | \uE022 | Special key |
NUMPAD9 | \uE023 | Special key |
MULTIPLY | \uE024 | Special key |
ADD | \uE025 | Special key |
SEPARATOR | \uE026 | Special key |
SUBTRACT | \uE027 | Special key |
DECIMAL | \uE028 | Special key |
DIVIDE | \uE029 | Special key |
F1 | \uE031 | Special key |
F2 | \uE032 | Special key |
F3 | \uE033 | Special key |
F4 | \uE034 | Special key |
F5 | \uE035 | Special key |
F6 | \uE036 | Special key |
F7 | \uE037 | Special key |
F8 | \uE038 | Special key |
F9 | \uE039 | Special key |
F10 | \uE03A | Special key |
F11 | \uE03B | Special key |
F12 | \uE03C | Special key |
META | \uE03D | Special key |
COMMAND | \uE03D | Special key |
ZENKAKU_HANKAKU | \uE040 | Special key |
The keys considered upper-case symbols are either defined by the current keyboard locale or are derived from the US 104 keys Microsoft Windows keyboard layout, which are:
When the user input is emulated natively (see note below), the implementation SHOULD use the current keyboard locale to determine which symbols are upper case. In all other cases, the implementation MUST use the US 104 key Microsoft Windows keyboard layout to determine those symbols.
The state of the physical keyboard MUST NOT affect emulated user input.
Non-latin symbols: TBD
Complex scripts using Input Method Editor (IME): TBD
Non-normative summary:
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 dialogues enumerates all supported simple dialogues, along with the commands that are allowed to interact with it as a non-normative reference:
Definition | Dialogue | 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 dialogues,
the window.print
dialogue,
or a dialogue 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. The following table lists the keywords and states for the attribute:
Keyword | State | Description |
---|---|---|
"dismiss "
| Dismiss state | All simple dialogues encountered should be dismissed. |
"accept "
| Accept state | All simple dialogues 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.
Match on the 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 dialogue 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 dialogue 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.
Let body be a JSON Object with the
"value
" property set to message.
Return success with data body.
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.
Match on current user prompt:
Return error with error code element not visible.
Do nothing.
Return error with error code unsupported operation.
Let character array be the result of
getting a property message
from the parameters argument.
Let message be the result of joining together each element in character array to a string.
Set the current user prompt’s text field value to the value of message.
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 screenshot result’s data.
Let encoding result be the result of encoding as Base64 the canvas element.
If encoding result is an error, return encoding result.
Let encoded string be encoding result’s data.
Let body be a JSON Object
with the "value
" property set to encoded string.
Return success with data null.
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 top-level 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 screenshot result’s data.
Let encoding result be the result of encoding as Base64 the canvas element.
If encoding result is an error, return encoding result.
Let encoded string be encoding result’s data.
Let body be a JSON Object
with the "value
" property set to encoded string.
Return success with data body.
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 may rely on a command-line flag or a configuration option to test whether to enable WebDriver. Another option is to 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.
To prevent arbitrary machines from connecting and creating sessions, only connections from loopback devices are allowed by default. Remote ends do however support a scenario where the local end runs on a different machine from the remote end.
The remote end must include a configuration option
to limit the accepted IP range allowed to connect and make requests.
The default setting for this should be
to limit connections to the IPv4 localhost CIDR range 127.0.0.0/8
and the IPv6 localhost address ::1
. [RFC4632]
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 valid 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 HTML
element [HTML], 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
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":
DOMRectList
has disappeared from [GEOMETRY-1]
and been replaced by ArrayClass
,
but there is no reference to it.
Let parent dimensions be the rectangle
that is the first element of the DOMRectList
array returned by calling getClientRects on parent.
Let element dimensions be the rectangle
that is the first element of the DOMRectList
array 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.
Many thanks to Robin Berjon for making our lives so much easier with his cool tool. Thanks to Jason Leyba, Malcolm Rowe, Ross Patterson, Andrey Botalov, and Berge Schwebs Bjørlo for proof reading and suggesting areas for improvement. Thanks to Jason Leyba, Eran Messeri, Daniel Wagner-Hall, Malini Das, Luke Inman-Semerau, Andreas Tolfsen, James Graham, and John Jansen for contributing sections to this document. Also thanks to the following people for their contribution of patches and test cases: