WebDriver
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.
Conformance
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:
- Local End
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.
- Remote End
- The remote end hosts the server side of the protocol.
Defining the behaviour of a remote end in response to the WebDriver protocol
forms the largest part of this specification.
- Intermediary Node
- Intermediary nodes are those that act as proxies,
implementing both the client and server sides of the protocol.
Intermediary nodes must be black-box indistinguishable from a remote end
from the point of view of local end,
and so are bound by the requirements on a remote end in terms of the wire protocol.
However they are not expected to implement remote end steps directly.
- Endpoint Node
- An endpoint node is the final remote end
in a chain of nodes that is not an intermediary node.
The endpoint node is implemented by a user agent or a similar program.
An endpoint node must be, like intermediary nodes,
indistinguishable from a remote end.
Dependencies
This specification relies on several other underlying specifications.
- DOM
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 attributes are defined in the UI Events
specification: [[!UI-EVENTS]]
- ECMAScript
The following terms are defined in the ECMAScript Language Specification: [[!ECMA-262]]
- This specification also presumes that you are able to call
some of the internal methods from the ECMAScript Language Specification:
- The ECMAScript Language Specification also defines
the following types and values that are used throughout this specification:
- Fetch
The following terms are defined in the WHATWG Fetch specification: [[!FETCH]]
- HTML
The following terms are defined in the HTML specification: [[!HTML]]
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:
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]]
- HTTP and related specifications
The following terms are defined in the Cookie specification: [[!RFC6265]]
The following terms are defined in
the Hypertext Transfer Protocol (HTTP) Status Code Registry:
- The following terms are defined in
the Netscape Navigator Proxy Auto-Config File Format:
The specification uses
URI Templates. [[!URI-TEMPLATE]]
- Styling
- The following terms are defined in
the CSS Values and Units Module Level 3 specification: [[!CSS3-VALUES]]
- The following properties are defined in
the CSS Basic Box Model Level 3 specification: [[!CSS3-BOX]]
- The following terms are defined in
the CSS Device Adaptation Module Level 1 specification: [[!CSS-DEVICE-ADAPT]]
- The following properties are defined in
the CSS Display Module Level 3 specification: [[!CSS3-DISPLAY]]
- The following terms are defined in
the Geometry Interfaces Module Level 1 specification: [[!GEOMETRY-1]]
- The following terms are defined in
the CSS Cascading and Inheritance Level 4 specification: [[!CSS-CASCADE-4]]
- The following terms are defined in the CSS Object Model: [[!CSSOM]]:
- The following functions are defined in
the CSSOM View Module: [[!CSSOM-VIEW]]:
- URLs
- The following terms are defined in the WHATWG URL standard: [[!URL]]
- Web IDL
The IDL fragments in this specification
must be interpreted as required for conforming IDL fragments,
as described in the Web IDL specification. [[!WEBIDL]]
Terminology
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 Unix Epoch
is a value that approximates the number of seconds
that have elapsed since the Epoch,
as described by The Open Group Base Specifications Issue 7
section 4.15 (IEEE Std 1003.1).
Interface
partial interface Navigator {
readonly attribute boolean webdriver;
};
The webdriver IDL attribute
of the Navigator interface must return
the value of the webdriver-active flag, which is initially false.
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.
Protocol
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.
Algorithms
Various parts of this specification are written in terms of step-by-step algorithms.
The details of these algorithms do not have any normative significance;
implementations are free to adopt any implementation strategy
that produces equivalent output to the specification.
In particular algorithms in this document are optimised
for readability rather than performance.
Where algorithms that return values are fallible,
they are written in terms of returning either
success or error.
A success value has an associated data field
which encapsulates the value returned,
whereas an error response has an associated error code.
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.
Commands
The WebDriver protocol is organised into commands.
Each HTTP request with a method and template defined in this specification
represents a single command
and therefore each command produces a single HTTP response.
In response to a command,
a remote end will run a series of actions 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.
Processing Model
The remote end acts as a HTTP server reading requests
from the client and writing responses, typically over TCP socket.
For the purposes of this specification we model the data transmission
between a particular local end and remote end with a connection
to which the remote end may write bytes and read bytes.
However the exact details of how this connection works
and how it is established are out of scope.
After such a connection has been established,
a remote end MUST run the following steps:
Should mention what happens if it can’t be decoded as HTTP.
Note that Fetch isn’t quite right
because it doesn’t specify how to construct a request from network data, or serialize a response.
Read bytes from the connection
until a complete HTTP request can be constructed from the data.
Let request be a request
constructed from the received data,
according to the requirements of [[!RFC7230]].
Let request match be the result of the algorithm
to match a request with request’s
method and URL as arguments.
If request match is of type error,
send an error with request match’s error code
and jump to step 1.
Otherwise, let command and url variables
be request match’s data.
Let session id be the corresponding variable
from url variables.
If command is not New Session:
If session id is not equal to the ID
of any session in the list of active sessions,
send an error with error code invalid session id,
then jump to step 1 in this overall algorithm.
Otherwise, let the current session be
the session with ID session id.
If request’s method is POST:
Let parse result be the result of
parsing as JSON with request’s
body as the argument.
If parse result is an error or if it is a success
but its associated data is not an Object,
send an error with error code invalid argument
and jump back to step 1 in this overall algorithm.
Otherwise, let parameters be parse result’s data.
Otherwise, let parameters be null.
Let response result be the return value
obtained by running the remote end steps for command
with url variables as arguments.
If response result is an error,
send an error with error code
equal to response result’s error code
and jump back to step 1 in this overall algorithm.
Otherwise, if response result is a success,
let response data be response result’s data.
Send a response with status 200 and response data.
Jump to step 1.
When required to send an error,
with error code,
a remote end must run the following steps:
Let http status and name
be the error response data for error code.
Let message be an implementation-defined string
containing a human-readable description of the reason for the error.
Let stacktrace be an implementation-defined string
containing a stack trace report of the active stack frames
at the time when the error occurred.
Really need a better way to construct JSON literals.
Let data be a new JSON Object
initialised with the following properties:
- "
error"
- Value of name.
- "
message"
- Value of message.
- "
stacktrace"
- Value of 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.
Routing Requests
Request routing
is the process of going from a HTTP request
to the series of steps needed
to implement the command represented by that request.
A remote end has an associated URL prefix,
which is used as a prefix on all WebDriver-defined URLs on that remote end.
This must either be undefined or 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.
Handling Errors
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.
|
Capabilities
WebDriver capabilities allow the local end
to specify what features it desires or requires the remote end to fulfill
to be able to create a new session.
The following table provides an overview
of recognised capabilities, and their usage and effect:
| Capability
| Key
| Value Type
| Description
|
| Browser name
| "browserName"
| string
| Identifies the user agent.
|
| Browser version
| "browserVersion"
| string
| Identifies the version of the user agent.
|
| Platform name
| "platformName"
| string
| Identifies the system or operating system
of the endpoint node.
|
| Platform version
| "platformVersion"
| string
| Identifies the system version of the endpoint node.
|
| Accept SSL certificates
| "acceptSslCerts"
| boolean
| Indicates that the endpoint node
support invalid SSL certificates.
|
Implementations are free to use the capabilities dictionary
passed in the request to create a new session
to provide additional feature requests
from any of the remote ends, including the endpoint node.
Likewise the remote end may supply additional entries
on the capabilities object returned
from creating 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"
- The lowercase name of the user agent.
- "
browserVersion"
- The version of the user agent.
- "
platformName"
- The lowercase name of the platform.
- "
platformVersion"
- The version of the platform.
- "
acceptSslCerts"
- Be true if the User Agent can handle
invalid SSL certifications
else let it be false.
Let required capabilities be the result of getting a property
named requiredCapabilities from capabilities.
- If required capabilities is not a JSON Object,
set the value to an empty JSON Object.
Let desired capabilities be the result of getting a property
named desiredCapabilities from capabilities.
- If desired capabilities is not a JSON Object,
set the value to an empty JSON Object.
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.
- Increase k by 1.
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.
- Otherwise
Return error with error code invalid argument.
Sessions
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.
New Session
| 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"
- The value of session id.
- "
capabilities"
- The value of capabilities result.
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.
Navigation
The commands in this section allow navigation of
the current top-level browsing context to new URLs
and introspection of the document currently loaded in this browsing context.
For commands that cause a new document to load,
the point at which the command returns
is determined by the session’s page load strategy.
A value of normal causes the command
to return after the load event fires on the new page,
a value of eager causes it to return
after DOMContentLoaded fires,
and a value of none causes it to return immediately.
Navigation actions are also affected by the value of
the session page load timeout,
which determines the maximum time that commands will block
before returning with a timeout error.
Get
| HTTP Method |
Path Template |
| POST |
/session/{session id}/url |
The Get command is used
to cause the user agent to navigate
the current top-level browsing context a new location.
From a user’s point of view,
it is as if they have entered a URL into the address bar
of the browser’s chrome.
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 url be the result of
getting a property named "url"
from the parameters argument.
If url is undefined,
return error with error code invalid argument.
Navigate the current top-level browsing context to url.
If this navigation results in a HTTP 401 response,
the remote end must proceed with the steps below,
irrespective of how the authentication challenge is handled.
If the current session’s page loading strategy
is none jump to the next step in this overall set of steps.
Otherwise:
Let readiness target be "interactive"
if the current session’s page loading strategy is eager,
or "complete" if it is normal.
Wait for the current document readiness to reach readiness target,
or for the session page load timeout milliseconds to pass,
whichever occurs sooner.
If the previous step completed by the load timeout being reached,
and the browser is not currently displaying an alert,
return error with error code timeout.
Set the current browsing context
to the current top-level browsing context.
Return success with data null.
Figure out if next paragraph is actually required:
When a page contains a META tag with the "http-equiv" attribute set to "refresh",
a response MUST be returned if the timeout is greater than 1 second
and the other criteria for determining whether a page is loaded are met.
When the refresh period is 1 second or less
and the page loading strategy is "normal" or "conservative"
implementations MUST wait for the refresh to complete before responding.
Invalid SSL Certificates
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".
Elements
A web element is an abstraction used to identify an element
when it is transported across the protocol,
between remote- and local ends.
The web element identifier is a constant
with the string "element-6066-11e4-a52e-4f735466cecf".
Each element has an associated web element reference (a UUID)
that uniquely identifies the element across all browsing contexts.
The web element reference for every element
representing the same element is the same.
An ECMAScript Object represents a web element
if it has a web element identifier own property
holding a UUID value.
Each browsing context has an associated list of
known elements.
When the browsing context is discarded,
the list of known elements is discarded along with it.
To get a known element
by a UUID reference,
return success with the known element
which web element reference matches reference.
If there are none, return error
with error code no such element.
To create a web element reference
for an element:
For each known element
of the current browsing context’s known elements:
If known element equals element,
return success with known element’s web element reference.
Let new reference be the result of generating a 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:
- web element identifier
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.
Element Retrieval
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:
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.
CSS Selectors
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.
Link Text
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.
Partial Link Text
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.
XPath
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:
- Let using contain the Element Location Strategy.
If it is not a valid stategy:
- Set the HTTP Response status code to 500
- Let status be equal to
Invalid Selector
- Let value be a statement that the strategy is invalid. It MAY return a list of valid search strategies.
- Let value contain a string that will be passed to the Element Location Strategy call.
If value is an empty string or null:
- Set the HTTP Response status code to 500
- Let status be equal to Invalid Selector
- Let value to a stating that the strategy is invalid. It MAY return a list of valid search strategies.
- Call the relevant Element Location Strategy and return what is described in findElement() or findElements() WebDriver Command described below.
Find Element
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 |
- Let id be an identifier for a DOMElement returned from Element Location Strategy.
If a NodeList is returned, the first element in the NodeList MUST be used.
If id is empty:
- Let the HTTP response status code be 501
- Let status contain the error
no such element
- Let value contain the details of the search contained in using and value above.
If an error is returned from Element Location Strategy do the following.(todo describe how the error is returned)
- Let the HTTP response status code be 501
- Let status contain the error
invalid selector
- Let value contain the details of the search contained in using and value above.
- Let result be equal to
{"element-6066-11e4-a52e-4f735466cecf": id}
- Return result. The object returned will look like the following:
{
"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 |
- Let element be the start node for the query in the Element Location Strategy
- Let id be a unique identifier for the DOMElement returned from Element Location Strategy.
If a NodeList is returned, the first DOMElement in the NodeList MUST be used.
If id is empty:
- Let the HTTP response status code be 501
- Let status contain the error
no such element
- Let value contain the details of the search contained in using and value above.
If an error is returned from Element Location Strategy do the following.(todo describe how the error is returned)
- Let the HTTP response status code be 501
- Let status contain the error
invalid selector
- Let value contain the details of the search contained in using and value above.
- Let result be equal to
{"element-6066-11e4-a52e-4f735466cecf": id}
- Return result. The object returned will look like the following:
{
"value": {"element-6066-11e4-a52e-4f735466cecf": id}
}
Find Elements
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 |
- Let result be equal to an empty list
- Let queryResult be a NodeList returned from Element Location Strategy
- Repeat for every value in queryResult if not an empty set else return result
- Let id be the unique identifier for the DOMElement.
- Append
{"element-6066-11e4-a52e-4f735466cecf": id} to result
- Return result. The object returned will look like the following:
{
"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 |
- Let result be equal to an empty list.
- Let element be the start node for the query in the Element Location Strategy
- Let queryResult be a NodeList returned from Element Location Strategy
- Repeat for every value in queryResult if not an empty set else return result
- Let id be the unique identifier for the DOMElement.
- Append
{"element-6066-11e4-a52e-4f735466cecf": id} to result
- Return result. The object returned will look like the following:
{
"value": [{"element-6066-11e4-a52e-4f735466cecf": id}, {"element-6066-11e4-a52e-4f735466cecf": id}]
}
Element State
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.
getElementText()
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:
- Whitespace
- Any text that matches the ECMAScript regular expression class
\s.
- Whitespace excluding non-breaking spaces
- Any text that matches the ECMAScript regular expression
[^\S\xa0]
- Block level element
- A block-level element is one which is not a table cell, and whose effective CSS display style is not in the set ['inline', 'inline-block', 'inline-table', 'none', 'table-cell', 'table-column', 'table-column-group']
- Horizontal whitespace characters
- Horizontal whitespace characters are defined by the ECMAScript regular expression
[\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:
- if the element is in the
head element of the document, return an empty string otherwise carry on with the algorithm below.
- For each descendent of node, at time of execution, in order:
- Get whitespace, text-transform, and then, if descendent is:
- a node which is not displayed, do nothing
- a [[!DOM]] text node let
text equal the nodeValue property of descendent. Then:
- Remove any zero-width spaces (\u200b, \u200e, \u200f), form feeds (\f) or vertical tab feeds (\v) from
text.
- Canonicalize any recognized single newline sequence in
text to a single newline (greedily matching (\r\n|\r|\n) to a single \n)
- If the parent's effective CSS whitespace style is 'normal' or 'nowrap' replace each newline (\n) in
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 character
- Apply the parent's effective CSS text-transform style as per the CSS 2.1 specification ([[!CSS21]])
- If
last(lines) ends with a space character and text starts with a space character, trim the first character of text.
- Append
text to last(lines) in-place
- an element which is displayed. If the element is a:
- BR element: Push '' to
lines and continue
- Block-level element and if
last(lines) is not '', push '' to lines.
And then recurse depth-first to step 1 at the beginning of the algorithm with descendent set to the current element
- If element is a TD element, or the effective CSS display style is 'table-cell', and last(lines) is not '', and
last(lines) does not end with whitespace append a single space character to last(lines) [Note: Most innerText implementations append a \t here]
- If element is a block-level element: push '' to
lines
- The string MUST then have the white space normalised as defined in the [[!XPATH]] normalize-space function which is then returned.
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.
Element Interaction
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.
Element Clear
| 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:
- Match on element’s
type attribute:
- Checkbox state
- Radio Button state
Set the checkedness to false.
- Otherwise
Set the value to an empty string.
Fire a change event.
Return success with data null.
Document Handling
Executing Script
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:
- If value is
null,
or has type Boolean,
Number
or String:
Return success with data value.
- If value is an Object
that represents a web element:
Return the result of running
the deserialize the web element algorithm with object value.
- If value if value is an Array object
or an Object object:
Return the result of running the clone an object algorithm
with arguments value and seen,
and the JSON deserialize algorithm as the clone algorithm.
- Otherwise:
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:
- undefined
- null
Success with data null.
- type Boolean
- type Number
- type String
Success with data value.
- instance of element
Serialize the element with argument value.
- instance of NodeList
- instance of HTMLCollection
- instance of Array
- instance of Object
-
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.
- Otherwise
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:
- instance of
NodeList
- instance of
HTMLCollection
- instance of
Array
A new Array object,
which length property
has the result of getting a property named "length"
from value.
- Otherwise
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.
Execute Async Script
| 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.
Cookies
This section describes the interaction with cookies
as described in [[!RFC6265]].
A cookie is described in [[!RFC6265]]
by a name-value pair holding the cookie’s data,
followed by zero or more attribute-value pairs describing its characteristics.
The following table for cookie conversion
defines the cookie concepts relevant to WebDriver,
how these are referred to in [[!RFC6265]],
what keys they map to in a serialised cookie,
as well as the attribute-value keys needed
when constructing a list of arguments for creating a cookie.
For informational purposes,
the table includes a legend of whether the field is optional
in the serialised cookie structure provided to Add Cookie,
and a brief non-normative description of the field
and the expected input type of its associated value.
| Concept
| RFC 6265 Field
| JSON Key
| Attribute Key
| Optional
| Description
|
| Cookie name
| name
| "name"
|
|
| The name of the cookie.
|
| Cookie value
| value
| "value"
|
|
| The cookie value.
|
| Cookie path
| path
| "path"
| "Path"
| ✓
| The cookie path.
Defaults to "/"
if omitted when adding a cookie.
|
| Cookie domain
| domain
| "domain"
| "Domain"
| ✓
| The domain the cookie is visible to.
Defaults to the current browsing context’s
document’s URL domain
if omitted when adding a cookie.
|
| Cookie secure only
| secure-only-flag
| "secure"
| "Secure"
| ✓
| Whether the cookie is a secure cookie.
Defaults to false if omitted when adding a cookie.
|
| Cookie HTTP only
| http-only-flag
| "httpOnly"
| "HttpOnly"
| ✓
| Whether the cookie is an HTTP only cookie.
Defaults to false if omitted when adding a cookie.
|
| Cookie expiry time
| expiry-time
| "expiry"
| "Max-Age"
| ✓
| When the cookie expires,
specified in seconds since Unix Epoch.
Defaults to 20 years into the future
if omitted when adding a cookie.
|
A serialised cookie is a JSON Object structure
where a cookie’s [[!RFC6265]] fields
listed in the table for cookie conversion
is mapped using the JSON Key
and the associated field’s value from the cookie store.
The optional fields may be omitted.
To get all associated cookies to a document,
the user agent must return the enumerated set of cookies
that meet the requirements set out in the first step of the algorithm in [[RFC6265]] to
compute cookie-string for an ‘HTTP API’,
from the cookie store of the given document’s address.
When the remote end is instructed
to create a cookie,
this is synonymous to carrying out the steps described in [[!RFC6265]]
section 5.3,
under receiving a cookie,
except the user agent may not ignore the received cookie in its entirety
(disregard step 1).
To delete cookies given an optional filter argument
name that is a string:
For each cookie among all associated cookies of
the current browsing context’s active document, if:
- name is undefined
- name is equal to cookie name
Set the cookie expiry time
to a Unix timestamp in the past.
Add Cookie
| HTTP Method |
Path Template |
| POST |
/session/{session id}/cookie |
The Add Cookie command
adds a single cookie to the cookie store
associated with the active document’s address.
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 current browsing context’s document element
is a cookie-averse Document object,
return error with error code invalid cookie domain.
Let data be the result of getting a property
named "cookie" from the parameters argument.
If data is not a JSON Object
with all the required (non-optional) JSON keys
listed in the table for cookie conversion,
return error with error code unable to set cookie.
If cookie name or cookie value is null,
cookie domain is not equal to
the current browsing context’s active document’s domain,
cookie secure only or cookie HTTP only are not boolean types,
or cookie expiry time is not an integer type,
return error with error code unable to set cookie.
Create a cookie in
the cookie store associated with
the active document’s address
using cookie name name,
cookie value value,
and an attribute-value list of the following properties
from data:
- Cookie path
The value if the entry exists, otherwise "/".
- Cookie domain
The value if the entry exists,
otherwise the current browsing context’s
active document’s domain.
- Cookie secure only
The value if the entry exists, otherwise false.
- Cookie HTTP only
The value if the entry exists, otherwise false.
- Cookie expiry time
The value if the entry exists,
otherwise a Unix timestamp 20 years into the future from now.
If there is an error during this step,
return error with error code unable to set cookie.
Return success with data null.
Interactions
The Actions API gives you a mechanism to pipeline interaction actions to be
performed atomically by sending over
a JSON object that can then be used to dispatch commands.
The commands are then processed by the user agent,
allowing complex interactions to be created.
An activation trigger generated by the WebDriver API User need to 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 WebDriver instances cannot run in parallel.
Actions
Terminology
Section needs to be fleshed out more or moved to the top of the document with other terms.
low-level action The smallest operation an input source can do. These are used to build chains of actions. Example: keyDown
action chain A chain of low-level actions
input source The source from which the inputs will originate. MUST support 'keyboard' and 'pointer'.
Creating Actions
The Perform Actions command allows you to create sequential
interactions that can be sent over from the local end to the
remote end. This type of interactions allow emulations like drag and drop.
As well as handling a sequence of actions there is also the ability to create
parallel interactions. This allows complex interactions between
keyboard and mouse or the ability to have multiple touch points. See the example below.
The following table of actions enumerates all supported
commands
| HTTP Method |
Path Template |
| POST |
/session/{session id}/actions |
The remote end steps are:
Let actions be the result of getting a property
named "actions" from the parameters argument.
If actions is not a JSON List, return error code
with error code invalid argument.
Let length be the length of actions.
Let k be 0.
While k < length:
Let action be the entry in actions at
index k.
If action is a JSON List:
Let longest action sequence be the length of longest
action JSON List.
Let j be 0.
While j < longest action sequence:
Let parallel sources length be the length of actions.
Let i be 0.
While i < parallel sources length:
Let raw action be the entry at i
in action for entry j in actions
Append raw action to parallel actions.
Dispatch commands with argument action.
Return success with data null.
Releasing Actions
| HTTP Method |
Path Template |
| DELETE |
/session/{session id}/actions |
The Release Actions command is used to cancel all current
action chains. This is the equivalent of releasing all modifiers from
input sources.
The remote end steps are:
This needs to be completed.
Return success with data null.
Actions
Keyboard Actions
The keyUp command:
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 key be the result of getting a property
named "value".
If element id is undefined jump to step 9.
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.
If element is stale,
return error with error code stale element reference.
Run the focusing steps for the element.
Let active element be the active element of
the current browsing context’s document element.
Let key to type be the result of processing keys
with argument key.
Generate keyUp Keyboard Event against
active element for key to type.
The keyDown command:
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 key be the result of getting a property
named "value".
If element id is undefined jump to step 9.
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.
If element is stale,
return error with error code stale element reference.
Run the focusing steps for the element.
Let active element be the active element of
the current browsing context’s document element.
Let key to type be the result of processing keys
with argument key.
Generate keyDown Keyboard Event against
active element for key to type.
The steps for processing keystrokes are:
Run the focusing steps for the element.
Let modifiers be equal to:
control
- false
shift
- false
alt
- false
meta
- false
This needs to be a global
Let length be the length of keys.
Let k be 0.
While k < length
Let key be the entry in keys at
index k.
If key is equal to the Character Types
code set key to be equal to the
value Character Types Key.
If key is equal to Character Types Key
and Character Types Type is equal to
"Modifier" set modifiers key with name
equal to Key to true
Generate keyboard event order against WebElement
using key. Set the according modifier on Keyboard Event
from values in modifier.
Increase k by 1.
The steps for releasing modifiers are:
Set modifiers be equal to:
control
- false
shift
- false
alt
- false
meta
- false
Character Types
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 |
Pointer Actions
The pointerUp command:
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 element id is undefined jump to step 9.
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.
If element is stale,
return error with error code stale element reference.
Run the focusing steps for the element.
Let active element be the active element of
the current browsing context’s document element.
Scroll into view the active element .
Let x, y be the result of getting a property
named x and y.
If x or y are undefined:
Let visible width be
active element ’s bounding rectangle’s
(max(x coordinate, x coordinate + width dimension) –
the current browsing context’s innerWidth).
Let visible height be
active element’s bounding rectangle’s
(max(y coordinate, y coordinate + height dimension) –
the current browsing context’s innerHeight).
Let x be (visible width / 2.0).
Let y be (visible height / 2.0).
Let button be the result of getting a property
named "button".
Do we need symbols here?
Do we need to base events off source? E.g. if a pen?
Generate mouseup Mouse Event against
element.
What about touch/pointer events?
The pointerDown command:
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 element id is undefined jump to step 9.
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.
If element is stale,
return error with error code stale element reference.
Run the focusing steps for the element.
Let active element be the active element of
the current browsing context’s document element.
Scroll into view the active element .
Let x, y be the result of getting a property
named x and y.
If x or y are undefined:
Let visible width be
active element ’s bounding rectangle’s
(max(x coordinate, x coordinate + width dimension) –
the current browsing context’s innerWidth).
Let visible height be
active element’s bounding rectangle’s
(max(y coordinate, y coordinate + height dimension) –
the current browsing context’s innerHeight).
Let x be (visible width / 2.0).
Let y be (visible height / 2.0).
Let button be the result of getting a property
named "button".
Do we need symbols here?
Do we need to base events off source? E.g. if a pen?
Generate mousedown Mouse Event against
element.
What about touch/pointer events?
The pointerMove command:
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 element id is undefined jump to step 9.
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.
If element is stale,
return error with error code stale element reference.
Let x, y be the result of getting a property
named x and y.
If x or y are undefined:
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 innerHeight).
Let x be (visible width / 2.0).
Let y be (visible height / 2.0).
Move the pointer from it's last location based on the previous
Action Command to x, y generating
the relevant mouse events order.
What about Pointer/Touch Events?
The pointerCancel command:
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.
to be completed
User Prompts
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:
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:
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:
- dismiss state
Dismiss the current user prompt.
- accept state
Accept the current user prompt.
- missing value default state
- not in the table of simple dialogues
Return error with error code
unexpected alert open.
Return success.
Screen Capture
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:
- X coordinate
- rectangle x coordinate
- Y coordinate
- rectangle y coordinate
- Width
- paint width
- Height
- paint height
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 data url be a data: URL
representing file. [[!RFC2397]]
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.
Privacy
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.
Security
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]]
Element Displayedness
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 element is a [[!DOM]] text node,
return true.
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:
Run step 10 on the parent elements of parent, if any.
Return true.
Acknowledgements
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: