WebDriver

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 machine remote from the user of the local end.

There is no requirement that the local and remote ends be in different processes.

2.1 Command

A command represents a call to the remote end of the WebDriver API.

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

2.2 Response

A response represents the value returned from the remote end of the WebDriver API.

interface Response {
    readonly attribute string  sessionId;
    readonly attribute integer status;
    readonly attribute object  value;
};

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 intermeditate processing nodes. There is no requirement to maintain the ordering of fields.

2.4 Error Codes

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

3.1 Capabilities

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

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

3.2 MutableCapabilities

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

4.1 Creating a Session

The process for successfully creating a session follows.

1. The local end creates a new Capabilities or MutableCapabilities instance describing the desired capabilities for the session. The Capabilities object may be empty, but must be defined.
2. The local end creates 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 serialized and transmitted to the remote end.
4. The remote end examines the two Capabilities parameters, and creates a new session matching as many of the Capabilities as possible from the "desiredCapabilities" and all of the Capabilities given in the "requiredCapabilities". How the new session is created depends on the implementation of this specification. In the case of a browser automation framework, it is expected that a new instance of the browser is started if possible.
   • If any of the "requiredCapabilities" cannot be fulfilled by the new session, the remote end must quit the session and return the SessionNotCreatedException error code. The error message should list all unmet required capabilities though only the first unmet required capability must be given.
5. The session must be assigned a UUID which must be unique for each session (by definition). Generating the UUID 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 UUID. Because of this, it is recommended that UUID generation be done on the remote end. If the UUID has already been used, a Response must be sent with the status code set to SessionNotCreatedException and the value being an explanation that the UUID has previously been used.
6. The remote end create a new Response object.
   • The "sessionId" field is assigned the UUID associated with this session.
   • The session is described by filling a Capabilities instance with keys matching the parts of this specification that can be fulfilled. This is assigned to the "value" field of the Response. This fields must be filled
   • The "status" field is set to the SUCCESS error code.
7. The Response is transmitted or returned back 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.

5.1 Page Load Strategies

conservative

The remote end must wait until all frames and iframes in the window currently be used to process commands that contain an HTML document are at "document.readyState == 'complete'" and there are no outstanding HTTP requests, other than those caused by XMLHttpRequests. If a frame or iframe does not contain an HTML document, the remote end should wait until all HTTP traffic to that frame is complete.

normal

The remote ends must wait until the frame currently handling commands reaches "document.readyState == 'complete'" or there are no more outstanding network requests other than XMLHttpRequests.

eager

The remote end must wait until the frame currently handling commands reaches "document.readyState == 'interactive' || document.readyState == 'complete'" or there are no more outstanding network requests.

none

The remote end does not do any checks to see if a page load is currently active.

All WebDriver implementations must support the normal and eager modes and should support the conservative and none modes. If no page loading strategy is chosen, then normal must be the default. In addition, implementors may add additional page loading strategies.

5.2 Navigation Commands

The "get" command is used to cause the browser under test to navigate to a new location, and is named after the HTTP verb. From a user's point of view, this is as if they have entered the "url" into the URL bar. When the command returns is based on the page load strategy that the user has selected with the following exceptions when the strategy is not "none":

• HTTP redirects must be automatically followed without first returning control to the user.
• Control must return to the user on pages with an HTML META tags that would cause a refresh only if the timeout is greater than 1 second.
• Control must be returned to the user if any modal dialog box, such as those opened by on window.onbeforeunload or window.alert, is opened at any point.
• Control must be returned to the user if user credentials are requested by the browser. That is, if BASIC, DIGEST, NTLM or similar authentication is required. This does not include FORM-based authentication.

The exception to requirement is if the Capabilities used to initialize has the WebDriver session had the capability secureSsl set to true. In this case, implementations may chose to make accessing a site with bad HTTPS configurations cause a WebDriverException to be thrown. If this is the case, the Capabilities describing the session must also set the secureSsl capability to "true".

5.3 Detecting When to Handle Commands

WebDriver instances must only process commands when the page loading strategy being used indicates that control would be returned to the user.

6.1 Defining "window" and "frame"

Within this specification, a window equates to anything that would be referred to as "window.top" in javascript. 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 is unique to the window. The suggested implementation is as a UUID. The "getWindowHandle" command can be used to obtain the window handle for the window that commands are currently acting upon:

6.3 Iterating Over Windows

This array of returned strings must contain a handle for every window associated with the browser session and no others. In addition, at the time of collecting the window handles the javascript expression "window.top.closed" must evaluate to false.

The ordering of the keys is not defined, but should 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.

6.4 Closing Windows

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 returns an empty list, then this close command must be the equivalent of calling "quit". In all other cases, control must be returned to the calling process once the window has been closed or an alert is displayed by the closing window.

Once the window has closed, future commands must return an error NoSuchWindowException until a new window is selected for receiving commands.

6.5 Resizing and Positioning Windows

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 "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 whole browser window must be left as if the restore button had been pressed, and must not be in the maximised state.

After maximizeWindow, the whole browser window must be left as if the maximise button had been pressed; it is not sufficient to leave the window "restored", but with the full screen dimensions.

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), an UnsupportedOperationException must be thrown.

6.6 Scaling the Content of Windows

TODO

7.1 Default Content

WebDriver's default context is the equivalent of window.top.

7.2 Switching Windows

The "switchToWindow" command is used to select which window should currently be accepting commands. In order to determine which window should be used for accepting commands, the "switchToWindow" command will iterate over all windows. For each window, the following will 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 "NoSuchWindowException" must be thrown, otherwise the "default content" of the first window to match will be selected for accepting commands.

When a new browser session is started by WebDriver and only a single window is present then the default content of that window becomes the "current" window. When more than one window is opened, the "current" window is undefined. Any commands that are executed at this point that require a window must throw an exception (TODO: Which exception? Ideally the same as if a window had just been closed). The correct way for a user to recover from this situation is to obtain the list of window handles and to "switch to" one of these.

7.3 Switching Frames

The "switchToFrame" command is used to select which frame within a window should be used 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 "window"):
      1. If "window" has a "name" property or attribute equal to the "id" parameter, this becomes the current context.
      2. If "window" 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 "NoSuchFrameException" must be thrown.

Frame switching must succeed even if doing so would cross a security origin, or javascript executing in window.top's context would otherwise not be able to access the frame being switched to.

9.1 Attributes

id of type DOMString, readonly

The WebDriver ID of this particular element. This should be a UUID.

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;
};

interface SeachContext {
    WebElement[] findElements (Locator locator);
    WebElement   findElement (Locator locator);
};

9.3 Element Location Strategies

10.1 Determining Visibility

The following algorithm is used to determine if an element has been displayed.

• The element has a height and width greater than 0px.
• The element must not be visible if that element, or any of its ancestors, is hidden or has a display property that is none.
• OPTIONs and OPTGROUP are treated as special cases, they are considered shown if and only if the enclosing select element is visible.
• MAP elements are shown if and only if the image it uses is visible. Areas within a map are shown if the enclosing MAP is visible.
• Any INPUT elements of "type=hidden" are not visible
• Any NOSCRIPT elements must not be visible if Javascript is enabled.
• The element must be not be visible if any ancestor in the element's transitive closure of offsetParents has a fixed size, and has the CSS style of "overflow:hidden", and the element's location is not within the fixed size of the parent

10.2 Determining Whether a WebElement Is Selected

WebDriver determines 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 WebElement represents an INPUT element, call the "getProperty" method described above looking for the "checked" property. This indicates whether the element is selected.
3. Otherwise, call the "getProperty" method described above looking for the "selected" property. This indicates whether the element is selected.

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 both 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:

• If, in the current rendering mode, the content attribute name reflects a boolean IDL attribute, as per the HTML specification, the value must be the string 'true' if that IDL attribute's value is true or the null value if the IDL attribute's value is false.
• If the element is an OPTION element and name is "value" and there is no "value" attribute, then the text content of the OPTION element must be returned, in accordance with [HTML401] spec, specifically the section on pre-selected options. The text content must be the result of calling the "getElementText" command on the OPTION element.
• If the element is selectable, and name is "selected", or the element is an INPUT element of type "checkbox" or "radio" and name is "checked", return the string 'true' if the element is selected, and the null value otherwise.
• If name is "style", the value returned must be serialized as defined in the [CSSOM-VIEW] spec. Notably, css property names must be cased the same as specified in in section 6.5.1 of the [CSSOM-VIEW] spec.
  • Consequently, it should be equivalent to obtaining the "cssText" property, with the additional constraint that the same value must be returned after a round trip through "executeScript". That is, the following pseudo-code must be true (where "driver" is a WebDriver instance, and "element" is a WebElement):

    var style = element.getAttribute('style');
    driver.executeScript('arguments[0].style = arguments[1]', element, style);
    var recovered = element.getAttribute('style');
    assertEquals(style, recovered);
    

  • Color property values must be standardized to rgba format, matching the regular expression: rgba\(\d+, \d+, \d+, (1|0(\.\d+)?)\).
• If the value is expected to be a URL (see the below table), return the property named name, i.e. a fully resolved URL: TODO: This doesn't feel like an exhaustive list

  Tag name	"name" value
  A	href
  IMG	src

• If name is in the below table, and the above stages have not yielded a defined, non-null value, the value of the aliased attribute in the table below should be returned:

  Original property name	Aliased property name
  class	className
  readonly	readOnly

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 such as Lynx would display. 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 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. For each line in lines trim any leading and trailing whitespace excluding non-breaking space characters.
3. Let s be lines.join('\n')
4. Trim any leading and trailing whitespace excluding non-breaking space characters from s.
5. Replace any non-breaking spaces (\xa0) with spaces (\x20) in s.
6. Return s.

11.1 Javascript Command Parameters

The Argument type is defined as being {(number|boolean|DOMString|WebElement|dictionary|Array.>Argument>)?}

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

11.2 Synchronous Javascript Execution

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 command's response status to JavascriptError.
   3. Set the command's 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 command's response value to value.
8. Return the command response.

11.3 Asynchronous Javascript Execution

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 command's response status to JavascriptError.
   3. Set the command's 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 command response status to Timeout and return.
    2. if the window fires an unload event, the WebDriver implementation must immediately set the command 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 command response.

11.4 Reporting Errors

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

• implicit - Set the amount of time the driver should wait when searching for elements. When searching for a single element, the driver should poll the page until an element is found or the timeout expires, whichever occurs first. When searching for multiple elements, the driver should poll the page until at least one element is found or the timeout expires, at which point it should return an empty list.
  If this command is never sent, the driver must default to an implicit wait of 0ms.
• page load -TODO(David, Simon) fill me in
• script - Set the amount of time the driver should wait when scripts are loading on to the page.

14.1 Interaction directly with elements

partial interface WebElement {
    void click ();
};

partial interface WebElement {
    void clear ();
    void sendKeys (string[] keysToSend);
};

14.2 High Level APIs: Clicking and Typing

This section deals with implicit interaction. In this kind of interaction, a user describes a series of input actions which the implementation should fulfill with little to no additional actions. This kind of interactions allow dragging and dropping or combining keyboard and mouse actions.

interface Actions {
    void keyDown (Keys theKey);
    void keyUp (Keys theKey);
    void sendKeys (string[] keysToSend);
    void moveToElement (WebElement toElement);
    void moveByOffset (int xOffset, int yOffset);
    void clickAndHold ();
    void release ();
    void click ();
    void doubleClick ();
    void contextClick ();
};

The following conditions must hold for implementation of this high-level API:

• Modifier keys are never implicitly released, once pressed.
• To release all currently-held modifier keys, Keys.NULL must be used.
• The results of using this API to generate sequences of actions that are not logically possible (such as releasing a modifier key twice) are undefined.
• The current mouse position must be persistent during the life of the browser. The interaction commands are not batched together, so one command should be able to rely on the mouse position set by another command.

Mouse movement and scrolling: Despite the implicit nature of this API, some mouse movement actions still cause implicit scrolling. The alternative, of providing an API to scroll the viewport and forcing the user to do so, would be inconvenient. When moving to an element, the implementation should use the same method of scrolling as is used for WebElement.click(). When moving by an offset, the implementation has a greater freedom to decide how much to scroll. In both cases, the implementation must not scroll if the target coordinates are already in the viewport.

14.3 Low Level APIs

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

15.1 window.alert, prompt and confirm

15.2 Modal Windows

16.1 Screen

16.2 Current Window

16.3 Element