W3C

WebDriver

W3C Working Draft 12 March 2013

This version:
http://www.w3.org/TR/2013/WD-webdriver-20130312/
Latest published version:
http://www.w3.org/TR/webdriver/
Latest editor's draft:
http://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html
Previous version:
http://www.w3.org/TR/2013/WD-webdriver-20130117/
Editors:
Simon Stewart, Facebook
David Burns, Mozilla

Abstract

This specification defines the WebDriver API, a platform and language-neutral interface and associated wire protocol that allows programs or scripts to introspect into, and control the behaviour of, a web browser. The WebDriver API is primarily intended to allow developers to write tests that automate a browser from a separate controlling process, but may also be implemented in such a way as to allow in-browser scripts to control a — possibly separate — browser.

The WebDriver API is defined by a wire protocol and a set of interfaces to discover and manipulate DOM elements on a page, and to control the behaviour of the containing browser.

This specification also includes a normative reference serialisation (to JSON over HTTP) of the interface's invocations and responses that are to be used by browser vendors to ensure interoperability.

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 http://www.w3.org/TR/.

If you wish to make comments regarding this document, please email feedback to public-browser-tools-testing@w3.org. All feedback is welcome, and the editors will read and consider all feedback.

This specification is still under active development and may not be stable. Any implementors who are not actively participating in the preparation of this specification may find unexpected changes occurring. It is suggested that any implementors join the WG for this specification. Despite not being stable, it should be noted that this specification is strongly based on an existing Open Source project — Selenium WebDriver — and the existing implementations of the API defined within that project.

This document was published by the Browser Testing and Tools Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-browser-tools-testing@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

The WebDriver API aims to provide a synchronous API that can be used for a variety of use cases, though it is primarily designed to support automated testing of web apps.

1.1 Intended Audience

This specification is intended for implementors of the WebDriver API. It is not intended as light bed time reading.

1.2 Relationship of WebDriver API and Existing Specifications

Where possible and appropriate, the WebDriver API references existing specifications. For example, the list of boolean attributes for elements is drawn from the HTML5 specification. When references are made, this specification will link to the relevant sections.

1.3 Naming the Two Sides of the API

The WebDriver API can be thought of as a client/server process. However, implementation details can mean that this terminology becomes confusing. For this reason, the two sides of the API are called the "local" and the "remote" ends.

Local
The user-facing API. Command objects are sent and Response objects are consumed by the local end of the WebDriver API. It can be thought of as being "local" to the user of the API.
Remote
The implementation of the user-facing API. Command objects are consumed and Response objects are sent by the remote end of the WebDriver API. The implementation of the remote end may be on a machine remote from the user of the local end.

There is no requirement that the local and remote ends be in different processes. The IDL given in this specification and summarized in Appendix XXXX SHOULD be used as the basis for any conforming local end implementation.

1.4 Conformance Requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in [RFC2119]. The key word "OPTIONALLY" in the normative parts of this document is to be interpreted with the same normative meaning as "MAY" and "OPTIONAL".

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent.

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification [WEBIDL].

1.4.1 Conformance Classes

This specification describes the conformance criteria for both local (relevant to creating bindings for languages) and remote end implementations (relevant to browser vendors and server implementors). A final conformance class — intermediate node — is also specified. These represent those nodes situated between the local and remote ends.

2. Commands and Responses

The communication between the remote and local ends is performed via Command and Response objects. How these are encoded and transmitted between the remote and local ends is left undefined.

Although the encoding and transport mechanism is left undefined in this specification, implementors of the remote end MUST provide an implementation suitable for acting as the server-side of the JSON and HTTP protocol defined in Appendix F. This MAY take the form of a standalone executable that translates the JSON over HTTP protocol to the encoding and transport mechanism used by the remote end.

2.1 Command

interface Command {  
  attribute DOMString name;
  attribute dictionary parameters;
  attribute DOMString sessionId;
};

A command represents a call to a remote end to the session identified by the sessionId attribute. By default, the sessionId is null. The only time the null value is a valid sessionId is before a call to newSession. The name of the command to execute is held in the name, and this MUST be handled case-sensitively. It defaults to the null value. The parameters attribute is a map of named parameters to objects representing the value of the parameter. The default value is an empty array and this field MUST NOT be null.

2.2 Response

interface Response {
  readonly attribute DOMString sessionId;
  readonly attribute DOMString status;
  readonly attribute object value;
};

A Response represents the value returned from the remote end of the WebDriver API after executing a Command from the session identified by the sessionId attribute. The default value for the sessionId MUST be the sessionId used in the Command that this is a response to, unless the Command's sessionId was the null value, in which case a unique sessionId MUST be assigned (see newSession for how this is achieved).

Each Response has a status that indicates the success or failure of the method. Anything other than "success" indicates a failure. Each command lists the status strings it can return in the section of this specification in which it is defined, but the normative list of expected statuses is given below in the Status Codes section. This list MAY be extended by implementors of the specification, provided they follow the guidelines about extending the protocol.

The meat of the Response is in the value attribute. It's type is determined by the Command that has been executed. In this specification, each command definition will make clear what the expected return type is. The default value is the null value. In the case where the status indicates failure, the value is commonly the error text explaining the cause of the problem.

Note

In the case where a failure is indicated and the language used for implementing the local end supports throwing exceptions, the value is often used as the exception's message.

There is no requirement that implementations of Command and Response exhibit any behaviour: they MAY be simple data structures. Reading of values MUST be idempotent, and writing any particular value MUST NOT cause any other values on the Command or Response to change.

2.3 Processing Additional Fields on Commands and Responses

Any Command or Response MAY contain additional fields than those listed above. The content of fields MUST be maintained, unaltered by any intermediate nodes. There is no requirement to maintain the ordering of fields.

Note

This requirement exists to allow for extension of the protocol, and to allow implementors to decorate Commands and Responses with additional information, perhaps giving context to a series of messages or providing security information.

2.4 Status Codes

The WebDriver API indicates the success or failure of a command invocation via Response.status. The following values are used and have the following meanings.

Status Code Detail
element not selectable An attempt was made to select an element that cannot be selected.
element not visible An element command could not be completed because the element is not visible on the page.
ime engine activation failed An IME engine could not be started.
ime not available IME was not available.
invalid cookie domain An illegal attempt was made to set a cookie under a different domain than the current page.
invalid element coordinates The coordinates provided to an interactions operation are invalid.
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 DOM).
invalid selector Argument was an invalid selector (e.g. XPath/CSS).
javascript error An error occurred while executing user supplied JavaScript.
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 An attempt was made to operate on a modal dialog when one was not open.
no such dom An attempt was made to switch to a hosted Shadow DOM that does not exist.
no such element An element could not be located on the page using the given search parameters.
no such frame A request to switch to a frame could not be satisfied because the frame could not be found.
no such window A request to switch to a different window could not be satisfied because the window could not be found.
script timeout A script did not complete before its timeout expired.
session not created A new session could not be created.
stale element reference An element command failed because the referenced element is no longer attached to the DOM.
success The command executed successfully.
timeout An operation did not complete before its timeout expired.
unable to set cookie A request to set a cookie's value could not be satisfied.
unexpected alert open A modal dialog was open, blocking this operation.
unknown command A command could not be executed because the remote end is not aware of it.
unknown error An unknown error occurred in the remote end while processing the command.
unsupported operation Indicates that a command that should have executed properly cannot be supported for some reason.

2.5 Handling of Status Codes at the Local End

Status codes are returned from the remote end to the local end. The local end SHOULD convert these into a form appropriate for the implementation language. For example, in C the status codes might be converted to constant integer values, whereas in Java various exceptions could be thrown.

Implementations of the local end written in languages that support exceptions SHOULD make use of an exception hierarchy rooted on a WebDriverException (or similarly named base exception class). Where references to WebDriverException are made in this specification, we are referring to this local end conversion of status codes to local end exceptions.

Note

The reason for this is to allow users of the local end to easily handle the all expected failure modes of a local WebDriver implementation by catching the WebDriverException.

Note

It is strongly recommended that the WebDriverException contain as much diagnostic information as possible, including version numbers and details about the remote end. This is because experience suggests that when reporting errors from tests using WebDriver, users will simply cut-and-paste a stack trace of an exception. Adding this information to the exception makes the task of debugging problems considerably easier.

3. Browser Capabilities

Different browsers support different levels of various specifications. For example, some support SVG or the [SELECTORS-API], but only browsers that implement [WEBSTORAGE] will support LocalStorage. The WebDriver API provides a mechanism to query the supported capabilities of a browser. Each broad area of functionality within the WebDriver API has an associated capability string. Whether a particular capability MUST or MAY be supported — as well as fallback mechanisms for handling those cases where a capability is not supported — is discussed where the capability string is defined.

3.1 Capabilities

interface Capabilities {
    readonly attribute dictionary capabilities;
    boolean                           has (DOMString capabilityName);
    (DOMString or boolean or number)? get (DOMString capabilityName);
};

3.1.1 Attributes

capabilities of type dictionary, readonly
The underlying collection of capabilities, represented as a dictionary mapping strings to values which may be of type boolean, numerical or DOMString. The default value is an empty dictionary.

3.1.2 Methods

get
Get the value of the key matching capabilityName in the underlying capabilities or null if no value is defined.
ParameterTypeNullableOptionalDescription
capabilityNameDOMString
Return type: (DOMString or boolean or number), nullable
has
Queries the underlying capabilities to see whether the value is set. This MUST return true if the capabilities contain a key with the given capabilityName and the value of that key is defined. If the value is a boolean, this function MUST return that boolean value. If the value is null, an empty string or a 0 then this method MUST return false.
ParameterTypeNullableOptionalDescription
capabilityNameDOMString
Return type: boolean

A Capabilities instance MUST be immutable. If a mutable Capabilities instance is required, then the MutableCapabilities MUST be used instead.

Note

The "has" method is designed to provide a quick boolean check on whether or not a particular capability is set and can be used in an "if" statement in many languages. The "get" method returns the exact value. In the case of boolean values, this will be the same result as if "truthy" values are used (that is: get('falseValue') and get('unsetValue') are both false).

3.2 MutableCapabilities

interface MutableCapabilities : Capabilities {
    void set (DOMString capabilityName, (DOMString or boolean or number)? value);
};

3.2.1 Methods

set
Set the value of the given capabilityName to the given value. If the value is not a boolean, numerical type, a DOMString or the null value a WebDriverException SHOULD be thrown.
ParameterTypeNullableOptionalDescription
capabilityNameDOMString
value(DOMString or boolean or number)
Return type: void

In the case where the local and remote end are in the same process, it SHOULD be acceptable to use other types with the set method. If this is allowed, the value MUST be serialized to one of the acceptable types (boolean, numerical type, a string or the null value) before being sent out of process (such as transmitting from the local to the remote end). If this serialization is not possible, a WebDriverException MUST be thrown.

Note

As an example, perhaps the browser being automated supports user profiles. This may be modelled in code as a "Profile" object, leading to code such as:

		profile = Profile("some/user/directory")
		capabilities = MutableCapabilities()
		capabilities.set('profile', profile)
		driver = RemoteDriver(capabilities)
    

In this example, the profile represents a directory on the local disk. One way to serialize this would be to zip the contents of this profile and then encode it using base64 to allow it to be passed as a string.

4. Sessions

Non-normative summary: A session is equivalent to a single instantiation of a particular browser, including all child windows. The WebDriver API gives each session a unique ID stored as an opaque string that can be used to differentiate one session from another, allowing multiple browsers to be controlled on the same machine if needed, and allowing sessions to be routed via a multiplexer. This ID is sent with every Command and returned with every Response and is stored on the sessionId field.

4.1 Creating a Session

The process for successfully creating a session MUST be:

  1. The local end creates a new Capabilities or MutableCapabilities instance describing the desired capabilities for the session. The Capabilities object MUST be defined but MAY be empty.
  2. The local end MUST create a new Command with the "name" being "newSession" and the "parameters" containing an entry named "desiredCapabilities" with the value set to the Capabilities instance from the previous step. An optional "requiredCapabilities" entry MAY also be created and populated with a Capabilities instance. The "sessionId" fields SHOULD be left empty.
  3. The Command is transmitted to the remote end.
  4. The remote end MUST examine the "requiredCapabilities" parameter if specified, SHOULD examine the "desiredCapabilities" parameter, and MUST create a new session matching as many of the Capabilities as possible. How the new session is created depends on the implementation of this specification.
    • If any of the "requiredCapabilities" cannot be fulfilled by the new session, the remote end MUST quit the session and return the session not created error code. The sessionId of the Response object MUST be left as the default value unless the Command had the sessionId set, in which case that value MUST be used. The error message SHOULD list all unmet required capabilities though only a single required capability MUST be given.
    • If a capability is listed in both the requiredCapabilities and desiredCapabilities, the value in the requiredCapabilities MUST be used.
  5. The session MUST be assigned a sessionId which MUST be unique for each session (a UUID SHOULD be used). Generating the sessionId MAY occur before the session is created. If the Command object had the "sessionId" field set, this MAY be discarded in favour of the freshly generated sessionId. Because of this, it is recommended that sessionId generation be done on the remote end. If the sessionId has already been used, a Response MUST be sent with the status code set to session not created and the value being an explanation that the sessionId has previously been used.
  6. The remote end MUST create a new Response object, with the following fields MUST be set to:
    • "sessionId": the sessionId associated with this session.
    • "value": a Capabilities instance. The keys of this Capabilities instance MUST be the strings given in each of the supported capabilities as defined in the relevant sections of this specification. Supported functionality MUST be included in this Capabilities instance, while unsupported functionality MAY be omitted.
    • "status": the success error code.
  7. The Response is returned to the local end.

There is no requirement for the local end to validate that some or all of the fields sent on the Capabilities associated with the Command match those returned in the Response.

As stated, when returning the value of the Response, the remote end MUST include the capability names and values of all supported capabilities from this specification. They MAY also include any additional capability names and values of supported capabilities implemented independently of this specification. Local ends MAY choose to ignore this additional information. Intermediate nodes between the local and remote ends MAY interpret the capabilities being returned.

If the browserName is given as a desired capability and omitted from the required capabilities, and the returned browserName value does not match the requested one, local ends SHOULD issue a warning to the user. How this warning is issued is undefined, but one implementation could be a log message. In this particular case, local ends MAY chose to change the Response's status code to session not created, and modify the value to explain the cause, including the value originally returned as the browserName capability. If this is done, the local end MUST ensure that the remote end quits the session.

4.1.1 Capability Names

The following keys SHOULD be used in the Capabilities instances. They all default to the null string.

browserName
The name of the desired browser as a string.
browserVersion
The version number of the browser, given as a string.
platformName
The OS that the browser is running on, matching any of the platform names given below.
platformVersion
The version of the OS that the browser is running on as a string.
4.1.1.1 Platform Names

The following platform names are defined and MUST be used, case sensitively, for the "platformName" unless the actual platform being used is not given in this list:

  • ANDROID
  • IOS
  • LINUX
  • MAC
  • UNIX
  • WINDOWS

In addition "ANY" MAY be used to indicate the underlying OS is either unknown or does not matter.

Implementors MAY add additional platform names. Until these are standardized, these MUST follow the conventions outlined in extending the protocol section with the exception that the vendor prefix SHOULD omit the leading "-" character.

Note

For example, Mozilla's Firefox OS could be described as either "-MOZ-FIREFOXOS" or "MOZ-FIREFOX". The latter makes it easier for local ends to specify an enum of supported platforms and is therefore recommended in this case.

4.1.2 Error Handling

The following status codes MUST be returned by the "newSession" command:

success
The session was successfully created. The "value" field of the Response MUST contain a Capabilities object describing the session.
timeout
The new session could not be created within the time allowed for command execution on the remote end. This time MAY be infinite (in which case this status won't be seen). The "value" field of the Response SHOULD contain a string explaining that a timeout has occurred, but it MAY be left as the null value or filled with the empty string.
unknown error
An unhandled error of some sort has occurred. The "value" field of the Response SHOULD contain a more detailed description of the error as a string.

4.1.3 Remote End Matching of Capabilities

This section is non-normative.

The suggested order for comparing keys in the Capabilities instance when creating a session is:

  1. browserName
  2. browserVersion
  3. platform
  4. platformVersion

For all comparisons, if the key is missing (as determined by a call to Capability.has() returning "false"), that particular criteria shall not factor into the comparison.

6. Controlling Windows

6.1 Defining "window" and "frame"

Within this specification, a window equates to [HTML5]'s top level browsing context. Put another way, within this spec browser tabs are counted as separate windows.

TODO: define "frame"

6.2 Window Handles

Each window has a "window handle" associated with it. This is an opaque string which MUST uniquely identify the window within the session and MUST NOT be "current". This MAY be a UUID. The "getWindowHandle" command can be used to obtain the window handle for the window that commands are currently acting upon:

Command Name getWindowHandle
Parameters None
Return Value {DOMString} The opaque string which uniquely identifies this window within the session.

6.3 Iterating Over Windows

Command Name getWindowHandles
Parameters None
Return Value {DOMString[]} An array containing a window handle for every open window in this session.

This array of returned strings MUST contain a handle for every window associated with the browser session and no others. For each returned window handle the javascript expression "window.top.closed" (or equivalent) MUST evaluate to false at the time the command is being executed.

The ordering of the array elements is not defined, but MAY be determined by iterating over each top level browser window and returning the tabs within that window before iterating over the tabs of the next top level browser window. For example, in the diagram below, the window handles should be returned as the handles for: win1tab1, win1tab2, win2.

Two top level windows. The first window has two tabs, lablled win1tab1 and win1tab2. The second window has only one tab labelled win2
Note

This implies that the correct way to determine whether or not a particular interaction with the browser opens a new window is done by obtaining the set of window handles before the interaction is performed and comparing with the set after the action is performed.

6.4 Closing Windows

Command Name close
Parameters None
Return Value None

The close command closes the window that commands are currently being sent to. If this means that a call to get the list of window handles would return an empty list, then this close command MUST be the equivalent of calling "quit". That is, if the final window of a session is closed, then the session quits.

Once the window has closed, future commands MUST return a status code of no such window until a new window is selected for receiving commands.

6.5 Resizing and Positioning Windows

Command Name setWindowSize
Parameters "windowHandle" {DOMString} The handle referring to the window to resize.
"width" {number} The new window width in pixels.
"height" {number} The new window height in pixels.
Return Value None
Errors unsupported operation if the window could not be resized.
Command Name getWindowSize
Parameters "windowHandle" {DOMString} The handle referring to the window to resize.
Return Value An object with two keys:
"width" {number} The width of the specified window in pixels.
"height" {number} The height of the specified window in pixels.
Command Name maximizeWindow
Parameters "windowHandle" {DOMString} The handle referring to the window to resize.
Return Value None
Errors unsupported operation if the window could not be resized.
Command Name fullscreenWindow
Parameters "windowHandle" {DOMString} The handle referring to the window to resize.
Return Value None
Errors unsupported operation if the window could not be resized.

Each of these commands accept the window handles returned by "getWindowHandles" and "getWindowHandle". In addition, the window handle may be "current", in which case the window that commands are currently being handled by MUST be acted upon.

The "width" and "height" values refer to the javascript "window.outerheight" and "window.outerwidth" properties. For those browsers that do not support these properties, these represent the height and width of the whole browser window including window chrome and window resizing borders/handles.

After setWindowSize, the browser window MUST NOT be in the maximised state.

After maximizeWindow, the browser window MUST be left as if the maximise button had been pressed if, and only if, the window manager of the OS supports this concept; it is not sufficient to leave the window "restored", but with the full screen dimensions.

After fullscreenWindow, the browser window MUST be in full-screen mode. For those operating systems that support the concept, this MUST be equivalent to if the user requested the window be full screen. If the OS does not support the concept of full-screen, then this command is a synonym for "maximizeWindow".

If a request is made to resize a window to a size which cannot be performed (e.g. the browser has a minimum, or fixed window size, or the operating system does not support resizing windows at all as is the case in many phone OSs), an unsupported operation status code MUST be returned.

6.6 Scaling the Content of Windows

TODO

7. Where Commands Are Handled

Web applications can be composed of multiple windows and/or frames. For a normal user, the context in which an operation is performed is obvious: it's the window or frame that currently has OS focus and which has just received user input. The WebDriver API does not follow this convention. There is an expectation that many browsers using the WebDriver API may be used at the same time on the same machine. This section describes how WebDriver tracks which window or frame is currently the context in which commands are being executed.

7.1 Default Content

WebDriver's default content is [HTML5]'s top level browsing context for the window that is currently receiving WebDriver commands.

When a WebDriver instance is started and a single browser window is opened, the default content of that window is automatically selected for receiving further commands. If more than one window is opened when the session starts, then the user MUST first select which window to act upon using the switchToWindow command. Until the user selects a window, all commands must return a status code of no such window.

7.2 Switching Windows

Command Name switchToWindow
Parameters "name" {DOMString} The identifier used for a window.
Return Value None
Errors no such window if no matching window can be found

The "switchToWindow" command is used to select which window MUST be used as the context for processing commands. In order to determine which window should be used for accepting commands, the "switchToWindow" command MUST iterate over all windows. For each window, the following MUST be compared — in this order — with the "name" parameter:

  1. A window handle, obtained from "getWindowHandles" or "getWindowHandle".
  2. The window name, as defined when the window was opened (the value of "window.name")
  3. The "id" attribute of the window.

If no windows match, then a "no such window" status code MUST be returned, otherwise the "default content" of the first window to match will be selected for accepting commands.

7.3 Switching Frames

Command Name switchToFrame
Parameters "id" {?(DOMString|number|!WebElement=)} The identifier used for a window.
Return Value None
Errors no such frame if no matching frame can be found

The "switchToFrame" command is used to select which frame within a window MUST be used as the context for handling future commands. All frame switching is taken from the current context from which commands are currently being handled. The "id" parameter can be one of a string, number of an element. WebDriver implementations MUST determine which frame to select using the following algorithm:

  1. If the "id" is a number the current context is set to the equivalent of the JS expression "window.frames[n]" where "n" is the number and "window" is the DOM window represented by the current context.
  2. If the "id" is null, the current context is set to the default context.
  3. If the "id" is a string:
    1. If the JS expression "window.frames[id]" evaluated in the current context returns a window, where "id" is the value of the the "id" parameter, the current context is set to that.
    2. Otherwise for each value of "window.frames" (referred to as win):
      1. If win has a "name" property or attribute equal to the "id" parameter, this becomes the current context.
      2. If win has an "id" property or attribute equal to the "id" parameter, this becomes the current context.
  4. If the "id" represents a WebElement, and the corresponding DOM element represents a FRAME or an IFRAME, and the WebElement is part of the current context, the "window" property of that DOM element becomes the current context.

In all cases if no match is made a "no such frame" status code MUST be returned.

If the indicated frame exists, frame switching MUST succeed even if doing so would violate the normal security constraints in place within the Javascript sandbox.

7.4 Switching to Hosted Shadow DOMs

Capability NameType
shadowDomboolean

If a browser implements the Shadow DOM specification, it MUST support the ability to access shadow subtrees. This is done using the switchToSubTree command:

Command Name switchToSubTree
Parameters "element" {!WebElement=} The shadow host.
"index" {int} The index of the shadow subtree. Defaults to 0.
Return Value None
Errors no such dom if the element is not a shadow host, or if the indexed shadow subtree does not exist.

When executing this command, Shadow DOM subtrees are indexed in the order that they were added to the host. That is, the "oldest" subtree is at index 0, and the "youngest" subtree at the highest sequentially numbered index.

Where the Shadow DOM is supported, all commands in WebDriver MUST operate on the currently selected Shadow DOM subtree unless the command itself declares otherwise.

8. Running Without Window Focus

All browsers must comply with the focus section of the [HTML5] spec. In particular, the requirement that the active element within a top-level browsing context be independent of whether or not the top-level browsing context itself has system focus MUST be followed.

Note

This requirement is put in place to allow efficient machine utilization when using the WebDriver API to control several browsers independently on the same desktop

9. Elements

One of the key abstractions of the WebDriver API is the WebElement interface. Each instance of this interface represents an Element as defined in the [DOM4] specification. Because the WebDriver API is designed to allow users to interact with apps as if they were actual users, the capabilities offered by the WebElement interface are somewhat different from those offered by the DOM Element interface.

Each WebElement instance must have an ID, which is distinct from the value of the DOM Element's "id" property. The ID for every WebElement representing the same underlying DOM Element MUST be the same. The IDs used to refer to different underlying DOM Elements MUST be unique within the session over the entire duration of the session.

Note

This requirement around WebElement IDs allows for efficient equality checks when the WebDriver API is being used out of process.

interface WebElement {
    readonly attribute DOMString id;
};

9.1 Attributes

id of type DOMString, readonly
The WebDriver ID of this particular element. This SHOULD be a UUID.

This section of the specification covers finding elements. Later sections deal with querying and interacting with these located elements. The primary interface used by the WebDriver API for locating elements is the SearchContext.

9.2 Lists of WebElements

The primary grouping of WebElement instances is an array of WebElement instances

A reference to an WebElement is obtained via a SearchContext. The key interfaces are:

interface Locator {
    readonly attribute DOMString strategy;
    readonly attribute DOMString value;
};

Attributes

strategy of type DOMString, readonly
The name of the strategy that should be used to locate elements. The default value is the null value
value of type DOMString, readonly
The value to pass to the element finding strategy. The default value is the null value.
interface SeachContext {
    WebElement[] findElements (Locator locator);
    WebElement   findElement (Locator locator);
};

Methods

findElement
ParameterTypeNullableOptionalDescription
locatorLocator
Return type: WebElement
findElements
ParameterTypeNullableOptionalDescription
locatorLocator
Return type: WebElement[]

9.3 Element Location Strategies

All element location strategies MUST return elements in the order in which they appear in the current document.

9.3.1 CSS Selectors

Capability Name Type
cssSelectors boolean

Strategy name: css selector

If a browser supports the CSS Selectors API ([SELECTORS-API]) it MUST support locating elements by CSS Selector. If the browser does not support the browser CSS Selector spec it MAY choose to implement locating by this mechanism. If the browser can support locating elements by CSS Selector, it MUST set the "cssSelector" capability to boolean true when responding to the "newSession" command. Elements MUST be returned in the same order as if "querySelectorAll" had been called with the Locator's value. Compound selectors are allowed.

9.3.2 ECMAScript

Finding elements by ecmascript is covered in the ecmascript part of this spec.

9.3.3 Element ID

Strategy name: id

This strategy MUST be supported by all WebDriver implementations.

The HTML5 specification ([HTML5]) states that element IDs must be unique within their home subtree. Sadly, this uniqueness requirement is not always met. Consequently, this strategy is equally valid for finding a single element or groups of elements. In the case of finding a single WebElement, this MUST be functionally identical to a call to "document.getElementById()" from the Web DOM Core specification ([DOM4]). When finding multiple elements, this is equivalent to an CSS query of "#value" where "value" is the ID being searched for with all "'" characters being properly escaped..

9.3.6 XPath

Strategy name: xpath

All WebDriver implementations MUST support finding elements by XPath 1.0 [XPATH] with the edits from section 3.3 of the [HTML5] specification made. If no native support is present in the browser, a pure JS implementation MAY be used. When called, the returned values MUST be equivalent of calling "evaluate" function from the DOM Level 3 XPath spec [DOM-LEVEL-3-XPATH] with the result type set to "ORDERED_NODE_SNAPSHOT_TYPE (7).

10. Reading Element State

10.1 Determining Visibility

The following steps MUST be used to determine if an element is visible to a user. This specification refers to this as the element being "shown".

Note

Essentially, this attempts to model whether or not a user of the browser could possibly find a way to view the WebElement without resizing the browser window.

Command Name isDisplayed
Parameters "id" {DOMString} The ID of the WebElement on which to operate.
Return Value {boolean} Whether the element is shown.
Errors stale element reference if the element referenced is no longer attached to the DOM.

10.2 Determining Whether a WebElement Is Selected

The remote end MUST determine whether a WebElement is selected using the following algorithm:

  1. If the item is not "selectable", the WebElement is not selected. A selectable element is either an OPTION element or an INPUT element of type "checkbox" or "radio".
  2. If the DOM node represented by the WebElement is an OPTION element, the "selectedness" of the element, as defined in [HTML5] determines whether the element is selected.
  3. Otherwise, the value of the DOM node's "checked" property determines whether the element is selected. This MUST reflect the element's "checkedness" as defined in [HTML5].
Command Name isSelected
Parameters "id" {string} The ID of the WebElement on which to operate.
Return Value {boolean} Whether the element is selected, according to the above algorithm.
Errors stale element reference if the element referenced is no longer attached to the DOM.

10.3 Reading Attributes and Properties

Although the [HTML5] spec is very clear about the difference between the properties and attributes of a DOM element, users are frequently confused between the two. Because of this, the WebDriver API offers a single command ("getElementAttribute") which covers the case of returning either of the value of a DOM element's property or attribute. If a user wishes to refer specifically to an attribute or a property, they should evaluate Javascript in order to be unambiguous. In this section, the "attribute" with name name shall refer to the result of calling the Javascript "getAttribute" function on the element, with the following exceptions:

Note

These aliases provide the commonly used names for element properties.

Command Name getElementAttribute
Parameters "id" {DOMString} The ID of the WebElement on which to operate.
"name" {DOMString} The name of the property of attribute to return.
Return Value {DOMString|null} The value returned by the above algorithm, coerced to a nullable string, or null if no value is defined.
Errors stale element reference If the element is no longer attached to the DOM.

10.4 Rendering Text

All WebDriver implementations MUST support getting the visible text of a WebElement, with excess whitespace compressed.

The following definitions are used in this section:

Whitespace
Any text that matches the ECMAScript regular expression class \s.
Whitespace excluding non-breaking spaces
Any text that matches the ECMAScript regular expression [^\S\xa0]
Block level element
A block-level element is one which is not a table cell, and whose effective CSS display style is not in the set ['inline', 'inline-block', 'inline-table', 'none', 'table-cell', 'table-column', 'table-column-group']
Horizontal whitespace characters
Horizontal whitespace characters are defined by the ECMAScript regular expression [\x20\t\u2028\u2029].

The expected return value is roughly what a text-only browser would display. This means that on browsers that support the Shadow DOM, this algorithm MUST operate on the section of the rendered DOM underneath the DOM node represented by this WebElement. The algorithm for determining this text is as follows:

Let lines equal an empty array. Then:

  1. For each child of node, at time of execution, in order:
    1. Get whitespace, text-transform, and then, if child is:
      • a node which is not visible, do nothing
      • a [DOM4] text node let text equal the nodeValue property of child. Then:
        1. Remove any zero-width spaces (\u200b), form feeds (\f) or vertical tab feeds (\v) from text.
        2. Canonicalize any recognized single newline sequence in text to a single newline (greedily matching (\r\n|\r|\n) to a single \n)
        3. If the parent's effective CSS whitespace style is 'normal' or 'nowrap' replace each newline (\n) in text with a single space character (\x20). If the parent's effective CSS whitespace style is 'pre' or 'pre-wrap' replace each horizontal whitespace character with a non-breaking space character (\xa0). Otherwise replace each sequence of horizontal whitespace characters except non-breaking spaces (\xa0) with a single space character
        4. Apply the parent's effective CSS text-transform style as per the CSS 2.1 specification ([CSS21])
        5. If last(lines) ends with a space character and text starts with a space character, trim the first character of text.
        6. Append text to last(lines) in-place
      • an element which is visible. If the element is a:
        • BR element: Push '' to lines and continue
        • Block-level element and if last(lines) is not '', push '' to lines.
        And then recurse depth-first to step 1 at the beginning of the algorithm with child set to the current element
      • If element is a TD element, or the effective CSS display style is 'table-cell', and last(lines) is not '', and last(lines) does not end with whitespace append a single space character to last(lines) [Note: Most innerText implementations append a \t here]
      • If element is a block-level element: push '' to lines
  2. The string MUST then have the white space normalised as defined in the [XPATH] normalize-space function which is then returned.

11. Executing Javascript

Note

Open questions: What happens if a user's JS triggers a modal dialog? Blocking seems like a reasonable idea, but there is an assumption that WebDriver is not threadsafe. What happens to unhandled JS errors? Caused by a user's JS? Caused by JS on a page? How does a user of the API obtain the list of errors? Is that list cleared upon read?

If a browser supports JavaScript and JavaScript is enabled, it MUST set the "javascriptEnabled" capability to true, and it MUST support the execution of arbitrary JavaScript.

Capability NameType
javascriptEnabledboolean

11.1 Javascript Command Parameters

The Argument type is defined as being {(number|boolean|DOMString|WebElement|dictionary|Argument[])?}

interface JavascriptCommandParameters {
    readonly attribute DOMString  script;
    readonly attribute Argument[] args;
};

11.1.1 Attributes

args of type array of Argument, readonly
The parameters to the function defined by script.
script of type DOMString, readonly
The JavaScript to execute, in the form of a Function body.

When executing Javascript, it MUST be possible to reference the args parameter using the function's arguments object. The arguments MUST be in the same order as defined in args. Each WebDriver implementation MUST preprocess the values in args using the following algorithm:

For each index, index in args, if args[index] is...

  1. a number, boolean, DOMString, or null, then let args[index] = args[index].
  2. an array, then recursively apply this algorithm to args[index] and assign the result to args[index].
  3. a dictionary, then recursively apply this algorithm to each value in args[index] and assign the result to args[index].
  4. a WebElement, then:
    1. If the element's ID does not represent a DOMElement, or it represents a DOMElement that is no longer attached to the document's tree, then the WebDriver implementation MUST immediately abort the command and return a stale element reference error.
    2. Otherwise, let args[index] be the underlying DOMElement.
  5. Otherwise WebDriver implementations MAY throw an unknown error indicating the index of the unhandled parameter but SHOULD attempt to convert the value into a dictionary.

11.2 Synchronous Javascript Execution

Command Name executeScript
Parameters "script" {DOMString} The script to execute.
"args" {Argument[]} The script arguments.
Return Value {Argument} The value returned by the script, or null.
Errors javascript error if the executing script threw an exception.
stale element reference if a WebElement referenced is no longer attached to the DOM.
unknown error if an argument or the return value is of an unhandled type.

When executing JavaScript, the WebDriver implementations MUST use the following algorithm:

  1. Let window be the Window object for WebDriver's current command context.
  2. Let script be the DOMString from the command's script parameter.
  3. Let fn be the Function object created by executing new Function(script);
  4. Let args be the JavaScript array created by the pre-processing algorithm defined above.
  5. Invoke fn.apply(window, args);
  6. If step #5 threw, then:
    1. Let error be the thrown value.
    2. Set the response's status status to javascript error.
    3. Set the response value to a dictionary, dict.
    4. If error is an Error, then set a "message" entry in dict whose value is the DOMString defined by error.message.
    5. Otherwise, set a "message" entry in dict whose value is the DOMString representation of error.
  7. Otherwise:
    1. Let result be the value returned by the function in step #5.
    2. Set the command's response status to success.
    3. Let value be the result of the following algorithm:
      1. If result is:
        1. undefined or null, return null.
        2. a number, boolean, or DOMString, return result.
        3. a DOMElement, then return the corresponding WebElement for that DOMElement.
        4. an array or NodeList, then return the result of recursively applying this algorithm to result.
        5. an object, then return the dictionary created by recursively applying this algorithm to each property in result.
    4. Set the response value to value.
  8. Return the response.

11.3 Asynchronous Javascript Execution

Command Name executeAsyncScript
Parameters "script" {DOMString} The script to execute.
"args" {Argument[]} The script arguments.
Return Value {Argument} The value returned by the script, or null.
Errors javascript error if the executing script threw an exception.
stale element reference if a WebElement referenced is no longer attached to the DOM.
Timeout if the callback is not called within the time specified by the "script" timeout.
unknown error if an argument or the return value is of an unhandled type.

When executing asynchronous JavaScript, the WebDriver implementation MUST use the following algorithm:

  1. Let timeout be the value of the last "script" timeout command, or 0 if no such commands have been received.
  2. Let window be the Window object for WebDriver's current command context.
  3. Let script be the DOMString from the command's script parameter.
  4. Let fn be the Function object created by executing new Function(script);
  5. Let args be the JavaScript array created by the pre-processing algorithm defined above.
  6. Let callback be a Function object pushed to the end of args.
  7. Register a one-shot timer on window set to fire timeout milliseconds in the future.
  8. Invoke fn.apply(window, args);
  9. If step #8 threw, then:
    1. Let error be the thrown value.
    2. Set the response status to javascript error.
    3. Set the response value to a dictionary, dict.
    4. If error is an Error, then set a "message" entry in dict whose value is the DOMString defined by error.message.
    5. Otherwise, set a "message" entry in dict whose value is the DOMString representation of error.
  10. Otherwise, the WebDriver implementation MUST wait for one of the following to occur:
    1. if the timer from step #7 fires, the WebDriver implementation MUST immediately set the response status to Timeout and return.
    2. if the window fires an unload event, the WebDriver implementation MUST immediately set the response status to JavascriptError and return with the error message set to "Javascript execution context no longer exists.".
    3. if the callback function is invoked, then:
      1. Let result be the first argument passed to callback.
      2. Set the command's response status to Success.
      3. Let value be the result of the following algorithm:
        1. If result is:
          1. undefined or null, return null.
          2. a number, boolean, or DOMString, return result.
          3. a DOMElement, then return the corresponding WebElement for that DOMElement.
          4. an array or NodeList, then return the result of recursively applying this algorithm to result. WebDriver implementations SHOULD limit the recursion depth.
          5. an object, then return the dictionary created by recursively applying this algorithm to each property in result.
      4. Set the command's response value to value.
    4. Return the response.

11.4 Reporting Errors

12. Cookies

This section describes the interaction with cookies as described in Web DOM Core Specification ([DOM-LEVEL-2-CORE]). When retrieving and setting a cookie it MUST be in the format of a Cookie.

Retrieving all cookies from the page:

Command Name getCookies
Parameters None
Return Value {DOMString[]} A list of ordinary cookies that are currently visible on the page.

Remote ends MUST return all cookies that are available in document.cookie via Javascript. In addition, remote ends SHOULD return any HTTP-Only cookies that are associated with the current page.

Setting a cookie:

Command Name addCookie
Parameters "cookie" {object} A Cookie defining the cookie to be added.
Return Value {object[]} A list of cookies in the Cookie format.
Throws invalid cookie domain - If the cookie's domain is not visible from the current page.
unable to set cookie - If attempting to set a cookie on a page that does not support cookies (e.g. pages with mime-type text/plain).

13. Timeouts

This section describes how timeouts and implicit waits are handled within WebDriver

The "timeouts" command is used to set the value of a timeout that a command can execute for.

Command Name timeouts
Parameters "type" {DOMString} The type of operation to set the timeout for. Valid values are: "implicit", "page load", "script"
"ms" - {number} The amount of time, in milliseconds, that time-limited commands are permitted to run.
Return Value None
Errors None

14. User Input

The WebDriver API offers two ways of interacting with elements, either with a set of low-level "do as I say" commands, or a high-level "do as I mean" set of commands. The former are offered to allow precise emulation of user input. The latter are offered as a convenience to cover the common case, and can conceivably be implemented on top of the lower level primitive operations.

14.1 Interactable elements

Some input actions require the element to be interactable. The following conditions must be met for the element to be considered interactable:

14.2 Low Level Commands

The low level commands provide a mechanism for precisely stating how a user can interact with the browser.

Input events generated by the WebDriver API User SHOULD indistinguishable from those generated by a real user interacting with the browser. It is therefore recommended that input events SHOULD NOT be generated at the DOM level using the "createEvent" API from [DOM4] or similar. The order of preference for methods to implement WebDriver's emulatation of user input is:

  1. Injection into the browser's event queue.
  2. Sending OS-specific input messages to the browser's window. This has the disadvantage that the browser being automated may not be properly isolated from a user accidentally modifying input device state.
  3. Use of Javascript to inject events at the DOM level.
  4. Use of an OS-level accessibility API. The disadvantage of this method is that the browser's window must be focused. As a result, multiple tests cannot run in parallel.

TODO: Describe the commands for basic control of keyboard and mouse.

14.2.1 Mouse

TODO: Ensure that this section mentions that mouse state MUST be maintained if the page is not related and MAY be maintained if the browser navigates to a new page.

TODO: Handle the case where the browser is on a mouse-less device (eg. mobile phone)

14.2.2 Keyboard

14.2.2.1 IME

14.2.3 Touch

TODO: Define capability to capture the concept that a browser supports touch events

14.3 High Level Commands

These higher level commands SHOULD be built on top of the low level commands, and implement a user friendly way of interacting with a page in a way that models common user expectations.

14.3.1 Clicking

partial interface WebElement {
    void click ();
};
14.3.1.1 Methods
click
Click in the middle of the WebElement instance. The middle of the element is defined as the middle of the box returned by calling getBoundingClientRect on the underlying DOM Element, according to the [CSSOM-VIEW] spec. If the element is outside the viewport (according to the [CSS21] spec), the implementation SHOULD bring the element into view first. The implementation MAY invoke scrollIntoView on the underlying DOM Element. The element MUST be visible, as defined in section 10.1. See the note below for when the element is obscured by another element. Exceptions:
  • Links (A elements): Clicking happens in the middle of the first visible bounding client rectangle. This is to overcome overflowing links where the middle of the bounding client rectangle does not actually fall on a clickable part of the link.
  • SELECT elements without the "multiple" attribute set. Clicking on the select element SHOULD open the drop down menu. The next click, on any element, MUST close this menu.
  • Clicking directly on an OPTION element (without clicking on the parent SELECT element previously) MUST open a selection menu, as if the SELECT option was clicked first, then click on the OPTION before finally closing the SELECT element's menu. The SELECT menu MUST be closed once the action is complete.

The possible errors for this command:

This command MUST use either the mouse or touch mechanisms for emulating the user input. In the case where the browser being automated supports only mouse input or both mouse and touch input, the low-level mouse mechanisms MUST be used. If the browser only supports touch input, the low level touch inputs MUST be used.

No parameters.
Return type: void
Note

As the goal is to emulate users as closely as possible, the implementation SHOULD NOT allow clicking on elements that are obscured by other elements. If the implementation forbids clicking on obscured elements, an element not visible response MUST be returned and this SHOULD have an explantory message explaining the reason. The implementation SHOULD try to scroll the element into view, but in case it is fully obscured, it SHOULD NOT be clickable.

14.3.2 Typing keys

A requirement for key-based interaction with an element is that it is interactable. Typing into an element is permitted if one of the following conditions is met:

  • The element is focusable as defined in the editing section of the [HTML5] spec.
  • The element is allowed to be the activeElement. In addition to focusable elements, this allows typing to the BODY element.
  • In an HTML5 document, the element is editable as a result of having its contentEditable attribute set or the containing document is in designMode.
  • The underlying browser implementation would allow keyboard input to directed to the element (eg. an HTML 4 document with a DIV marked as being contentEditable)

Prior to any keyboard interaction, an attempt to shift focus to the element MUST be attempted if the element does not currently have the focus. This is the case if one of the following holds:

  • The element is not already the document's active element.
  • The owner document of the element to be interacted with is not the focused document.

In case focusing is needed, the implementation MUST follow the focusing steps as described in the focus management section of the [HTML5] spec. The focus MUST NOT leave the element at the end of the interaction, other than as a result of the interaction itself (i.e. when the tab key is sent).

partial interface WebElement {
    void clear ();
    void sendKeys (string[] keysToSend);
};
14.3.2.1 Methods
clear
Clears the value of the element.
No parameters.
Return type: void
sendKeys
Sends a sequence of keyboard events representing the keys in the keysToSend parameter.

Caret positioning: If focusing was needed, after following the focusing steps, the caret MUST be positioned at the end of the text currently in the element. At the end of the interaction, the caret MUST be positioned at the end of the typed text sequence, unless the keys sent position it otherwise (e.g. using the LEFT key).

There are four different types of keys that are emulated:

  • Character literals - lower-case symbols.
  • Uppercase letters and symbols requiring the SHIFT key for typing.
  • Modifier keys
  • Special keys
The rest of this section details the values used to represent the different keys, as well as the expected behaviour for each key type.
ParameterTypeNullableOptionalDescription
keysToSendstring[]
Return type: void

When emulating user input, the implementation MUST generate the same sequence of events that would have been produced if a real user was sitting in front of the keyboard and typing the sequence of characters. In cases where there is more than one way to type this sequence, the implementation MUST choose one of the valid ways. For example, typing AB may be achieved by:

  • Holding down the Shift key
  • Pressing the letter 'a'
  • Pressing the letter 'b'
  • Releasing the Shift key
Alternatively, it can be achieved by:
  • Holding down the Shift key
  • Pressing the letter 'a'
  • Releasing the Shift key
  • Holding down the Shift key
  • Pressing the letter 'b'
  • Releasing the Shift key

Or by simply turning on the CAPS LOCK first.

The implementation MAY use the following algorithm to generate the events. If the implementation is using a different algorithm, it MUST adhere to the requirements listed below.

For each key, key in keysToSend, do

  1. If key is a lower-case symbol:
    1. If the Shift key is not pressed:
      1. Generate a sequence of key-down, key-press and key-up events with key as the character to emulate
    2. else (The Shift key is pressed)
      1. let uppercaseKey be the upper-case character matching key
      2. Generate a sequence of key-down, key-press and key-up events with uppercaseKey as the character to emulate
  2. Else if key is an upper-case symbol:
    1. If the Shift key is not pressed:
      1. Generate a key-down event of the Shift key.
      2. Generate a sequence of key-down, key-press and key-up events with key as the character to emulate
      3. Generate a key-up event of the Shift key.
    2. else (The Shift key is pressed)
      1. Generate a sequence of key-down, key-press and key-up events with key as the character to emulate
  3. Else if key represents a modifier key:
    1. let modifier be the modifier key represented by key
    2. If modifier is currently held down:
      1. Generate a key-up event of modifier
    3. Else:
      1. Generate a key-down event of modifier
    4. Maintain this key state and use it to modify the input until it is pressed again.
  4. Else if key represents the NULL key:
    1. Generate key-up events of all modifier keys currently held down.
    2. All modifier keys are now assumed to be released.
  5. Else if key represents a special key:
    1. Translate key to the special key it represents
    2. Generate a sequence of key-down, key-press and key-up events for the special key.

Once keyboard input is complete, an implicit NULL key is sent unless the final character is the NULL key.

Any implementation MUST comply with these requirements:

  • For uppercase letters and symbols that require the Shift key to be pressed, there are two options:
    • A single Shift key-down event is generated before the entire sequence of uppercase letters.
    • Before each such letter or symbol, a Shift key-down event is generated. After each letter or symbol, a Shift key-up event is generated.
  • A user-specified Shift press implies capitalization of all following characters.
  • If a user-specified Shift press precedes uppercase letters and symbols, a second Shift key-down event MUST NOT be generated. In that case, a Shift key-up event MUST NOT be generated implicitly by the implementation.
  • The NULL key releases all currently held down modifier keys.
  • The state of all modifier keys must be reset at the end of each sendKeys call and the appropriate key-up events generated

Character types

The keysToSend parameter contains a mix of printable characters and pressable keys that aren't text. Pressable keys that aren't text are stored in the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. The following table describes the mapping between PUA and key:

Key Code Type
NULL\uE000NULL
CANCEL\uE001Special key
HELP\uE002Special key
BACK_SPACE\uE003Special key
TAB\uE004Special key
CLEAR\uE005Special key
RETURN\uE006Special key
ENTER\uE007Special key
SHIFT\uE008Modifier
LEFT_SHIFT\uE008Modifier
CONTROL\uE009Modifier
LEFT_CONTROL\uE009Modifier
ALT\uE00AModifier
LEFT_ALT\uE00AModifier
PAUSE\uE00BSpecial key
ESCAPE\uE00CSpecial key
SPACE\uE00DSpecial key
PAGE_UP\uE00ESpecial key
PAGE_DOWN\uE00FSpecial key
END\uE010Special key
HOME\uE011Special key
LEFT\uE012Special key
ARROW_LEFT\uE012Special key
UP\uE013Special key
ARROW_UP\uE013Special key
RIGHT\uE014Special key
ARROW_RIGHT\uE014Special key
DOWN\uE015Special key
ARROW_DOWN\uE015Special key
INSERT\uE016Special key
DELETE\uE017Special key
SEMICOLON\uE018Special key
EQUALS\uE019Special key
NUMPAD0\uE01ASpecial key
NUMPAD1\uE01BSpecial key
NUMPAD2\uE01CSpecial key
NUMPAD3\uE01DSpecial key
NUMPAD4\uE01ESpecial key
NUMPAD5\uE01FSpecial key
NUMPAD6\uE020Special key
NUMPAD7\uE021Special key
NUMPAD8\uE022Special key
NUMPAD9\uE023Special key
MULTIPLY\uE024Special key
ADD\uE025Special key
SEPARATOR\uE026Special key
SUBTRACT\uE027Special key
DECIMAL\uE028Special key
DIVIDE\uE029Special key
F1\uE031Special key
F2\uE032Special key
F3\uE033Special key
F4\uE034Special key
F5\uE035Special key
F6\uE036Special key
F7\uE037Special key
F8\uE038Special key
F9\uE039Special key
F10\uE03ASpecial key
F11\uE03BSpecial key
F12\uE03CSpecial key
META\uE03DSpecial key
COMMAND\uE03DSpecial key
ZENKAKU_HANKAKU\uE040Special key

The keys considered upper-case symbols are either defined by the current keyboard locale or are derived from the US 104 keys Windows keyboard layout, which are:

  • A - Z
  • !$^*()+{}:?|~@#%_\" & < >

When the user input is emulated natively (see note below), the implementation SHOULD use the current keyboard locale to determine which symbols are upper case. In all other cases, the implementation MUST use the US 104 key Windows keyboard layout to determine those symbols.

The state of the physical keyboard MUST NOT affect emulated user input.

Internationalized input

Non-latin symbols: TBD

Complex scripts using Input Method Editor (IME): TBD

16. Screenshots

Screenshots are a powerful mechanism for providing information to users of WebDriver, particularly once a particular WebDriver instance has been disposed of. In different circumstances, users want different types of screenshot. Note that the WebDriver spec does not provide a mechanism for taking a screenshot of the entire screen.

In all cases, screenshots MUST be returned as lossless PNG images encoded using Base64. Local ends MUST provide the user with access to the PNG images without requiring the user to decode the Base64. This access MUST be via at least one of a binary blob or a file.

All commands within this section are implemented using the "TakesScreenshot" interface:

interface TakesScreenshot {
    string takeScreenshot ();
};

16.1 Methods

takeScreenshot
Take a screenshot as determined by the CommandName and return a lossless PNG encoded using Base64.
No parameters.
Return type: string

16.2 Current Window

Capability NameType
takesScreenshotboolean
Command Name screenshot
Parameters None
Return Value {DOMString} A Base64 encoded, lossless PNG of the current window.
Errors WebDriverException if the screenshot cannot be taken.

If this capability is supported, local end MUST add the TakesScreenshot interface to the WebDriver interface.

This command will take a screenshot of the current window. Implementations of the remote end SHOULD capture the entire DOM, even if this would require a user to scroll the browser window. That is, the returned PNG SHOULD have the same width and height as returned by a call to getSize of the BODY element and MUST contain all visible content on the page, and this SHOULD be done without resizing the browser window. If the remote end is unable to capture the entire DOM, then the part of the DOM currently displayed in UI of the browser MUST be captured without additional chrome such as scrollbars and browser chrome.

Note

One way to think of capturing the entire DOM is that the user has an infinitely large monitor and has resized the window to allow all content to be visible. One of those monitors would be very cool.

Nested frames MUST be sized as if the user has resized the window to the dimensions of the PNG being returned. This often means that not all potentially visible content within the nested frames is captured.

Remote ends MUST NOT attempt to track changes in window size as the screenshot is being taken. In particular this means that in the case of a page that makes use of "infinite scrolling" (where an AJAX call is used to populate additional content as the user scrolls down) or in some other way resizes content as the window size is changed only the content that was originally contained in the DOM when the command is executed will be captured.

16.3 Element

Capability NameType
takesElementScreenshotboolean
Command Name takesElementScreenshot
Parameters "id" {DOMString} The ID of the WebElement on which to operate.
Return Value {DOMString} A Base64 encoded, lossless PNG of the area contained within the WebElement's clientBoundingRect.
Errors WebDriverException if the screenshot cannot be taken.

If this capability is supported, local end MUST add the TakesScreenshot interface to the WebElement interface.

Remote ends SHOULD take a screenshot of the area bounded by the clientBoundingRect of the DOM element represented by the WebElement, returning it as a Base64 encoded, lossless PNG. Local ends MUST make the PNG available directly to the user as at least one of a binary blob or a file. If the remote end cannot capture the entire clientBoundingRect, they MUST scroll as much of the element into the current browser viewport as possible and capture the maximum visible area without additional browser chrome.

If the WebElement represents a FRAME or IFRAME element, this is equivalent of taking a screenshot of the frame's BODY element.

17. Handling non-HTML Content

There is no requirement that WebDriver implementations handle non-HTML content. The remainder of this section is non-normative.

17.1 SVG

TODO: describe how the SVG DOM maps to WebElement implementations.

17.2 Working with Accessibility APIs

Many accessibility APIs represent the UI as a series of nested nodes. It is possible to map these nodes to WebElement instances. In order to function properly, it is likely that additional element locating strategies will be required.

Note

This is one way in which it might be possible to test mobile applications that marry a native wrapper around a series of HTML views.

18. Extending the Protocol

18.1 Vendor-specific Extensions

The WebDriver protocol is designed to allow extension to meet vendor-specific needs, such as interacting with the chrome of a browser. Vendor-specific extensions are implemented by appending a prefix to the command name. This should be of the form:

        '-' + vendor prefix + '-' + command name
      

For example: "-o-open-bookmark" or "-moz-install-extension".

It is guaranteed that no command name in this or future versions of the WebDriver specification will be prefixed with a leading dash.

Note
It is suggested that vendors use the same vendor identifier as in [CSS21] (notably, section 4.1.2.2)

18.2 Extending the JSON/HTTP Protocol

This section is non-normative.

The wire protocol (see Appendix XXX) makes use of URLs to distinguish command names. When extending the protocol by adding new URLs, vendors should use their vendor prefix without additional characters to prevent any potential clashes with other implementations. This leads to URLs of the form: http://host:port/session/somekey/moz/extension.

A. Command Summary

This is an exhaustive list of the commands listed in this specification.

B. Capabilities

This section is non-normative.

Capabilities are used by WebDriver implementations to enumerate the parts of this specification that they support. They are also used when establishing a new session to descrive the required or desired capabilities. This appendix collects the capabilities mentioned in this spec into one place.

C. Command Format

This is essentially the content at the start of the json wire protocol

D. Thread Safety

There is no requirement for local or remote implementations to be thread safe. Local ends SHOULD support serialized access from multiple threads.

E. Logging

F. Mapping to HTTP and JSON

G. Acknowledgements

Many thanks to Robin Berjon for making our lives so much easier with his cool tool. Thanks to Jason Leyba, Malcolm Rowe and Ross Patterson for proof reading and suggesting areas for improvement. Thanks to Jason Leyba, Eran Messeri and Daniel Wagner-Hall for contributing sections to this document.

These links are only here until we have fixed ReSpec.js to avoid creating anchors to things that don't exist.

H. References

H.1 Normative references

[CSS21]
Bert Bos et al. Cascading Style Sheets, level 2 (CSS2) Specification. 07 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/CSS21/
[CSSOM-VIEW]
Anne van Kesteren. CSSOM View Module. 4 August 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-cssom-view-20110804
[DOM-LEVEL-2-CORE]
Arnaud Le Hors et al. Document Object Model (DOM) Level 2 Core Specification. 13 November 2000. W3C Recommendation. URL: http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/
[DOM4]
Anne van Kesteren; Aryeh Gregor; Lachlan Hunt; Ms2ger. DOM4. 6 December 2012. W3C Working Draft. URL: http://www.w3.org/TR/2012/WD-dom-20121206
[HTML401]
David Raggett; Ian Jacobs; Arnaud Le Hors. HTML 4.01 Specification. 24 December 1999. W3C Recommendation. URL: http://www.w3.org/TR/1999/REC-html401-19991224
[HTML5]
Robin Berjon et al. HTML5. 17 December 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[SELECTORS-API]
Lachlan Hunt; Anne van Kesteren. Selectors API Level 1. 13 December 2012. W3C Proposed Recommendation. URL: http://www.w3.org/TR/2012/PR-selectors-api-20121213
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/
[WEBSTORAGE]
Ian Hickson. Web Storage. 08 December 2011. W3C Candidate Recommendation. URL: http://www.w3.org/TR/2011/CR-webstorage-20111208
[XPATH]
James Clark; Steven DeRose. XML Path Language (XPath) Version 1.0. 16 November 1999. W3C Recommendation. URL: http://www.w3.org/TR/1999/REC-xpath-19991116/

H.2 Informative references

[DOM-LEVEL-3-XPATH]
Ray Whitmer. Document Object Model (DOM) Level 3 XPath Specification. 26 February 2004. W3C Note. URL: http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226

Warning:
This is an older snapshot of the WebDriver spec. Implementors and reviewers should instead read the latest editor's draft, which is up to date with the latest changes and bug fixes.