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.
Dependencies
This specification relies on several other underlying specifications.
- Web App Security
The following terms are defined
in the Content Security Policy Level 3 specification: [[!CSP3]]
- 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]]
The following attributes are defined
in the UI Events Code specification: [[!UIEVENTS-CODE]]
The following attributes are defined
in the UI Events Code specification: [[!UIEVENTS-KEY]]
- 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, values, and operations 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
To be HTTP compliant,
it is supposed that the implementation supports the relevant subsets of
[[!RFC7230]], [[!RFC7231]], [[!RFC7232]], [[!RFC7234]], and [[!RFC7235]].
The following terms are defined in the Cookie specification: [[!RFC6265]]
The following terms are defined in
the Hypertext Transfer Protocol (HTTP) Status Code Registry:
- The 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]]
- XPATH
The following terms are defined in the Document Object Model XPath standard [[!XPATH]]
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]].
Generating a UUID means Creating a
UUID From Truly Random or Pseudo-Random Numbers [[!RFC4122]],
and serializing it as appropriate for the callee.
The Unix Epoch
is a value that approximates the number of seconds
that have elapsed since the Epoch,
as described by The Open Group Base Specifications Issue 7
section 4.15 (IEEE Std 1003.1).
An Integer is a Number that is unchanged under
the ToInteger operation.
The initial value of a javascript property is the value
defined by the platform for that property i.e. the value it would
have in the absence of any shadowing by content script.
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.
Nodes
The standard defines four broad conformance classes,
known as node types:
- 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.
A remote end’s readiness state is
for each node type said to be:
- intermediary node
False if it is known to be in a state
in which attempting to create a new session would fail.
Otherwise true.
- endpoint node
False if the maximum active sessions
is equal to the length of the list of active sessions
or there is a current user prompt present.
Otherwise true.
If the intermediary node
is a multiplexer that manages
multiple endpoint nodes,
this might indicate its ability to purvey more sessions,
for example if it has hit its maximum capacity.
Protocol
WebDriver remote ends must provide
an HTTP compliant wire protocol
where the endpoints map to different commands.
As this standard only defines the remote end protocol,
it puts no demands to how local ends should be implemented.
Local ends are only expected to be compatible to the extent
that they can speak the remote end’s protocol;
no requirements are made upon their exposed user-facing API.
Algorithms
Various parts of this specification are written in terms of step-by-step algorithms.
The details of these algorithms do not have any normative significance;
implementations are free to adopt any implementation strategy
that produces equivalent output to the specification.
In particular algorithms in this document are optimised
for readability rather than performance.
Where algorithms that return values are fallible,
they are written in terms of returning either
success or error.
A success value has an associated data field
which encapsulates the value returned,
whereas an error response has an associated error code.
When calling a fallible algorithm, the construct
"Let result be the result of trying to
call algorithm" is equivalent to "Let temp be
the result of calling algorithm. If temp is
an error return temp, otherwise
let result be temp's data.
The result of getting a property
with name from an Object is defined as
the result of calling the [[\GetOwnProperty]]
internal method of with property name name.
The result of setting a property
with name and value to an Object is defined
as calling the [[\Put]] internal method with name name
and value value.
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
- name
message
- message
stacktrace
- 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 a JSON Object with a key value
set to the JSON serialisation of data.
Let response bytes be the byte sequence resulting
from serializing response according to the rules in [[!RFC7230]].
Write response bytes
to the connection.
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 occurred;
and stacktrace
, containing an implementation-defined string
with a stack trace report of the active stack frames at the time when the error occurred.
The following table lists each error code,
its associated HTTP status,
JSON error
code,
and a non-normative description of the error.
The error response data for a particular error code
is the values of the HTTP Status
and JSON Error Code columns for the row corresponding to that error code.
Error Code
| HTTP Status
| JSON Error Code
| Description
|
element not selectable
| 400
| element not selectable
| An attempt was made to select an element that cannot be selected.
|
element not interactable
| 400
| element not interactable
| An element command could not be completed
because the element is not
pointer- or
keyboard interactable.
|
insecure certificate
| 400
| insecure certificate
| Navigation caused
the user agent to hit a certificate warning,
which is usually the result of an expired or invalid TLS certificate.
|
invalid argument
| 400
| invalid argument
| The arguments passed to a command
are either invalid or malformed.
|
invalid cookie domain
| 400
| invalid cookie domain
| An illegal attempt was made to set a cookie
under a different domain than the current page.
|
invalid coordinates
| 400
| invalid coordinates
| The coordinates provided to an interactions operation are invalid.
|
invalid element state
| 400
| invalid element state
| 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 cookie
| 404
| no such cookie
| No cookie matching the given path name
was found amongst the associated cookies
of the current browsing context’s active document.
|
no such element
| 404
| no such element
| An element could not be located on the page
using the given search parameters.
|
no such frame
| 400
| no such frame
| A request to switch to a frame
could not be satisfied because the frame could not be found.
|
no such window
| 400
| no such window
| A request to switch to a window
could not be satisfied because the window could not be found.
|
script timeout
| 408
| script timeout
| A script did not complete before its timeout expired.
|
session not created
| 500
| session not created
| A new session could not be created.
|
stale element reference
| 400
| stale element reference
| 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.
|
Protocol Extensions
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 command prefix,
followed by "/
",
and the extension command’s name.
The extension command URL,
along with the HTTP method and extension command,
is added to the table of endpoints
and thus follows the same rules for request routing
as that of other built-in commands.
An extension command prefix
is a lowercased ASCII string that forms a URL path element,
separating extension commands from other commands
in order to avoid potential resource conflicts with other implementations.
It is suggested that vendors use their vendor prefixes
without additional characters as outlined in [[CSS21]],
notably in section 4.1.2.2 on vendor keywords,
as the name for this path element,
and include a vendor-chosen UA identifier.
Remote ends may also introduce
extension capabilities
that are extra capabilities
used to provide configuration or fulfill other vendor-specific needs.
Extension capabilities’ key
must contain a ":
" (colon) character,
denoting an implementation specific namespace.
The value can be arbitrary JSON types.
As with extension commands,
it is suggested that the key used to denote
the extension capability namespace
is based on the vendor keywords
listed in [[!CSS21]]
and preceeds the first ":
" character in the string.
Capabilities
WebDriver capabilities are used to communicate the features
supported by a given implementation. The local end may use capabilities
to define which features it requires the remote end to satisfy when
creating a new session. Likewise, the remote end uses capabilities
to describe the full feature set for a session.
The following table provides an overview of the standard capabilities that
each implementation MUST support. An implementation MAY define
additional capabilities, although it is RECOMMENDED that custom
capabilities prepend the capability key with a vendor prefix, as outlined in
[[CSS21]].
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 whether untrusted and self-signed SSL certificates are
implicitly trusted on navigation for the duration of the
session.
|
Page Load Strategy
| "pageLoadStrategy "
| string
| Defines the current session’s page load strategy.
|
Proxy Configuration
| "proxy "
| JSON Object
| Describes a session's proxy configuration.
|
Session Timeouts Configuration
| "timeouts "
| JSON Object
| Describes the timeouts imposed on certain session operations.
|
Proxy
The proxy configuration capability
is a JSON Object nested
within the primary capabilities.
Implementations may define additional proxy configuration options,
but they must not alter the semantics of those listed below.
Key
| Value Type
| Description
|
"proxyType "
| string
| Indicates the type of proxy configuration. This value SHOULD be one
of the following: "pac ", "noproxy ",
"autodetect ", "system ", or "manual ".
|
"proxyAutoconfigUrl "
| string
| Defines the URL for a proxy auto-config file. [URL]
This property SHOULD only be set when the "proxyType " is
equal to "pac ".
|
"ftpProxy "
| string
| Defines the proxy hostname for FTP traffic. Alternatively, an
implementation MAY accept a hostname and port through this property.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"ftpProxyPort "
| number
| Defines the proxy port for FTP traffic.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"httpProxy "
| string
| Defines the proxy hostname for HTTP traffic. If a hostname and port
is passed through this property, set "httpProxy " to the hostname
and "httpProxyPort " to the port.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"httpProxyPort "
| number
| Defines the proxy port for HTTP traffic. If "httpProxyPort "
is defined in "httpProxy " and from this property, return error with error code invalid argument.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"sslProxy "
| string
| Defines the proxy hostname for encrypted SSL traffic. If a hostname and port
is passed through this property, set "sslProxy " to the hostname
and "sslProxyPort " to the port.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"sslProxyPort "
| number
| Defines the proxy port for ssl traffic. If "sskProxyPort "
is defined in "sslProxy " and from this property, return error with error code invalid argument.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"socksProxy "
| string
| Defines the proxy hostname for a SOCKS proxy. [[RFC1928]]
Alternatively, an implementation MAY accept a hostname and port
through this property.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"socksProxyPort "
| number
| Defines the proxy port for a SOCKS proxy. [[RFC1928]]
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"socksVersion "
| number
| Defines the SOCKS proxy version.
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"socksUsername "
| string
|
Defines the username used when authenticating with a SOCKS proxy. [[RFC1928]]
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
|
"socksPassword "
| string
|
Defines the password used when authenticating with a SOCKS proxy. [[RFC1928]]
This property SHOULD only be set when the "proxyType " is
equal to "manual ".
This property MUST NOT be set by a remote end when returning
capabilities to the local end.
|
Processing Capabilities
When processing capabilities with argument parameters,
the endpoint node must take the following steps:
Let capabilities request be the result of getting a property
named "capabilities
" from parameters.
If capabilities request is not a JSON object,
return error with error code invalid argument.
Let required capabilities be the result of getting a property
named "alwaysMatch
" from capabilities request.
If required capabilities is null or undefined,
set the value to an empty JSON Object.
If required capabilities is not a JSON Object,
return error with error code invalid argument.
Let desired capabilities be the result of getting a property
named "firstMatch
" from capabilities request.
If desired capabilities is null or undefined,
set the value to a JSON List with a single entry of an empty JSON Object.
If desired capabilities is not a JSON List,
return error with error code invalid argument.
Let length be the length of desired capabilities.
Let k be 0.
Let matched capabilities be null.
While k < length and
matched capabilities is null:
Let dc be the entry in desired capabilities at
index k.
If dc is not a JSON Object,
return error with error code invalid argument.
Let merged capabilities be the result of
merging capabilities with required capabilities and
dc as arguments.
If merged capabilities is an error,
return the merged capabilities error.
Set matched capabilities to the result of
matching capabilities with merged capabilities as an
argument.
Increment k by 1.
Return matched capabilities.
When merging capabilities with JSON Object arguments
primary and secondary, an endpoint node
must take the following steps:
Let result be a JSON Object with the same entries as
primary.
If secondary is null or undefined, return
result.
Let k be 0.
Let num entries be the number of entries in
secondary.
While k < num entries:
Let entry be the entry in secondary at index
k.
If the name of entry is also the name of an entry in
result,
return error with error code invalid argument.
Otherwise, add entry to result.
Increment k by 1.
Return result.
When matching capabilities with JSON Object argument
capabilities, an endpoint node must take the following
steps:
Let matched capabilities be a JSON Object
with the following entries:
- "
browserName
"
- Lowercase name of the user agent.
- "
browserVersion
"
- The user agent version, as a string.
- "
platformName
"
- Lowercase name of the current platform.
- "
platformVersion
"
- The platform version, as a string.
- "
acceptSslCerts
"
- Boolean initially set to false, indicating the session will not implicitly trust
untrusted or self-signed SSL certificates on navigation.
Let capabilities length be the number of entries in capabilities.
Let k be 0.
While k < capabilities length:
Let capability name be the name of the entry at index
k in capabilities.
Let capability value be the value of the entry at index
k in capabilities.
Switch on capability name:
- "
browserName
"
-
If capability value is null, undefined,
or equal to the string "*
", it is considered
a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to
the "browserName
" entry in matched capabilities,
return null.
- "
browserVersion
"
-
If capability value is null, undefined,
or equal to the string "*
", it is to be considered
a match for the entry in matched capabilities.
Otherwise, compare capability value to the
"browserVersion
" entry in matched capabilities
using an implementation-defined comparison algorithm. The comparison
is to accept a capability value that places
constraints on the version using the "<
",
"<=
", ">
", and ">=
"
operators.
If the two values do not match, return null.
Version comparison is left as an implementation detail
since each user agent will likely have conflicting methods of encoding
the user agent version and standardizing these schemes is beyond the
scope of this specification.
- "
platformName
"
-
If capability value is null, undefined,
or equal to the string "*
", it is considered
a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to
the "platformName
" entry in
matched capabilities, return null.
- "
platformVersion
"
-
If capability value is null, undefined,
or equal to the string "*
", it is considered
a match for the entry in matched capabilities.
Otherwise, if capability value is not a string equal to
the "platformVersion
" entry in
matched capabilities, return null.
- "
acceptSslCerts
"
-
If capability value is not a boolean,
return error with error code invalid argument.
If capability value is true
and the
endpoint node does not support insecure
SSL certificates, return null.
Otherwise, set the "acceptSslCerts
" entry in
matched capabilities to capability value.
- "
pageLoadStrategy
"
-
If capability value is not a string,
return error with error code invalid argument.
Otherwise, set the "pageLoadStrategy
" entry in
matched capabilities to capability value.
- "
proxy
"
-
If capability value is not a valid Proxy Configuration,
return error with error code invalid argument.
If the endpoint node does not support the proxy configuration
defined in capability value, return null.
Otherwise, set the "proxy
" entry in
matched capabilities to capability value.
- "
timeouts
"
-
If capability value is not a valid
Session Timeouts Configuration object,
return error with error code invalid argument.
Otherwise, set the "timeouts
" entry in
matched capabilities to capability value.
- Otherwise
-
If capability name is not recognized by the endpoint node,
return null.
Let processed value be the result of implementation
specific steps to match on capability name with
capability value.
If processed value is an error,
return processed value.
Otherwise, create a new entry in matched capabilities with
name capability name and value processed value.
Return matched capabilities.
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, and otherwise
is the top-level browsing context of the current browsing
context.
A session has an associated session script timeout
that specifies a time to wait for scripts to run.
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 retreiving 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 secure SSL state
that indicates whether untrusted or self-signed SSL certificates
should be trusted for the duration of the WebDriver session.
If it is unset, this indicates that certificate- or SSL errors
that occur upon navigation should be suppressed.
The state can be unset by providing
an "acceptSslCerts
" capability with the value true.
Unless stated otherwise, it is set.
A session has an associated user prompt handler.
A session has an associated input state.
A session has an associated input cancel list.
When asked to close the session,
a remote end must take the following steps:
Set the webdriver-active flag to false.
Close any top-level browsing contexts
associated with the session,
without prompting to unload.
Remove the current session from active sessions.
Perform any implementation-specific cleanup steps.
Closing a session might cause the associated browser process to be killed.
It is assumed that any implementation-specific cleanup steps
are performed after the response has been sent back to the client
so that the connection is not prematurely closed.
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,
there is a problem processing the given capabilities,
or the provisioning of a remote end is impossible,
a session not created error is returned.
If the remote end is an intermediary node,
it MAY use the result of the processing capabilities algorithm
to route the new session request to the appropriate endpoint node.
An intermediary node MAY also define custom capabilities
to assist in this process, however, these capabilities MUST NOT be
forwarded to the endpoint node. Furthermore, if the
intermediary node requires additional information unrelated to user
agent features, it is RECOMMENDED that this information be passed as
top-level parameters and not part of the requested capabilities. An
intermediary node MAY forward custom, top-level parameters
(i.e. non-capabilities) to subsequent remote end nodes.
The remote end steps are:
If the remote end is an intermediary node,
take implementation-defined steps that either result in
returning an error with error code session not created,
or in returning a success with data
that is isomorphic to that returned by remote ends
according to the rest of this algorithm.
If the maximum active sessions is equal to
the length of the list of active sessions,
return error with error code session not created.
If there is a current user prompt,
return error with error code session not created.
Let capabilities result be the result of
processing capabilities with parameters as an argument.
If capabilities result is an error,
return error with error code session not created and
the error data from capabilities result.
If capabilities result is null,
return error with error code session not created.
Let capabilities be capabilities result’s data.
Let session id be the result of generating a UUID.
Let session be a new session
with the session ID of session id.
Set the current session to session.
Append session to active sessions.
Let body be a JSON Object initialised with:
sessionId
- session id
capabilities
- capabilities result
Initialise the following from capabilities:
Let strategy be the result of getting property
"pageLoadStrategy
" from capabilities.
If strategy is a string, set the current session's
page loading strategy to strategy.
Otherwise, set the page loading strategy to normal.
Let proxy be the result of getting property
"proxy
" from capabilities.
If proxy is a Proxy Configuration object, take
implementation-defined steps to set the user agent proxy using the
extracted proxy configuration. If the defined proxy cannot be
configured,
return error with error code session not created.
Let timeouts be the result of getting property
"timeouts
" from capabilities.
If timeouts is a Session Timeouts Configuration
object:
If timeouts has a numeric property with key
"implicit
", set the current session's
session implicit wait timeout to the value of property
"implicit
". Otherwise, set the
session implicit wait timeout to 0 (zero) milliseconds.
If timeouts has a numeric property with key
"page load
", set the current session's
session page load timeout to the value of property
"page load
". Otherwise, set the
session page load timeout to 300,000 milliseconds.
If timeouts has a numeric property with key
"script
", set the current session's
session script timeout to the value of property
"script
". Otherwise, set the
session script timeout to 30,000 milliseconds.
Apply changes to the user agent for any implementation defined
capabilities selected during the processing capabilities step.
Set the webdriver-active flag to true.
Return success with data body.
Status
HTTP Method |
Path Template |
GET |
/status |
The Status command
returns information about whether a remote end
is in a state in which it can create new sessions
and can additionally include arbitrary meta information
that is specific to the implementation.
The readiness state is represented
by the ready
property of the body,
which is false if an attempt to create a session
at the current time would fail.
However, the value true does not guarantee
that a new session request will succeed.
Implementations may optionally include
additional meta information as part of the body,
but the top-level properties
ready
and message
are reserved and must not be overwritten.
The remote end steps are:
Let body be a new JSON Object
with the following properties:
ready
The remote end’s readiness state.
message
An implementation-defined string
explaining the remote end’s readiness state.
Return success with data body.
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 loading strategy.
The normal state causes it
to return after the load event fires on the new page,
eager causes it to return
after the DOMContentLoaded
event fires,
and 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.
The following is the table of page load strategies
that links the pageLoadingStrategy
capability keyword
to a page loading strategy state,
and shows which document readiness state
that corresponds to it:
Keyword
| Page load strategy state
| Document readiness state
|
"none "
| none
|
|
"eager "
| eager
| "interactive "
|
"normal "
| normal
| "complete "
|
When asked to wait for navigation to complete,
run the following steps:
If the current session has a page loading strategy:
Let readiness target be the document readiness state
tied to the current session’s page loading strategy,
which can be found in the table of page load strategies.
Wait for the the current browsing context’s
document readiness state
to reach readiness target,
or for the session page load timeout to pass,
whichever occurs sooner.
This can typically be implemented
by registering an event handler for
the DOMContentLoaded
event,
and comparing the document readiness state
against readiness target whenever it fires.
When it reaches its designated readiness target,
return from the overall step of this algorithm.
If the previous step completed
by the load timeout being reached
and the browser is does not have an active user prompt,
return error with error code timeout.
When asked to run the post-navigation checks,
run the substeps of the first matching statement:
- response is a network error
Return error with error code unknown error.
- response be blocked by content security policy
If the current session’s secure SSL state is disabled,
take implementation specific steps to ensure
the navigation is not aborted
and that the untrusted- or invalid TLS certificate error
that would normally occur under these circumstances,
are suppressed.
Otherwise return error with error code insecure certificate.
- response’s HTTP status code is 401
- Otherwise
Irrespective of how a possible authentication challenge is handled,
return success with data null.
Command Contexts
Many WebDriver commands happen in the context of either
the current browsing context or current top-level browsing context.
The current top-level browsing context is represented in the protocol
by its associated window handle.
A top-level browsing context is selected
using the Switch To Window command.
Once this is done, a specific browsing context can be selected
using the Switch to Frame command.
The use of the term “window” to
refer to a top-level browsing context
is legacy and doesn’t correspond with either
the operating system notion of a “window”
or the DOM Window
object.
The top-level browsing context is said
to be no longer open if it has been discarded.
Each browsing context has an associated
window handle (string)
uniquely identifying it.
It must not be "current
".
The web window identifier
is the string constant "window-fcc6-11e5-b4f8-330a88ab9d7f
".
The web frame identifier
is the string constant "frame-075b-4da1-b6ba-e579c2d3230a
".
The JSON serialisation of the WindowProxy
object
is the JSON Object obtained by applying the following algorithm
to the given WindowProxy
object window:
Let identifier be the web window identifier
if the associated browsing context of window
is a top-level browsing context.
Otherwise let it be the web frame identifier.
Return a JSON Object initialised with the following properties:
- identifier
Associated window handle
of the window’s browsing context.
In accordance with
the focus
section of the [[!HTML]] specification,
commands are unaffected by whether
the operating system window has focus or not.
Get Window Handles
HTTP Method |
Path Template |
GET |
/session/{session id}/window/handles |
The Get Window Handles command
returns a list of window handles
for every open top-level browsing context.
The order in which the window handles are returned is arbitrary.
The remote end steps are:
Let handles be a JSON List.
For each top-level browsing context in the remote end,
push the associated window handle onto handles.
- Return success with data handles.
Resizing and Positioning Windows
WebDriver provides commands
for interacting with the operating system window
containing the current top-level browsing context.
Because different operating system’s window managers provide different abilities,
not all of the commands in this section can be supported by all remote ends.
Where a command is not supported,
an unsupported operation error is returned.
A top-level browsing context’s window size
are the outer dimensions, including any browser chrome
externally drawn window decorations in CSS reference pixels
of the operating system window corresponding to it.
Its JSON representation is the following:
- "
width
"
- Width of the top-level browsing context’s outer dimensions,
including any browser chrome and externally drawn window decorations
in CSS reference pixels.
- "
height
"
- Height of the top-level browsing context’s outer dimensions,
including any browser chrome and externally drawn window decorations
in CSS reference pixels.
In some user agents the operating system’s
window dimensions including decorations,
are provided by the proprietary window.outerWidth
and window.outerHeight
[[!DOM]] properties.
A top-level browsing context’s window position
is defined as a dictionary of the screenX and screenY attributes
on the WindowProxy
it corresponds to.
Its JSON representation is the following:
- "
x
"
- screenX attribute of the
WindowProxy
for the current top-level browsing context.
- "
y
"
- screenY attribute of the
WindowProxy
for the current top-level browsing context.
Set Window Size
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.
If the properties width
or height
are missing from the parameters argument,
or they are not integers, or less than 0 or greater than 264 – 1,
return error with error code invalid argument.
Let width be the result of
getting a property named width
from the parameters argument.
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 the JSON serialisation
of the current top-level browsing context’s window size.
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 UUID.
Set element’s web element reference
to new reference.
Append element to
the known elements of the current browsing context.
Return success with data
element’s web element reference.
The JSON serialisation of an element
is a JSON Object where the web element identifier key
is mapped to the element’s web element reference.
When required to deserialise a web element
by a JSON Object object that represents a web element:
If object has no own property web element identifier,
return error with error code invalid argument.
Let reference be the result of
getting
the web element identifier property
from object.
Let element result be the result of
getting a known element by
UUID reference.
If element result is a success,
let element be element result’s data.
Otherwise, return element result.
Return success with data element.
A stale element is a reference to a node
that has been disconnected from the current browsing context’s DOM.
To determine if an element is stale,
run the following substeps:
Let document be
the current browsing context’s document element.
If element is not in the same tree as document,
return true.
Otherwise return false.
An element is
scrolled into view
by calling scrollIntoView().
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,
Find Elements,
Find Element From Element,
and Find Elements From Element commands
allow lookup of individual elements and collections of elements.
Element retrieval searches are performed
using pre-order traversal of the document’s nodes
that match the provided selector’s expression.
Elements are serialised
and returned as web elements.
When required to find with arguments
all, start node, using and value,
a remote end must run the following steps:
Let location strategy be equal to using.
Let selector be equal to value.
Let result be an empty JSON List.
Let elements returned be the result
of the relevant element location strategy
call with arguments all, start node, .
If elements returned is an empty NodeList, match on all:
- true
- Return success with empty JSON List.
- false
- Return error no such element.
DOMException
SyntaxError
XPathException
- Return error invalid selector.
Let result be an empty JSON List.
For each element in elements returned:
Return result.
Locator Strategies
An element location strategy
is an enumerated attribute
deciding what technique should be used
to search for elements in the current browsing context.
The following table lists the keywords and states defined for this attribute:
Partial Link Text
The Partial link text strategy
is very similar to the Link Text strategy,
but rather than matching the entire string,
only a substring needs to match.
That is, return all a
elements
with rendered text that contains the selector expression.
To find a web element
with the Partial Link Text strategy
the following steps need to be completed:
Let elements be the result of calling querySelectorAll,
with argument a
elements,
with the context object equal to the start node.
Let result be an empty NodeList.
For each element in elements:
Let rendered text be the result
of getting innerText
of element.
If rendered text contains selector,
append element to result.
Return result.
XPath
To find a web element with
the XPath Selector strategy
the following steps need to be completed:
Return the result of calling evaluate
,
with arguments selector, context object
equal to the start node.
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 interactable,
return error with error code element not interactable.
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 deserialise
with argument value,
and optional argument seen,
a remote end must run the following steps:
If seen was not provided,
let seen be an empty set.
Jump to the first appropriate step below:
- 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 deserialised
web element from 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 deserialise 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
If the element is stale,
return error with error code stale element reference.
Otherwise, return success
with the JSON serialisation
of the web element value.
- a
WindowProxy
object
If the associated browsing context
of the WindowProxy
object
in value has been discarded,
return error with error code stale element reference.
Otherwise return success
with the JSON serialisation
of 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.
The rules to execute a function body are as follows.
The algorithm will return success
with the JSON representation
of the function’s return value,
or an error if the evaluation of the function
results in a JavaScript exception being thrown
or at any point during its execution
an unhandled user prompt appears.
If at any point during the algorithm a user prompt appears,
the user prompt handler must be invoked.
If its return value is an error,
it must immediately return with that error
and abort all subsequent substeps of this algorithm.
Let window be the associated window
of the current browsing context’s active document.
Let environment settings be
the environment settings object for window.
Let script environment be
the script execution environment
for JavaScript obtained from environment settings.
If body is not parsable as a FunctionBody
or if parsing detects an early error,
return error with error code javascript error.
If body begins with a directive prologue
that contains a use strict directive
then let strict be true,
otherwise let strict be false.
Using the script execution environment script environment,
let function be the result of
calling create a function object with parameter list of
an empty List,
body body,
scope of the global environment,
and strict flag strict.
Let script be a new script.
Let script’s code entry-point
be function.
Let script’s settings object object
be script settings.
Invoke the [[\Call]] internal method of function,
providing window as the this value
and parameters as the argument values.
If doing so does not produce an exception,
let result be success with data set
to the return value from this function call.
Otherwise let result be error
with error code javascript error.
If result is an error, return result.
Otherwise let json data be a JSON clone
of result’s data.
Return success with data json data.
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.
Return success with data value.
The execute async script callback algorithm
is initialized with a single argument webdriver callback state.
It defines a function with a single optional argument result.
When this function is called, the following steps are run:
If webdriver callback state is not in the unset
state,
return undefined
.
If result is not present,
let result be null
.
Let json result be a JSON clone
of result.
Set the webdriver callback state
to set
with data json result.
Return undefined
.
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 invalid argument.
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,
or it less than 0 or greater than 264 – 1,
return error with error code invalid argument.
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.
Actions
Expand these examples
The Actions API provides a low-level interface
for providing virtualised device input to the web browser.
Conceptually, the actions API divides time into a series of ticks.
The local end sends a series of actions
which correspond to the change in state, if any,
of each input device during each tick.
For example, pressing a key
is represented by an action chain
consisting of a single key input device and two ticks,
the first containing a keyDown action,
and the second a keyUp action,
whereas a pinch-zoom input is represented
by an action chain consisting of a three ticks
and two pointer input devices of type touch,
each performing a sequence of actions pointerDown,
followed by pointerMove, and then pointerUp.
Move this note:
Terminology
An input source is a virtual device providing input
events. Each input source has an associated input id,
which is a string that identifies the particular device, and
a source type which determines the kind of input the
device can provide. As with real devices, virtual devices are
stateful; this state is recorded in an input device state object
associated with each device.
A null input source is an input source that
is not associated with a specific physical device. Null input
sources support the following actions:
Action
| Non-normative Description
|
pause |
Used with an integer argument to specify the duration of
a tick, or as a placeholder to indicate that
an input source does nothing during a particular
tick. |
A key input source is a input source that is
associated with a keyboard-type device. A key input source
supports the same pause action as a null input
source plus the following actions:
Action
| Non-normative Description
|
keyDown |
Used to indicate that a particular key should be held down. |
keyUp |
Used to indicate that a depressed key should be released. |
A pointer input source is an input source
that is associated with a pointer-type input device. Such an
input source has an associated subtype specifying exactly which
kind of pointing device it is associated with. A pointer input
source supports the same pause action as a null input
source plus the following actions:
Action
| Non-normative Description
|
pointerDown |
Used to indicate that a pointer should be depressed in
some way e.g. by holding a button down (for a mouse) or by
coming into contact with the active surface (for a touch or
pen device). |
pointerUp |
Used to indicate that a pointer should be released in
some way e.g. by releasing a mouse button or moving a pen
or touch device away from the active surface. |
pointerMove |
Used to indicate a location on the screen that a
pointer should move to, either in its active (pressed) or
inactive state. |
pointerCancel |
Used to cancel a pointer action. |
A tick is the basic unit of time over which actions
can be performed. During a tick, each input source has an assigned
action — possibly a noop pause action — which may
result in changes to the user agent internal state and eventually
cause DOM events to be fired at the page. The next tick begins
after the user agent has had a chance to process all DOM events
generated in the current tick.
Waiting
asynchronously means waiting for something to occur whilst
allowing the browser to continue processing
the event
loop.
At the lowest level, the behaviour of actions is intended to
mimic the remote end's behaviour with an actual input device as
closely as possible, and the implementation strategy may involve
e.g. injecting synthesized events into a browser event
loop. Therefore the steps to dispatch an action will inevitably
end up in implementation-specific territory. However there are
certain content observable effects that must be consistent across
implementations. To accomodate this, the specification requires
that remote ends perform
implementation-specific action dispatch steps, along with a
list of events and their properties. This list is not
comprehensive; in particular the default action of the input
source may cause additional events to be generated depending on
the implementation and the state of the browser (e.g. input events
relating to key actions when the focus is on an editable element,
scroll events, etc.).
Input State
Each session has an associated input state
object. This is a map between input id and the device
state for that input source, with one entry for each
active input source.
Each session also has an associated input cancel
list, which is a list of actions. This list is used to
manage dispatching events when resetting the state of the input
sources. For simplicity the algorithms described here only
append actions to the list and rely on the fact that the reset
operations are idempotent.
A null input source has a corresponding null input
state object. This is always an empty object.
A key input source has a corresponding key input
state object. This is an object with a
property, pressed
, which is a set of strings
representing currently pressed keys and
properties alt
, shift
, ctrl
,
and meta
, which are Booleans.
When required to create a new key input state
object, an implementation must return a key input
state object with the pressed
property set to the
empty set
and alt
, shift
, ctrl
,
and meta
all set to false
.
A pointer input source has a corresponding pointer
input state object. This consists of a subtype
property, which has the possible
values "mouse"
, "pen"
,
and "touch"
, a primary
property which is
a boolean, a pressed
property which is a set of
unsigned integers, an x
property which is an unsigned
integer, and a y
property which is an unsigned
integer.
When required to create a new pointer input state
object with arguments subtype and primary an
implementation must return a pointer input state object
with subtype
set
to subtype, primary
set
to primary, pressed
set to an empty set
and both x
and y
set to 0
.
The corresponding input state type for a
label action type is given by the following table:
Processing Actions Requests
The algorithm for extracting an action chain from a request takes the
JSON object representing an action chain, validates the input, and
returns a data structure that is the transpose of the input JSON,
such that the actions to be performed in a single tick are grouped
together.
When required to extract an action chain with
argument parameters, a remote end must run the
following steps:
If the current browsing context is no longer open,
return error with error code no such window.
Let actions be the result of getting a
property from parameters named actions
.
If actions is undefined or
is not an Array, return error with error
code invalid argument.
Let actions by tick be an
empty List.
For each value action sequence corresponding
to an indexed property in actions:
Let input source actions be the result
of trying to process a input source action
sequence with argument action sequence.
For each action in input source actions:
Let i be the zero-based index
of action in input source
actions.
If the length of actions by tick
is less than i + 1, append a
new List to actions by tick.
Append action to the List
at index i in actions by
tick.
Return success with data actions by
tick.
When required to process a input source action sequence, with
argument action sequence, a remote end must run the
following steps:
Let type be the result of getting a property
named type
from actions sequence.
If type is
not "key"
, "pointer"
,
or "none"
, return an error with
error code invalid argument.
Let id be the result of getting a
property named id
from actions
sequence.
If id is undefined
let id be a new UUID. Otherwise
if id is not a String return error
with error code invalid argument.
Let action items be the result
of getting a property named actions
from action sequence.
If action items is not an Array,
return error with error code invalid argument.
If type is equal to "pointer"
,
let parameters data be the result of getting a
property named parameters
from action sequence. Then let parameters be
the result of trying to process pointer
parameters with argument parameters
data.
If the current session's input state
already has an entry corresponding to input
id id and that entry has a type different
to the corresponding input state type
for type, then return error with
error code invalid argument.
Let actions be a new list.
For each action item in action
items:
If action item is not an Object
return error with error
code invalid argument.
If type is "none"
let action be the result of trying
to process a null action with
parameters id, and action item.
Otherwise, if type is "key"
let action be the result of trying
to process a key action with
parameters id, and action item.
Otherwise, if type
is "pointer"
let action be the
result of trying to process a pointer
action with parameters id, parameters,
and action item.
Append action to actions.
Return success with data actions.
The default pointer parameters consist of an object
with property pointerType
set to mouse
and primary
set to true
.
When required to process pointer parameters with
argument parameters data, a remote end must perform the
following steps:
Let parameters be the default pointer
parameters.
If parameters data is undefined,
return success with data parameters.
If parameters data is not an Object
return error with error code invalid argument.
Let pointer type be the result of getting
a property named pointerType
from parameters data.
If pointer type is not undefined:
If pointer type does not have one of the
values "mouse"
, "pen"
,
or "touch"
return error with
error code invalid argument.
Set the pointerType
property
of parameters to pointer type.
Let primary be the result of getting a
property named primary
from parameters
data.
If primary is not undefined:
If primary is not a Boolean
return error with error code invalid
argument.
Set the primary
property
of parameters to primary.
Return success with data parameters.
A action object constructed with
arguments id, type, and subtype
is an object with property id
set to id,
type
set to type
and subtype
set to subtype. Specific
action objects have further properties added by other algorithms
in this specification.
When required to process a null action with
arguments id and action item, a remote end
must perform the following steps:
Let subtype be the result of getting a property
named type
from action item.
If subtype is not "pause"
return error with error code invalid argument.
Let action be an action object
constructed with arguments id,
"none"
, and subtype.
Let result be the result of trying
to process a pause action with arguments action
item, and action.
Return result.
When required to process a key action with
arguments id and action item, a remote end
must perform the following steps:
Let subtype be the result of getting a property
named type
from action item.
If subtype is not one of the
values "keyUp"
, "keyDown"
,
or "pause"
, return an error with
error code invalid argument.
Let action be an action object
constructed with arguments id,
"key"
, and subtype.
If subtype is "pause"
;
let result be the result of trying to
process a pause action with arguments action
item, and action, and return
result.
Let key be the result of getting a property
named value
from action item.
If key is not a String containing a
single unicode codepoint or grapheme
cluster? return error with error
code invalid argument.
Set the value
property on action
to key.
Return success with data action.
When required to process a pointer action with
arguments id, parameters, and action
item, a remote end must perform the following steps:
Let subtype be the result of getting a property
named type
from action item.
If subtype is not one of the
values pause
, "pointerUp"
,
"pointerDown"
, "pointerMove"
,
or "pointerCancel"
return an error with
error code invalid argument.
If the current session's input state
already has an entry corresponding to input
id id and that entry has
a subtype
property with value different
to subtype return error with
error code invalid argument.
Let action be an action object
constructed with arguments id,
"pointer"
, and subtype.
If subtype is "pause"
;
let result be the result of trying to
process a pause action with arguments action
item, and action, and return
result.
Set the pointerType
property
of action equal to the pointerType
property of parameters.
Set the primary
property
of action equal to the primary
property of parameters.
If subtype is "pointerUp"
or "pointerDown"
, process a pointer up or
pointer down action with arguments action
item, and action. If doing so results in
an error, return that error.
If subtype
is "pointerMove"
process a pointer move
action with arguments action item,
and action. If doing so results in an error,
return that error
If subtype
is "pointerCancel"
process a
pointer cancel action. If doing so results in an
error, return that error
Return success with data action.
When required to process a pause action with
arguments action item, and action, a remote
end must run the following steps:
Let duration be the result of getting a
property named duration
from action
item.
If duration is not an Integer greater
than or equal to 0 return error with error
code invalid argument.
Set the duration
property
of action to duration.
Return success with data action.
When required to process a pointer up or pointer down
action with arguments action item,
and action, a remote end must run the following
steps:
Let button be the result of getting a
property named button
from action
item.
If button is not an Integer greater
than or equal to 0 return error with error
code invalid argument.
Set the button
property
of action to button.
Return success with data null
When required to process a pointer move action with
arguments action item, and action, a remote
end must run the following steps:
Let duration be the result of getting a
property named duration
from action
item.
If duration is not undefined
and duration is not an Integer greater than or equal to 0,
return error with error code invalid argument.
Set the duration
property
of action to duration.
Let element be the result of getting a
property named element
from action item.
If element is not undefined
and element is not an Object
that represents a web element, return error with
error code invalid argument.
Set the element
property
of action to element.
Let x be the result of getting a
property named x
from action
item.
If x is not undefined or is not
an Integer greater than or equal to 0,
return error with
error code invalid argument.
Set the x
property
of action to x.
Let y be the result of getting a
property named y
from action
item.
If y is not undefined or is not
an Integer greater than or equal to 0,
return error with
error code invalid argument.
Set the y
property
of action to y.
Return success with data null.
Dispatching Actions
The algorithm to dispatch actions takes a list of
actions grouped by tick, and then causes each action to be
run at the appropriate point in the sequence.
When asked to dispatch actions with
argument actions by tick, a remote end must run the
following steps:
For each item tick actions in actions by
tick:
Let tick duration be the result
of computing the tick duration with
argument tick actions.
Dispatch tick actions with
arguments tick actions and tick
duration. If this results in an error return
that error.
Wait until the following conditions are all met:
There are no pending asynchronous
waits arising from the last invocation of
the dispatch tick actions steps.
The user agent event loop has spun enough
times to process the DOM events generated by the
last invocation of the dispatch tick
actions steps.
At least tick duration
milliseconds have passed.
Return success with data null.
When required to
compute the tick
duration with argument tick actions,
a remote end must take the following steps:
Let max duration be 0.
For each action object in tick actions:
let duration be undefined.
If action object has type
property set to "none"
and subtype
property set
to "pause"
or action object
has type
property set
to "pointer"
and subtype
property set to "pointerMove"
,
let duration be equal to
the duration
property of action
object.
If duration is not undefined, and
duration is greater than max
duration let max duration be equal to
duration.
Return max duration.
When required to dispatch tick actions with
arguments tick actions and tick duration,
a remote end must run the following steps:
For each action object in tick actions:
Let source id be equal to the value
of action object's id
property.
Let source type be equal to the value
of action object's type
property.
If the current session's input
state doesn't have a property corresponding
to source id, then let the property
corresponding to source id be a new
object of the corresponding input state type
for source type.
Let device state be the device state
corresponding to source id in
the current session's input state
object.
Let algorithm be the algorithm in the
right hand column of the table below such that the
value in the first column matches source
type and the value in the second column
matches action
object's subtype
property.
Return the result of running algorithm
with arguments source id, action
object, device state and tick
duration
General Actions
When required to dispatch a pause action with
arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Return success with data null.
Keyboard Actions
The normalised key value for a raw
key key is, if key appears in the table
below, the string value in the second column on the row
containing key's unicode codepoint in the first
column, otherwise it is key.
key's codepoint
| Normalised key value
|
\uE000 | "Unidentified" |
\uE001 | "Cancel" |
\uE002 | "Help" |
\uE003 | "Backspace" |
\uE004 | "Tab" |
\uE005 | "Clear" |
\uE006 | "Return" |
\uE007 | "Enter" |
\uE008 | "Shift" |
\uE009 | "Control" |
\uE00A | "Alt" |
\uE00B | "Pause" |
\uE00C | "Escape" |
\uE00D | " " |
\uE00E | "PageUp" |
\uE00F | "PageDown" |
\uE010 | "End" |
\uE011 | "Home" |
\uE012 | "ArrowLeft" |
\uE013 | "ArrowUp" |
\uE014 | "ArrowRight" |
\uE015 | "ArrowDown" |
\uE016 | "Insert" |
\uE017 | "Delete" |
\uE018 | ";" |
\uE019 | "=" |
\uE01A | "0" |
\uE01B | "1" |
\uE01C | "2" |
\uE01D | "3" |
\uE01E | "4" |
\uE01F | "5" |
\uE020 | "6" |
\uE021 | "7" |
\uE022 | "8" |
\uE023 | "9" |
\uE024 | "*" |
\uE025 | "+" |
\uE026 | "," |
\uE027 | "-" |
\uE028 | "." |
\uE029 | "/" |
\uE031 | "F1" |
\uE032 | "F2" |
\uE033 | "F3" |
\uE034 | "F4" |
\uE035 | "F5" |
\uE036 | "F6" |
\uE037 | "F7" |
\uE038 | "F8" |
\uE039 | "F9" |
\uE03A | "F10" |
\uE03B | "F11" |
\uE03C | "F12" |
\uE03D | "Meta" |
\uE040 | "ZenkakuHankaku" |
\uE050 | "Shift" |
\uE051 | "Control" |
\uE052 | "Alt" |
\uE053 | "Meta" |
\uE054 | "PageUp" |
\uE055 | "PageDown" |
\uE056 | "End" |
\uE057 | "Home" |
\uE058 | "ArrowLeft" |
\uE059 | "ArrowUp" |
\uE05A | "ArrowRight" |
\uE05B | "ArrowDown" |
\uE05C | "Insert" |
\uE05D | "Delete" |
The code for key is the value in the
last column of the following table on the row with key in
either the first or second column, if any such row exists,
otherwise it is undefined
.
Key
| Alternate Key
| code
|
"`" | "~" | "Backquote" |
"\" | "|" | "Backslash" |
"\uE003" |
| "Backspace" |
"[" | "{" | "BracketLeft" |
"}" | "]" | "BracketRight" |
"," | "<" | "Comma" |
"0" | ")" | "Digit0" |
"1" | "!" | "Digit1" |
"2" | "@" | "Digit2" |
"3" | "#" | "Digit3" |
"4" | "$" | "Digit4" |
"5" | "%" | "Digit5" |
"6" | "^" | "Digit6" |
"7" | "&" | "Digit7" |
"8" | "*" | "Digit8" |
"9" | "(" | "Digit9" |
"=" | "+" | "Equal" |
"<" | ">" | "IntlBackslash" |
"a" | "A" | "KeyA" |
"b" | "B" | "KeyB" |
"c" | "C" | "KeyC" |
"d" | "D" | "KeyD" |
"e" | "E" | "KeyE" |
"f" | "F" | "KeyF" |
"g" | "G" | "KeyG" |
"h" | "H" | "KeyH" |
"i" | "I" | "KeyI" |
"j" | "J" | "KeyJ" |
"k" | "K" | "KeyK" |
"l" | "L" | "KeyL" |
"m" | "M" | "KeyM" |
"n" | "N" | "KeyN" |
"o" | "O" | "KeyO" |
"p" | "P" | "KeyP" |
"q" | "Q" | "KeyQ" |
"r" | "R" | "KeyR" |
"s" | "S" | "KeyS" |
"t" | "T" | "KeyT" |
"u" | "U" | "KeyU" |
"v" | "V" | "KeyV" |
"w" | "W" | "KeyW" |
"x" | "X" | "KeyX" |
"y" | "Y" | "KeyY" |
"z" | "Z" | "KeyZ" |
"-" | "_" | "Minus" |
"." | ">" | "Period" |
"'" | """ | "Quote" |
";" | ":" | "Semicolon" |
"/" | "?" | "Slash" |
"\uE00A" |
| "AltLeft" |
"\uE052" |
| "AltRight" |
"\uE009" |
| "ControlLeft" |
"\uE051" |
| "ControlRight" |
"\uE006" |
| "Enter" |
"\uE03D" |
| "OSLeft" |
"\uE053" |
| "OSRight" |
"\uE008" |
| "ShiftLeft" |
"\uE050" |
| "ShiftRight" |
" " | "\uE00D" | "Space" |
"\uE004" |
| "Tab" |
"\uE017" |
| "Delete" |
"\uE010" |
| "End" |
"\uE002" |
| "Help" |
"\uE011" |
| "Home" |
"\uE016" |
| "Insert" |
"\uE01E" |
| "PageDown" |
"\uE01F" |
| "PageUp" |
"\uE015" |
| "ArrowDown" |
"\uE012" |
| "ArrowLeft" |
"\uE014" |
| "ArrowRight" |
"\uE013" |
| "ArrowUp" |
"\uE00C" |
| "Escape" |
"\uE031" |
| "F1" |
"\uE032" |
| "F2" |
"\uE033" |
| "F3" |
"\uE034" |
| "F4" |
"\uE035" |
| "F5" |
"\uE036" |
| "F6" |
"\uE037" |
| "F7" |
"\uE038" |
| "F8" |
"\uE039" |
| "F9" |
"\uE03A" |
| "F10" |
"\uE03B" |
| "F11" |
"\uE03C" |
| "F12" |
"\uE01A" | "\uE05C" | "Numpad0" |
"\uE01B" | "\uE056" | "Numpad1" |
"\uE01C" | "\uE05B" | "Numpad2" |
"\uE01D" | "\uE055" | "Numpad3" |
"\uE01E" | "\uE058" | "Numpad4" |
"\uE01F" |
| "Numpad5" |
"\uE020" | "\uE05A" | "Numpad6" |
"\uE021" | "\uE057" | "Numpad7" |
"\uE022" | "\uE059" | "Numpad8" |
"\uE023" | "\uE054" | "Numpad9" |
"\uE024" |
| "NumpadAdd" |
"\uE026" |
| "NumpadComma" |
"\uE028" | "\uE05D" | "NumpadDecimal" |
"\uE029" |
| "NumpadDivide" |
"\uE007" |
| "NumpadEnter" |
"\uE024" |
| "NumpadMultiply" |
"\uE026" |
| "NumpadSubtract" |
The key location for key is the value
in the last column in the table below on the row
with key appears in the first column, if such a
row exists, otherwise it is 0
.
key's codepoint
| Location
| Description
|
\uE007 | Enter | 1 |
\uE008 | Left Shift | 1 |
\uE009 | Left Control | 1 |
\uE00A | Left Alt | 1 |
\uE01A | Numpad 0 | 3 |
\uE01B | Numpad 1 | 3 |
\uE01C | Numpad 2 | 3 |
\uE01D | Numpad 3 | 3 |
\uE01E | Numpad 4 | 3 |
\uE01F | Numpad 5 | 3 |
\uE020 | Numpad 6 | 3 |
\uE021 | Numpad 7 | 3 |
\uE022 | Numpad 8 | 3 |
\uE023 | Numpad 9 | 3 |
\uE024 | Numpad * | 3 |
\uE025 | Numpad + | 3 |
\uE026 | Numpad , | 3 |
\uE027 | Numpad - | 3 |
\uE028 | Numpad . | 3 |
\uE029 | Numpad / | 3 |
\uE03D | Left Meta | 1 |
\uE050 | Right Shift | 2 |
\uE051 | Right Control | 2 |
\uE052 | Right
Alt | 2 |
\uE053 | Right Meta | 2 |
\uE054 | Numpad
PageUp | 3 |
\uE055 | Numpad
PageDown | 3 |
\uE056 | Numpad
End | 3 |
\uE057 | Numpad
Home | 3 |
\uE058 | Numpad
ArrowLeft | 3 |
\uE059 | Numpad
ArrowUp | 3 |
\uE05A | Numpad
ArrowRight | 3 |
\uE05B | Numpad
ArrowDown | 3 |
\uE05C | Numpad
Insert | 3 |
\uE05D | Numpad
Delete | 3 |
When required to dispatch a keyDown action with
arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Let raw key be equal to action
object's value
property.
Let key be equal to the normalised key
value for raw key.
If the input state's pressed
property contains key, let repeat
be true, otherwise let repeat be false.
Let code be the code
for raw key.
Let location be the key location
for raw key.
Let charCode, keyCode
and which be the implementation-specific values of
the charCode
, keyCode
and which
properties appropriate for a key with
key key and location location on a 102
key US keyboard, following the guidelines in [[!UI-EVENTS]].
If key is "Alt"
,
let device state's alt
property
be true.
If key is "Shift"
,
let device state's shift
property
be true.
If key is "Control"
,
let device state's ctrl
property
be true.
If key is "Meta"
,
let device state's meta
property
be true.
Add key to the set corresponding
to input state's pressed
property.
Append a copy of action object with
the subtype property changed to keyUp
to current session's input cancel list.
Perform
implementation-specific action dispatch steps equivalent
to pressing a key on the keyboard in accordance with the
requirements of [[!UI-EVENTS]], and producing at least the
following events with the specified properties:
keyDown
with properties:
Attribute |
Value |
key | key
|
code | code
|
location | location
|
altKey | device
state's alt property
|
shiftKey | device
state's shift property
|
ctrlKey | device
state's ctrl property
|
metaKey | device
state's meta property
|
repeat | repeat
|
isComposing | false
|
charCode | charCode
|
keyCode | keyCode
|
which | which
|
keyPress
,
with properties:
Attribute |
Value |
key | key
|
code | code
|
location | location
|
altKey | device
state's alt property
|
shiftKey | device
state's shift property
|
ctrlKey | device
state's ctrl property
|
metaKey | device
state's meta property
|
repeat | repeat
|
isComposing | false
|
charCode | charCode
|
keyCode | keyCode
|
which | which
|
Return success with data null.
When required to dispatch a keyUp action with
arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Let raw key be equal to action
object's value
property.
Let key be equal to the normalised key
value for raw key.
If the input state's pressed
property does not contain key, return.
Let code be the code
for raw key.
Let location be the key location
for raw key.
Let charCode, keyCode
and which be the implementation-specific values
of the charCode
, keyCode
and which
properties appropriate for a key
with key key and location location
on a 102 key US keyboard, following the guidelines in
[[!UI-EVENTS]].
If key is "Alt"
,
let device state's alt
property
be false.
If key is "Shift"
,
let device state's shift
property
be false.
If key is "Control"
,
let device state's ctrl
property
be false.
If key is "Meta"
,
let device state's meta
property
be false.
Perform
implementation-specific action dispatch steps
equivalent to pressing a key on the keyboard in accordance
with the requirements of [[!UI-EVENTS]], and producing at
least the following events with the specified properties:
keyup
,
with properties:
Attribute |
Value |
key | key |
code | code |
location | location |
altKey | device
state's alt property |
shiftKey | device
state's shift property |
ctrlKey | device
state's ctrl property |
metaKey | device
state's meta property |
repeat | repeat |
isComposing | false |
charCode | charCode |
keyCode | keyCode |
which | which |
Return success with data null.
Pointer Actions
When required to get a global key
state with argument key, a remote end must
run the following steps:
- Let input state be the current
session's input state object.
- For each device input state that is a value
of the input state map:
- If device input state is a key input
state object, and its
pressed
property
contains key return true.
Return false.
When required to dispatch a pointerDown action
with arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Let pointerType be equal to action
object's pointerType
property.
Let button be equal to action
object's button
property.
If the input state's pressed
property contains button return success
with data null.
Let primary be equal to action object's
primary
property.
Let x be equal to input state's
x
property.
Let y be equal to input state's
y
property.
Add button to the set corresponding
to input state's pressed
property, and let buttons be the resulting
value of that property.
Append a copy of action object with
the subtype property changed to pointerUp
to the current session's input cancel list.
Perform
implementation-specific action dispatch steps
equivalent to pressing the button
numbered button on the pointer with
ID source id, having type
type pointerType at viewport x
coordinate x, viewport y
coordinate y, with buttons buttons
depressed, in accordance with the requirements of
[[!UI-EVENTS]] and [[!POINTER-EVENTS]], with
primary determining whether the pointer is
regarded as a primary pointer and thus generates legacy
mouse events. Type specific properties for the pointer
that are not exposed through the webdriver API must be set
to the default value specified for hardware that doesn't
support that property.
Return success with data null.
When required to dispatch a pointerUp action with
arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Let pointerType be equal to action
object's pointerType
property.
Let button be equal to action
object's button
property.
If the input state's pressed
property does not contain button
return success with data null.
Let primary be equal to action object's
primary
property.
Let x be equal to action object's
x
property.
Let y be equal to action object's
y
property.
Let alt be the result of getting a
global key pressed state with
argument "Alt"
.
If key is "Shift"
,
let device state's shift
property
be true.
If key is "Control"
,
let device state's ctrl
property
be true.
If key is "Meta"
,
let device state's meta
property
be true.
Remove button from the set corresponding
to input state's pressed
property, and let buttons be the resulting
value of that property.
Perform
implementation-specific action dispatch steps
equivalent to releasing the button
numbered button on the pointer of
ID source id having type
type pointerType at viewport x
coordinate x, viewport y
coordinate y, with buttons buttons
depressed, in accordance with the requirements of
[[!UI-EVENTS]] and [[!POINTER-EVENTS]], with
primary determining whether the pointer is
regarded as a primary pointer and thus generates legacy
mouse events. Type specific properties for the pointer
that are not exposed through the webdriver API must be set
to the default value specified for hardware that doesn't
support that property.
Return success with data null.
When required to dispatch a pointerMove action
with arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Let x be equal to the x
property of action object.
Let y be equal to the y
property of action object.
Let start x be equal to the x
property of input state.
Let start y be equal to the y
property of input state.
Let element id be equal to
the element
property of action
object.
If element id is not undefined:
Let element be equal to the result
of trying to get a known element with
argument element.
If x and y are undefined,
let x and y be the result of calculating the
in-view centre point of element.
Let duration be equal to action
object's duration
property if it is
not undefined
, or tick duration
otherwise.
If duration is greater than 0 and inside any
implementation-defined bounds, asynchronously wait
for an implementation defined amount of time to pass.
Perform a pointer move with
arguments source id, input
state, duration, start
x, start
y, x, y.
When required to perform a pointer move with
arguments source id, input
state, duration,
start x, start y, target x
and target y, an implementation must run the
following steps:
Let subtype equal the subtype
property of input state.
Let time delta be the time since the
beginning of the current tick, measured in milliseconds on a
monotonic clock.
Let duration ratio be the ratio
of time deta and duration,
if duration is greater than 0, or 1
otherwise.
If duration ratio is 1, or close enough to
1 that the implementation will not further subdivide the move
action, let last be true. Otherwise
let last be false
.
If last is true, let x
equal target x and y
equal target y.
Otherwise let x equal an approximation
to duration ratio × (target
x - start x) + start x,
and y equal an approximation to duration
ratio × (target y - start
y) + start y.
Let current x equal the x
property of input state.
Let current y equal the y
property of input state.
If x is not equal to current x
or y is not equal to current y, run
the following steps:
Let buttons be equal to input
state's buttons
property.
Perform
implementation-specific action dispatch steps
equivalent to moving the pointer with
ID source id having
type pointerType from viewport x
coordinate current x, viewport y
coordinate y to viewport x
coordinate x and viewport y
coordinate y, with
buttons buttons depressed, in
accordance with the requirements of [[!UI-EVENTS]]
and [[!POINTER-EVENTS]], with primary
determining whether the pointer is regarded as a
primary pointer and thus generates legacy mouse
events. Type specific properties for the pointer
that are not exposed through the WebDriver API
must be set to the default value specified for
hardware that doesn't support that property. In
the case where the pointerType
is "pen"
or "touch"
,
and buttons is empty, this may be a
no-op. For a pointer of type "mouse"
,
this will always produce events including at least
a pointerMove
event.
Let input state's x
property equal x and y
property
equal y.
If last is true, return.
Asynchronously wait for an implementation
defined amount of time to pass.
Perform a pointer move with
arguments source id, input
state, duration, start
x, start y, target
x, target y.
When required to dispatch a pointerCancel action
with arguments source id, action
object, input state and tick
duration a remote end must run the following
steps:
Perform
implementation-specific action dispatch steps
equivalent to cancelling the any action of the
pointer with ID source id having
type pointerType, in accordance with
the requirements of [[!UI-EVENTS]] and
[[!POINTER-EVENTS]].
Perform Actions
HTTP Method |
Path Template |
POST |
/session/{session id}/actions |
Payload Format
This section is non-normative.
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 can rely on a command-line flag
or a configuration option
to test whether to enable WebDriver,
or alternatively make the user agent initiate
or confirm the connection through
a privileged content document or control widget,
in case the user agent does not
directly implement the HTTP endpoints.
It is strongly suggested that user agents
require users to take explicit action to enable WebDriver,
and that WebDriver remains disabled
in publicly consumed versions of the user agent.
To prevent arbitrary machines on the network
from connecting and creating sessions,
it is suggested that only connections from
loopback devices are allowed by default.
The remote end can include
a configuration option to limit
the accepted IP range allowed to connect and make requests.
The default setting for this might be
to limit connections to the IPv4 localhost
CIDR range 127.0.0.0/8
and the IPv6 localhost address ::1
. [[!RFC4632]]
It is also suggested that user agents
make an effort to visually distinguish
a user agent session that is under control of WebDriver
from those used for normal browsing sessions.
This can be done through a chrome UX element
such as a “door hanger”,
colorful decoration of the OS window,
or some widget element that is prevalent in the window
so that it easy to identify automation windows.
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":
Let parent dimensions be the rectangle
that is the first element of the DOMRect
sequence returned by calling getClientRects on parent.
Let element dimensions be the rectangle
that is the first element of the DOMRect
sequence returned by calling getClientRects on element.
Let parent style be the computed style of parent.
Return false if any the following conditions evaluate to false:
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, John Jansen, Maja Frydrychowicz and Gábor Csárdi for contributing sections to this document.
Also thanks to the following people for their contribution of patches and test cases: