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 behavior of web browsers.
Provided is a set of interfaces
to discover and manipulate DOM elements in web documents
and to control the behavior 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.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document has been reviewed by W3C Members, by software developers, and by other W3C
groups and interested parties, and is endorsed by the Director as a W3C Recommendation.
It is a stable document and may be used as reference material or cited from another
document. W3C's role in making the Recommendation is to draw attention to the
specification and to promote its widespread deployment. This enhances the functionality
and interoperability of the Web.
This document was produced by
a group
operating under the
W3C Patent Policy.
W3C maintains a public list of any patent
disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual knowledge of a patent
which the individual believes contains
Essential
Claim(s) must disclose the information in accordance with
section
6 of the W3C Patent Policy.
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.
1.1 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]
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 IDL fragments in this specification
must be interpreted as required for conforming IDL fragments,
as described in the Web IDL specification. [WEBIDL]
The WebDriver standard attempts to follow a number of design goals:
2.1 Compatibility
This specification is derived from the popular
Selenium WebDriver browser automation framework.
Selenium is a long-lived project,
and due to its age and breadth of use
it has a wide range of expected functionality.
This specification uses these expectations to inform its design.
Where improvements or clarifications have been made,
they have been made with care to allow existing users of Selenium WebDriver
to avoid unexpected breakages.
2.2 Simplicity
The largest intended group of users of this specification
are software developers and testers
writing automated tests and other tooling,
such as monitoring or load testing, that relies on automating a browser.
As such, care has been taken to provide commands
that simplify common tasks such as typing into
and clicking elements.
2.3 Extensions
WebDriver provides a mechanism for others to define extensions to the protocol
for the purposes of automating functionality that cannot be implemented entirely
in ECMAScript. This allows other
web standards to support the automation of new platform features. It also
allows vendors to expose functionality that is specific to their browser.
3. 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.
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 converting it to the string representation [RFC4122].
The Unix Epoch
is a value that approximates the number of seconds
that have elapsed since the Epoch,
as described by The Open Group Base Specifications Issue 7
section 4.15 (IEEE Std 1003.1).
An integer is a Number that is unchanged
under the ToInteger operation.
The initial value of an ECMAScript property
is the value defined by the platform for that property,
i.e. the value it would have in the absence of any shadowing by content script.
The browser chrome is a non-normative term
to refer to the representation through which the user
interacts with the user agent itself,
as distinct from the accessed web content.
Examples of browser chrome elements
include, but are not limited to,
toolbars (such as the bookmark toolbar),
menus (such as the file or context menu),
buttons (such as the back and forward buttons),
door hangers (such as security and certificate indicators),
and decorations (such as operating system widget borders).
4. Interface
The webdriver-active flag
is set to true when the user agent is under remote control.
It is initially false.
It is acknowledged that this is complementary to the Evil Bit [RFC3514].
5. Nodes
The WebDriver protocol consists of communication between:
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.
Remote end
The remote end hosts the server side of the protocol.
Defining the behavior of a remote end in response to the WebDriver protocol
forms the largest part of this specification.
For remote ends the standard defines two broad conformance
classes, known as node types:
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.
All remote end node types 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.
A remote end’s readiness state is the value corresponding
to the first matching statement:
the node is an intermediary node and is known to be in a state in
which attempting to create a new session would fail
False
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.
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.
6.1 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 field.
The result of getting a property with argument name is
defined as being the same as the result of calling
Object.[[GetOwnProperty]](name).
Setting a property with
arguments name and value is defined as being
the same as calling
Object.[[Put]](name, value).
The result of JSON serialization with object
of type JSON Object is defined as the result of
calling JSON.[[Stringify]](object).
The result of JSON deserialization with text is defined as
the result of calling JSON.[[Parse]](text).
6.2 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 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.
6.3 Processing Model
The remote end is an HTTP server
reading requests from the client and writing responses,
typically over a TCP socket.
For the purposes of this specification we model the data transmission between
a 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 endMUST run the following steps:
Otherwise, let command and command parameters
be request match’s data. Let url variables be a
url variables dictionary mapping the command parameters
to their corresponding values.
If session id is among the variables defined by command parameters:
Let parse result be the result of
parsing as JSON with request’s
body as the argument. If this process throws an exception,
return an error with error codeinvalid
argument and jump back to step 1 in this overall algorithm.
Let response result be the return value
obtained by running the remote end steps for command
with an argument named url variables whose value is
url variables and an
additional argument named parameters whose value is
parameters.
Errors are represented in the WebDriver protocol
by an HTTP response with an HTTP status in the 4xx or 5xx range,
and a JSON body containing details of the error.
The body is a JSON Object
and has a field named "value"
whose value is an object bearing three, and sometimes four, fields:
"error", containing a string indicating the error code.
"message", containing an implementation-defined string
with a human readable description of the kind of error that occurred.
"stacktrace", containing an implementation-defined string
with a stack trace report of the active stack frames at the time when the error occurred.
Optionally "data", which is a JSON Object
with additional error data helpful in diagnosing the error.
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.
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 element state
400
invalid element state
A command could not be completed because the element is
in an invalid state, e.g. attempting to
clear an element that isn't
both editable and resettable.
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
404
no such alert
An attempt was made to operate on a modal dialog
when one was not open.
A command failed because
the referenced element is no longer attached to the DOM.
timeout
408
timeout
An operation did not complete before its timeout expired.
unable to set cookie
500
unable to set cookie
A command 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.
An error data dictionary
is a mapping of string keys to JSON serializable values
that can optionally be included with error objects.
6.7 Protocol Extensions
Using the terminology defined in this section, others may define additional
commands that seamlessly integrate with the standard protocol. This allows
vendors to expose functionality that is specific to their user agent, and it
also allows other web standards to define commands for automating new platform
features.
Commands defined in this way
are 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 URI Template
that is a URI Template string,
and which should bear some resemblance to what the command performs.
This value,
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.
In order to avoid potential resource conflicts with other implementations,
vendor-specific extension command URI Templates must begin with one
or more path segments which uniquely identifies the vendor and UA.
It is suggested that vendors use their vendor prefixes
without additional characters as outlined in [CSS21],
notably in section 4.1.2.2 on vendor keywords,
as the name for this path element,
and include a vendor-chosen UA identifier.
Note
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.
WebDriver capabilities
are used to communicate the features supported by a given implementation.
The local end may use capabilities
to define which features it requires the remote end
to satisfy when creating a new session.
Likewise, the remote end uses capabilities
to describe the full feature set for a session.
The following table of standard capabilities
enumerates the capabilities each implementation MUST support.
An implementation MAY define additional extension capabilities.
Capability
Key
Value Type
Description
Browser name
"browserName"
string
Identifies the user agent.
Browser version
"browserVersion"
string
Identifies the version of the user agent.
Platform name
"platformName"
string
Identifies the operating system of the endpoint node.
Accept insecure TLS certificates
"acceptInsecureCerts"
boolean
Indicates whether untrusted and self-signed TLS certificates
are implicitly trusted on navigation
for the duration of the session.
The proxy configuration capability
is a JSON Object nested
within the primary capabilities.
Implementations may define additional proxy configuration options,
but they must not alter the semantics of those listed below.
Key
Value Type
Description
Valid values
proxyType
string
Indicates the type of proxy configuration.
"pac",
"direct",
"autodetect",
"system",
or "manual".
proxyAutoconfigUrl
string
Defines the URL for a proxy auto-config file
if proxyType
is equal to "pac".
A host and optional port for a scheme is
defined as being a valid host, optionally followed by a colon
and a valid port. The host may
include credentials. If the
port is omitted and scheme has a default port,
this is the implied port. Otherwise, the port is left undefined.
A proxyType of "direct" indicates
that the browser should not use a proxy at all.
A proxyType of "system" indicates
that the browser should use the various proxies configured for the
underlying Operating System.
A proxyType of "autodetect"
indicates that the proxy to use should be detected in an
implementation-specific way.
The remote end steps to deserialize as a proxy
argument parameter are:
A proxy configuration object is a
JSON Object where each of its own properties matching
keys in the proxy configuration meets the validity criteria for
that key.
7.2 Processing Capabilities
To process capabilities
with argument parameters,
the endpoint node must take the following steps:
Let capabilities request be the result of getting the property
"capabilities" from parameters.
Optionally add extension capabilities as entries
to matched capabilities. The values of these may be
elided, and there is no requirement that all
extension capabilities be added.
Note
For each name and value corresponding
to capability's own properties:
Run the substeps of the first matching name:
"browserName"
If value is not a string equal to
the "browserName" entry in
matched capabilities, return success
with data null.
Note
There is a chance the remote end will need
to start a browser process to correctly determine
the browserName. Lightweight checks are preferred
before this is done.
"browserVersion"
Compare value
to the "browserVersion" entry in matched capabilities
using an implementation-defined comparison algorithm.
The comparison is to accept a value
that places constraints on the version using
the "<", "<=", ">",
and ">=" operators.
If the two values do not match,
return success with data null.
Note
Version comparison is left as an implementation detail
since each user agent will likely have conflicting methods
of encoding the user agent version,
and standardizing these schemes is beyond the scope of this standard.
Note
There is a chance the remote end will need
to start a browser process to correctly determine
the browserVersion. Lightweight checks are preferred
before this is done.
"platformName"
If value is not a string equal
to the "platformName" entry in matched capabilities,
return success with data null.
Note
The following platform names are in common usage with
well-understood semantics and, when matching
capabilities, greatest interoperability can be achieved by
honoring them as valid synonyms for well-known Operating
Systems:
Key
System
"linux"
Any server or desktop system based upon the Linux kernel.
"mac"
Any version of Apple’s macOS.
"windows"
Any version of Microsoft Windows, including desktop and mobile versions.
This list is not exhaustive.
When returning capabilities from New Session,
it is valid to return a more
specific platformName, allowing users to
correctly identify the Operating System the WebDriver
implementation is running on.
If the endpoint node does not allow the proxy it
uses to be configured, or if the proxy configuration defined
in value is not one that passes the endpoint
node's implementation-specific validity checks,
return success with data null.
Note
A local end would only send this capability
if it expected it to be honored and the configured proxy
used. The intent is that if this is not possible a new session
will not be established.
let value be the
result of trying implementation-specific steps to match
on name with value. If the match is not
successful, return success with data null.
Set a property on matched capabilities
with name name and value value.
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 commands to
the remote end requires passing a session ID.
A session has an associated session script timeout
that specifies a time to wait for scripts to run. If equal to null
then session script timeout will be indefinite.
Unless stated otherwise it is 30,000 milliseconds.
A session has an associated session page load timeout
that specifies a time to wait for the page loading to complete.
Unless stated otherwise it is 300,000 milliseconds.
A session has an associated secure TLS state
that indicates whether untrusted or self-signed TLS certificates
should be trusted for the duration of the WebDriver session.
If it is unset, this indicates that certificate- or TLS errors
that occur upon navigation should be suppressed.
The state can be unset by providing
an "acceptInsecureCerts" capability with the value true.
Unless stated otherwise, it is set.
Perform any implementation-specific cleanup steps.
If an error has occurred in any of the steps above,
return the error, otherwise return success with
data null.
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.
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 as part of the requested capabilities.
An intermediary nodeMUST forward custom,
top-level parameters (i.e. non-capabilities) to subsequent remote end nodes.
How this is done is entirely up to the implementation,
but typically the sessionId, and URL and
URL prefix of the upstreamremote end will need
to be tracked.
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 codesession not created.
Otherwise
Set a property of capabilities with name
"proxy" and a value that is a new JSON Object.
Let timeouts be the result of getting property
"timeouts" from capabilities.
WebDriver implementations typically start a
completely new browser instance, but there is no requirement in
this specification (or for WebDriver only to be used to automate
only web browsers). Implementations might choose to use an existing
browser instance, eg. by selecting the window that currently has
focus.
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 following table of session timeouts
enumerates the different timeout types that may be set
using the Set Timeouts command.
The keywords given in the first column
maps to the timeout type given in the second.
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 timeouterror.
The following is the table of page load strategies
that links the pageLoadStrategycapability 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 deserialize as a page load strategy with
argument value:
A "network error" in this case is not an
HTTP response with a status code indicating an unsucessful result,
but could be a problem occurring lower in the OSI model, or a
failed DNS lookup.
If the current session’s secure TLS 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.
If the session is not in a secure TLS state,
no certificate errors that would normally
cause the user agent to abort and show a security warning
are to hinder navigation to the requested address.
This command causes the browser to traverse
one step backward in the joint session history
of the current top-level browsing context.
This is equivalent to pressing the back button in the browser chrome
or invoking window.history.back.
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.
Each browsing context has an associated
window handle which uniquely
identifies it. This must be a String and must not be
"current".
The web window identifier
is the string constant "window-fcc6-11e5-b4f8-330a88ab9d7f".
The web frame identifier
is the string constant "frame-075b-4da1-b6ba-e579c2d3230a".
The JSON serialization of the WindowProxy object
is the JSON Object obtained by applying the following algorithm
to the given WindowProxy object window:
Update any implementation-specific state that would result
from the user selecting the current browsing context for
interaction, without altering OS-level focus.
Update any implementation-specific state that would result
from the user selecting the current browsing context for
interaction, without altering OS-level focus.
WebDriver is not bound by the same origin policy,
so it is always possible to switch into child browsing contexts,
even if they are different origin to the current browsing context.
Update any implementation-specific state that would result
from the user selecting the current browsing context for
interaction, without altering OS-level focus.
The top-level browsing context
has an associated window state
which describes what visibility state its OS widget window is in.
It can be in one of the following states:
State
Keyword
Default
Description
Maximized window state
"maximized"
The window is maximized.
Minimized window state
"minimized"
The window is iconified.
Normal window state
"normal"
✓
The window is shown normally.
Fullscreen window state
"fullscreen"
The window is in full screen mode.
If for whatever reason
the top-level browsing context’s OS window
cannot enter either of the window states,
or if this concept is not applicable on the current system,
the default state must be normal.
To maximize the window,
given an operating system level window
with an associated top-level browsing context,
run the implementation-specific steps
to transition the operating system level window
into the maximized window state.
If the window manager supports window resizing
but does not have a concept of window maximization,
the window dimensions must be increased
to the maximum available size
permitted by the window manager
for the current screen.
Return when the window has completed the transition,
or within an implementation-defined timeout.
To iconify the window,
given an operating system level window
with an associated top-level browsing context,
run implementation-specific steps
to iconify, minimize, or hide the window
from the visible screen.
Do not return from this operation
until the visibility state
of the top-level browsing context’s active document
has reached the hidden state,
or until the operation times out.
To restore the window,
given an operating system level window
with an associated top-level browsing context,
run implementation-specific steps
to restore or unhide the window
to the visible screen.
Do not return from this operation
until the visibility state
of the top-level browsing context’s active document
has reached the visible state,
or until the operation times out.
Set the width, in CSS 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 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.
Run the implementation-specific steps
to set the position of the operating system level window
containing the current top-level browsing context
to the position given by the x and y coordinates.
The Maximize Window command
invokes the window manager-specific “maximize” operation, if any,
on the window containing the current top-level browsing context.
This typically increases the window to the maximum available size
without going full-screen.
The Minimize Window command
invokes the window manager-specific “minimize” operation, if any,
on the window containing the current top-level browsing context.
This typically hides the window in the system tray.
In order to determine if an element
can be interacted with using pointer actions,
WebDriver performs hit-testing to find
if the interaction will be able to reach the requested element.
A pointer-interactable element
is defined to be the first element,
defined by the paint order found at the center point
of its rectangle that is inside the viewport,
excluding the size of any rendered scrollbars.
An element’s in-view center point
is the origin position of the rectangle
that is the intersection between
the element’s first DOM client rectangle
and the initial viewport.
Given an element that is known to be in view,
it can be calculated this way:
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 of location strategies lists the keywords and
states defined for this attribute:
The Partial link text strategy
is very similar to the Link Textstrategy,
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.
Let datalist parent be
the first datalist element reached
by traversing the tree in reverse order from element,
or undefined if the root of the tree is reached.
Let select parent be the
first select element reached
by traversing the tree in reverse order from element,
or undefined if the root of the tree is reached.
Please note that the behavior of this command
deviates from the behavior of getAttribute in [DOM],
which in the case of a set boolean attribute
would return an empty string.
The reason this command returns true as a string
is because this evaluates to true in most dynamically typed programming languages,
but still preserves the expected type information.
Let rendered text be the result of performing
implementation-specific steps whose result is exactly the same as the
result of a Call(bot.dom.getVisibleText,
null, element).
Some resettable elements define their own clear algorithm.
Unlike their associated reset algorithms,
changes made to form controls as part of these algorithms
do count as changes caused by the user
(and thus, e.g. do cause input events to fire).
When the clear algorithm is invoked
for an element that does not define its own clear algorithm,
its reset algorithm must be invoked instead.
The clear algorithm for output elements
is set the element’s value mode flag to default
and then to set the element’s textContent IDL attribute
to an empty string (thus clearing the element’s child nodes).
Wait until the user agent event loop has spun enough times to
process the DOM events generated by the previous step.
Perform implementation-defined steps to allow
any navigations triggered by the click
to start.
Note
It is not always clear how long this will cause the
algorithm to wait, and it is acknowledged that some implementations
may have unavoidable race conditions. The intention is to allow a
new attempt to navigate to begin so that the next step in the
algorithm is meaningful. It is possible the click does not cause an
attempt to navigate, in which case the implementation-defined
steps can return immediately, and the next step will also return
immediately.
The shifted state for keyboard
is the value of keyboard’s
key input state’s shift property.
In order to dispatch the events for a typeable string
with arguments text and keyboard, a remote
end must for each char corresponding to an indexed
property in text:
When required to dispatch a composition
event with arguments type
and cluster the remote end must perform
implementation-specific action dispatch steps equivalent to
sending composition events in accordance with the requirements of
[UI-EVENTS], and producing the following event with the specified
properties.
Complete implementation specific steps
equivalent to setting the selected files
on the input.
If multiple is truefiles are be appended to element’s selected files.
The user agent renders element as something other
than a text input control (for example an input
element in the color state being presented as a
colorwheel):
Let source be the result of invoking the
fragment serializing algorithm on a fictional node whose only
child is the document element providing true for the
require well-formed flag. If this causes an exception
to be thrown, let source be null.
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:
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 error,
return error with error codejavascript 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.
When required to extract the script arguments from a
request with argument parameters the implementation must:
Let script be the result of
getting a property named script
from the parameters.
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.
If at any point during the algorithm a user prompt appears,
abort all subsequent substeps of this algorithm, and return
success with data null.
The Execute Async Scriptcommand
causes JavaScript to execute as an anonymous function.
Unlike the Execute Scriptcommand,
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 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.
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 serialized 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 serialized cookie 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.
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. Must not be set if omitted when
adding a cookie.
A serialized cookie is a JSON Object
where a cookie’s [RFC6265] fields
listed in the table for cookie conversion
are mapped using the JSON Key
and the associated field’s value from the cookie store.
The optional fields may be omitted.
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:
The Actions API provides a low-level interface
for providing virtualised device input to the web browser.
Conceptually, the Actions commands divide 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 sequence
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 sequence consisting of three ticks
and two pointer input devices of type touch,
each performing a sequence of actions pointerDown,
followed by pointerMove, and then pointerUp.
17.1 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 source state object
associated with each input source.
A null input source is an input source that is
not associated with a specific physical device. A null input source
supports 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.
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 pointer type 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.
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 behavior of actions is intended to mimic
the remote end's behavior 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 accommodate 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.).
Note
17.2 Input Source State
Note
The objects and properties defined in this section
are spec-internal constructs
and do not correspond to ECMAScript objects.
For convenience the same terminology is used for their manipulation.
"Input source state" is used as a generic term to
describe the state associated with each input source.
The corresponding input source state type
for a label action type is given by the following table:
A key input source's input source state is a
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's input source state is
a pointer input state object. This consists of
a subtype property, which has the possible
values "mouse", "pen",
and "touch", 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 an implementation must return
a pointer input state object with subtype set
to subtype, pressed set to an empty set and
both x and y set to 0.
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.
The calculated global key state is the aggregated key
state from all key input state objects. It can be calculated
this way:
Let pressed be a new Set.
Let alt, ctrl, meta,
and shift be the Booleanfalse value.
Set a property on state with
name shift and value shift.
Return state.
17.3 Processing Actions Requests
The algorithm for
extracting an action sequence from a request takes the
JSON Object representing an action sequence, 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 sequence with
argument parameters, a remote end must run the
following steps:
Let actions be the result
of getting a property from parameters
named actions.
If type is equal to "pointer",
let parameters data be the result
of getting the property "parameters"
from action sequence.
Then let parameters be the result
of trying to process pointer parameters
with argument parameters data.
An 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.
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 codeinvalid 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.
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:
If action object has subtype
property set to "pause" or
action object has type property set
to "pointer" and subtype property set
to "pointerMove", let duration be equal to
the duration property of
action object.
If duration is not undefined,
and duration is greater than max duration,
let max duration be equal to duration.
Return max duration.
When required to dispatch tick actions with
arguments tick actions and tick duration,
a remote end must run the following steps:
For each action object in tick actions:
Let source id be equal to the value
of action object's id property.
Let source type be equal to the value
of action object's type property.
Let algorithm be the value of the column
dispatch action algorithm from the following table of
dispatch action algorithms that matches the
source type and the action object's
subtype property, to a dispatch action algorithm.
Return the result of running algorithm with
arguments source id, action object,
device state and tick duration.
17.4.1 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:
The normalised key value for a raw key key
is, if key appears in the table below, the string value in
the second column on the row containing key's unicode
code point in the first column, otherwise it is key.
key's codepoint
Normalised key value
\uE000
"Unidentified"
\uE001
"Cancel"
\uE002
"Help"
\uE003
"Backspace"
\uE004
"Tab"
\uE005
"Clear"
\uE006
"Return"
\uE007
"Enter"
\uE008
"Shift"
\uE009
"Control"
\uE00A
"Alt"
\uE00B
"Pause"
\uE00C
"Escape"
\uE00D
" "
\uE00E
"PageUp"
\uE00F
"PageDown"
\uE010
"End"
\uE011
"Home"
\uE012
"ArrowLeft"
\uE013
"ArrowUp"
\uE014
"ArrowRight"
\uE015
"ArrowDown"
\uE016
"Insert"
\uE017
"Delete"
\uE018
";"
\uE019
"="
\uE01A
"0"
\uE01B
"1"
\uE01C
"2"
\uE01D
"3"
\uE01E
"4"
\uE01F
"5"
\uE020
"6"
\uE021
"7"
\uE022
"8"
\uE023
"9"
\uE024
"*"
\uE025
"+"
\uE026
","
\uE027
"-"
\uE028
"."
\uE029
"/"
\uE031
"F1"
\uE032
"F2"
\uE033
"F3"
\uE034
"F4"
\uE035
"F5"
\uE036
"F6"
\uE037
"F7"
\uE038
"F8"
\uE039
"F9"
\uE03A
"F10"
\uE03B
"F11"
\uE03C
"F12"
\uE03D
"Meta"
\uE040
"ZenkakuHankaku"
\uE050
"Shift"
\uE051
"Control"
\uE052
"Alt"
\uE053
"Meta"
\uE054
"PageUp"
\uE055
"PageDown"
\uE056
"End"
\uE057
"Home"
\uE058
"ArrowLeft"
\uE059
"ArrowUp"
\uE05A
"ArrowRight"
\uE05B
"ArrowDown"
\uE05C
"Insert"
\uE05D
"Delete"
The code for key
is the value in the last column of the following table
on the row with key in either the first or second column,
if any such row exists,
otherwise it is undefined.
A shifted character
is one that appears in the second column of the following table.
Key
Alternate Key
code
"`"
"~"
"Backquote"
"\"
"|"
"Backslash"
"\uE003"
"Backspace"
"["
"{"
"BracketLeft"
"}"
"]"
"BracketRight"
","
"<"
"Comma"
"0"
")"
"Digit0"
"1"
"!"
"Digit1"
"2"
"@"
"Digit2"
"3"
"#"
"Digit3"
"4"
"$"
"Digit4"
"5"
"%"
"Digit5"
"6"
"^"
"Digit6"
"7"
"&"
"Digit7"
"8"
"*"
"Digit8"
"9"
"("
"Digit9"
"="
"+"
"Equal"
"<"
">"
"IntlBackslash"
"a"
"A"
"KeyA"
"b"
"B"
"KeyB"
"c"
"C"
"KeyC"
"d"
"D"
"KeyD"
"e"
"E"
"KeyE"
"f"
"F"
"KeyF"
"g"
"G"
"KeyG"
"h"
"H"
"KeyH"
"i"
"I"
"KeyI"
"j"
"J"
"KeyJ"
"k"
"K"
"KeyK"
"l"
"L"
"KeyL"
"m"
"M"
"KeyM"
"n"
"N"
"KeyN"
"o"
"O"
"KeyO"
"p"
"P"
"KeyP"
"q"
"Q"
"KeyQ"
"r"
"R"
"KeyR"
"s"
"S"
"KeyS"
"t"
"T"
"KeyT"
"u"
"U"
"KeyU"
"v"
"V"
"KeyV"
"w"
"W"
"KeyW"
"x"
"X"
"KeyX"
"y"
"Y"
"KeyY"
"z"
"Z"
"KeyZ"
"-"
"_"
"Minus"
"."
">"
"Period"
"'"
"""
"Quote"
";"
":"
"Semicolon"
"/"
"?"
"Slash"
"\uE00A"
"AltLeft"
"\uE052"
"AltRight"
"\uE009"
"ControlLeft"
"\uE051"
"ControlRight"
"\uE006"
"Enter"
"\uE03D"
"OSLeft"
"\uE053"
"OSRight"
"\uE008"
"ShiftLeft"
"\uE050"
"ShiftRight"
" "
"\uE00D"
"Space"
"\uE004"
"Tab"
"\uE017"
"Delete"
"\uE010"
"End"
"\uE002"
"Help"
"\uE011"
"Home"
"\uE016"
"Insert"
"\uE01E"
"PageDown"
"\uE01F"
"PageUp"
"\uE015"
"ArrowDown"
"\uE012"
"ArrowLeft"
"\uE014"
"ArrowRight"
"\uE013"
"ArrowUp"
"\uE00C"
"Escape"
"\uE031"
"F1"
"\uE032"
"F2"
"\uE033"
"F3"
"\uE034"
"F4"
"\uE035"
"F5"
"\uE036"
"F6"
"\uE037"
"F7"
"\uE038"
"F8"
"\uE039"
"F9"
"\uE03A"
"F10"
"\uE03B"
"F11"
"\uE03C"
"F12"
"\uE01A"
"\uE05C"
"Numpad0"
"\uE01B"
"\uE056"
"Numpad1"
"\uE01C"
"\uE05B"
"Numpad2"
"\uE01D"
"\uE055"
"Numpad3"
"\uE01E"
"\uE058"
"Numpad4"
"\uE01F"
"Numpad5"
"\uE020"
"\uE05A"
"Numpad6"
"\uE021"
"\uE057"
"Numpad7"
"\uE022"
"\uE059"
"Numpad8"
"\uE023"
"\uE054"
"Numpad9"
"\uE024"
"NumpadAdd"
"\uE026"
"NumpadComma"
"\uE028"
"\uE05D"
"NumpadDecimal"
"\uE029"
"NumpadDivide"
"\uE007"
"NumpadEnter"
"\uE024"
"NumpadMultiply"
"\uE026"
"NumpadSubtract"
The key location for key is the value in the
last column in the table below on the row with key appears
in the first column, if such a row exists, otherwise it
is 0.
key's codepoint
Description
Location
\uE007
Enter
1
\uE008
Left Shift
1
\uE009
Left Control
1
\uE00A
Left Alt
1
\uE01A
Numpad 0
3
\uE01B
Numpad 1
3
\uE01C
Numpad 2
3
\uE01D
Numpad 3
3
\uE01E
Numpad 4
3
\uE01F
Numpad 5
3
\uE020
Numpad 6
3
\uE021
Numpad 7
3
\uE022
Numpad 8
3
\uE023
Numpad 9
3
\uE024
Numpad *
3
\uE025
Numpad +
3
\uE026
Numpad ,
3
\uE027
Numpad -
3
\uE028
Numpad .
3
\uE029
Numpad /
3
\uE03D
Left Meta
1
\uE050
Right Shift
2
\uE051
Right Control
2
\uE052
Right Alt
2
\uE053
Right Meta
2
\uE054
Numpad PageUp
3
\uE055
Numpad PageDown
3
\uE056
Numpad End
3
\uE057
Numpad Home
3
\uE058
Numpad ArrowLeft
3
\uE059
Numpad ArrowUp
3
\uE05A
Numpad ArrowRight
3
\uE05B
Numpad ArrowDown
3
\uE05C
Numpad Insert
3
\uE05D
Numpad Delete
3
When required to dispatch a keyDown action with arguments
source id, action object,
input state and tick duration a remote end
must run the following steps:
Let raw key be equal to the
action object's value property.
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'salt property be true.
If key is "Shift", let
device state'sshift property be true.
If key is "Control", let
device state'sctrl property be true.
If key is "Meta", let
device state'smeta property be true.
Add key to the set corresponding to
input state's pressed property.
Perform implementation-specific
action dispatch steps equivalent to pressing a key on the
keyboard in accordance with the requirements of [UI-EVENTS], and
producing the following events, as appropriate, with the specified
properties. This will always produce events including at least
a keyDown event.
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 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'salt property be false.
If key is "Shift", let
device state'sshift property be false.
If key is "Control", let
device state'sctrl property be false.
If key is "Meta", let
device state'smeta property be false.
Remove key from the set corresponding
to input state's pressed property.
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 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.
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]. The generated events must
set ctrlKey, shiftKey, altKey,
and metaKey from the calculated global key state.
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.
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 x be equal to input state’s
x property.
Let y be equal to input state’s
y property.
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]. The generated events must
set ctrlKey, shiftKey, altKey,
and metaKey from the calculated global key state.
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.
When required to dispatch a pointerMove action with
arguments source id, action object,
input state and tick duration a
remote end must run the following steps:
Let x offset be equal to the x
property of action object.
Let y offset be equal to the y
property of action object.
Let start x be equal to the x
property of input state.
Let start y be equal to the y
property of input state.
Let origin be equal to the origin
property of action object.
Run the substeps of the first matching value
of origin:
"viewport"
Let x equal x offset and
y equal y offset.
"pointer"
Let x equal start x +
x offset and y equal
start y + y offset.
Let 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 delta 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]. The
generated events must set ctrlKey, shiftKey,
altKey, and metaKey from the
calculated global key state. 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.
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:
The Release Actionscommand
is used to release all the keys and pointer buttons
that are currently depressed.
This causes events to be fired
as if the state was released by an explicit series of actions.
It also clears all the internal state of the virtual devices.
This chapter describes interaction with various types of user prompts.
The common denominator for user prompts is that they are
modal windows requiring users to interact with them
before the event loop is unpaused
and control is returned to the current top-level browsing context.
A user prompt has an associated user prompt message
that is the string message shown to the user,
or null if the message length is 0.
The following table of simple dialogs
enumerates all supported simple dialogs,
along with the commands that are allowed to interact with it
as a non-normative reference:
To dismiss
the current user prompt,
do so as if the user would click the Cancel or OK button,
whichever is present, in that order.
To accept the current user prompt,
do so as if the user would click the OK button.
A user prompt handler is an enumerated attribute
defining what action the remote end must take
when a user prompt is encountered. This is defined by the
unhandled prompt behavior capability. The
following known prompt handling approaches table lists the
keywords and states for the attribute:
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.
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.
B. Security Considerations
A user agent can rely on a command-line flag
or a configuration option
to test whether to enable WebDriver,
or alternatively make the user agent initiate
or confirm the connection through
a privileged content document or control widget,
in case the user agent does not
directly implement the HTTP endpoints.
It is strongly suggested that user agents
require users to take explicit action to enable WebDriver,
and that WebDriver remains disabled
in publicly consumed versions of the user agent.
To prevent arbitrary machines on the network
from connecting and creating sessions,
it is suggested that only connections from
loopback devices are allowed by default.
The remote end can include
a configuration option to limit
the accepted IP range allowed to connect and make requests.
The default setting for this might be
to limit connections to the IPv4 localhost
CIDR range 127.0.0.0/8
and the IPv6 localhost address ::1. [RFC4632]
It is also suggested that user agents
make an effort to visually distinguish
a user agent session that is under control of WebDriver
from those used for normal browsing sessions.
This can be done through a browser chrome element
such as a “door hanger”,
colorful decoration of the OS window,
or some widget element that is prevalent in the window
so that it easy to identify automation windows.
C. 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 was originally developed by
the Selenium project, and is
based on crude approximations about an element's 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 boundaries of the viewport.
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,
invoke the Call(bot.dom.isShown,
null, element).
If doing so does not produce an error,
return the return value from this function call.
Otherwise return an error with error codeunknown error.
This function is typically exposed to GET requests
with a URI Template of
/session/{session id}/element/{element id}/displayed.
D. Acknowledgements
There have been a lot of people that have helped make
browser automation possible over the years
and thereby furthered the goals of this standard.
In particular, thanks goes to the
Selenium Open Source community,
without which this standard would never have been possible.
This standard is authored by
Aleksey Chemakin,
Andreas Tolfsen,
Andrey Botalov,
Clayton Martin,
Daniel Wagner-Hall,
David Burns,
Eran Messeri,
Erik Wilde,
Gábor Csárdi,
Sam Sneddon,
James Graham,
Jason Juang,
Jason Leyba,
Jim Evans,
John Jansen,
Luke Inman-Semerau,
Maja Frydrychowicz,
Malini Das,
Marc Fisher,
Mike Pennisi,
Ondřej Machulda,
Randall Kent,
Seva Lotoshnikov,
Simon Stewart,
Titus Fortner,
and Vangelis Katsikaros.
The work is coordinated and edited by
David Burns
and Simon Stewart.
Thanks to
Berge Schwebs Bjørlo,
Lukas Tetzlaff,
Malcolm Rowe,
Michael[tm] Smith,
Nathan Bloomfield,
Philippe Le Hégaret,
Robin Berjon,
Ross Patterson,
and Wilhelm Joys Andersen
for proofreading and suggesting areas for improvement.