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. A list of current W3C
publications and the latest revision of this technical report can be found
in the
W3C standards and drafts index.
Publication as an Editor's Draft does not
imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than a work in progress.
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 that the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
The WebDriver standard attempts to follow a number of design goals:
1.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.
1.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.
1.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.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
Conformance requirements phrased as algorithms
or specific steps may be implemented in any manner,
so long as the end result is equivalent.
Algorithms in this document are typically written with readability,
rather than performance, in mind.
3. Terminology
In equations, all numbers are integers,
addition is represented by “+”,
subtraction by “−”,
division by “÷”,
and bitwise OR by “|”.
The characters “(” and “)” are used to provide logical grouping in these contexts.
The mathematical function
min(value, value[, value])
returns the smallest item of two or more values.
Conversely, the function
max(value, value[, value])
returns the largest item of two or more values.
The mathematical function floor(value)
produces the largest integer, closest to positive infinity,
that is not larger than value.
A Universally Unique Identifier (UUID)
is a 128 bits long URN that requires no central registration process.
Generating a UUID means
Creating a UUID From Truly Random or Pseudo-Random Numbers,
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.
The readiness state of a remote end indicates
whether it is free to accept new connections. It must be false if the
implementation is an endpoint node and the list of active
HTTP sessions is not empty, or otherwise if the remote end is known to
be in a state in which attempting to create new sessions would
fail. In all other cases it must be 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 optimized
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 value has an associated error code.
When calling a fallible algorithm,
the construct “Let result be the result
of trying to call algorithm”
is equivalent to
Let temp be the result of calling algorithm.
If temp is an error return temp,
otherwise let result be temp's data field.
The result of getting a property with name
from object is defined as being the same as the result of
calling Object.[[GetOwnProperty]](name) on object.
The result of getting a property with default with
arguments name and default
from object is defined as being the same as the result of
calling
Object.[[GetOwnProperty]](name)
on object if that results in a value other
than undefined and default otherwise.
Setting a property with
arguments name and value on object
is defined as being the same as calling
Object.[[Put]](name, value) on object.
The result of JSON serialization with object
of type JSON Object is defined as the result of
calling stringify(object).
The result of JSON deserialization with text is defined as
the result of calling parse(text).
6.2 Commands
The WebDriver protocol is organized 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
known as remote end steps.
These provide the sequences 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.
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.
Remove each entry from endpoints for which the
concatenation of the URL prefix and the entry's URI
template does not have a valid expansion equal to
URL's path.
Let URL variables be a map with one
entry for each variable defined in URI template,
with the entry name equal to the template variable name, and the
entry value being the variable value required to expand the URI
template to match URL's path.
Return success with data
command and URL variables.
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