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 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].

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.

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.

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.

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.

3.1 Capabilities

interface Capabilities {
    readonly attribute dictionary capabilities;
    boolean                           has (DOMString capabilityName);
    (DOMString or boolean or number)? get (DOMString 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 (DOMString capabilityName, (DOMString or boolean or number)? value);
};

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.

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

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.

5.1 Page Load Strategies

It is possible to request a particular strategy be used for detecting when the next command should be processed by a remote end implementation by modifying the page load strategy that is used. The following are the expected values that MAY be used when creating a new session:

conservative

The remote end MUST wait until all frames and iframes in the window currently being used to process commands that contain an HTML document are at document.readyState equals '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. Put in non-normative terms, this implies that the "onload" event has fired on every frame.

normal

The remote end MUST wait until the "document.readyState" of the frame currently handling commands equals "complete", or there are no more outstanding network requests other than XMLHttpRequests.

eager

The remote end MUST wait until the "document.readyState" of frame currently handling equals "interactive" or "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 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 responding to the command.
• When a page contains a META tag with the "http-equiv" attribute set to "refresh", a response MUST be returned if the timeout is greater than 1 second and the other criteria for determining whether a page is loaded are met. When the refresh period is 1 second or less and the page loading strategy is "normal" or "conservative" implementations MUST wait for the refresh to complete before responding.
• If any modal dialog box, such as those opened by on window.onbeforeunload or window.alert, is opened at any point in the page load, a response MUST be sent.
• If a 401 response is seen by the browser, a response MUST be sent. That is, if BASIC, DIGEST, NTLM or similar authentication is required, the page load is assumed to be complete. 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 choose to make accessing a site with bad HTTPS configurations cause a WebDriverException to be thrown. Remote end implementations MUST return an unknown error status in this case. 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

Commands MUST only be processed when the page loading strategy being used indicates that page loading is complete.

If a remote end receives a new Command for a session while still waiting to finish an existing Command for that session it MAY choose to queue the command for execution as soon as possible, it MAY throw a WebDriverException or it MAY leave the remote end in an inconsistent state. Because of this, local ends SHOULD NOT attempt to send a new Command to a session until the previous Command has returned.

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:

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. 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.

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

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.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

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

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

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

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.

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

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

		  elements = driver.find_elements(by = By.TAG_NAME, value = "a")
		  result = []
		  for element in elements:
		    text = element.get_text()
		    if text == search_term:
		      result.append(element)
		

		  elements = driver.find_elements(by = By.TAG_NAME, value = "a")
		  result = []
		  for element in elements:
		    text = element.get_text()
		    if text.find(seach_term) != -1:
		      result.append(element)
		

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".

• The element MUST have 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 CSS display property that is none.
• The element MUST NOT be visible if there is a CSS3 Transform property that moves the element out of the viewport and can not be scrolled to.
• OPTIONs and OPTGROUP elements 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 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

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].

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:

• 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+,\s*\d+,\s*\d+\s*(,\s*(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. A non-normative set of these properties is given below:

  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 MUST be used as the argument to a recursive call to getElementAttribute:

  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 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.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.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 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

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

Retrieving all cookies from 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:

12.1 Cookie

When returning Cookie objects, the server SHOULD include all optional fields it is incapable of providing the information for.

interface Cookie {
             attribute DOMString name;
             attribute DOMString value;
             attribute DOMString path;
             attribute DOMString domain;
             attribute number    expiry;
             attribute boolean   httpOnly;
};

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 - Set the amount of time the driver should wait before returning when the page load stratgey is not "none". If this limit is exceeded, the get() command MUST return a "timeout" response status.
• script - Set the amount of time the driver should wait when scripts are loading on to the page.

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:

• The element MUST be visible, as defined in section 10.1.
• The element MUST NOT be disabled. "Disabled" is defined as:
  • If the current document is being processed as an HTML 4 document, the element MUST be considered disabled if it does not support the disabled attribute (according to the [HTML401] spec), or if the disabled attribute is set in the case where that attribute is present.
  • If the currently loaded document is an HTML 5 document, the element is disabled as defined in the [HTML5] spec.

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.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.

partial interface WebElement {
    void click ();
};

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

15.1 window.alert, prompt and confirm

15.2 Modal Windows

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

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.

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

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.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.

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.

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.