1.1 Dependencies

This specification relies on several other underlying specifications.

HTTP and related specifications

The following terms are defined in the Cookie specification: [RFC6265]

• cookie
• cookie name as a cookie’s name field
• cookie value as a cookie’s value field
• cookie expiry time a cookie’s expiry-time field
• cookie domain as a cookie’s domain field
• cookie path as a a cookie’s path field
• cookie secure only as a cookie’s secure-only-flag field
• cookie http only as a cookie’s http-only-flag

4.1 Algorithms

Various parts of this specification are written in terms of step-by-step algorithms. The details of these algorithms do not have any normative significance; implementations are free to adopt any implementation strategy that produces equivalent output to the specification. In particular algorithms in this document are optimised for readability rather than performance.

Where algorithms that return values are fallible, they are written in terms of returning either success or error. A success value has an associated data field which encapsulates the value returned, whereas an error response has an associated error code.

The result of getting a property with name name from an [ECMA-262] Object object is defined as the result of calling the [[GetOwnProperty]] internal method of object with property name name.

4.2 Commands

The WebDriver protocol is organised into commands. Each HTTP request with a method and template defined in this specification represents a single command and therefore each command produces a single HTTP response. In response to a command, a remote end will run a series of actions against the remote browser.

Each command defined in this specification has an associated list of remote end steps. This provides the sequence of actions that a remote end takes when it recieves a particular command.

4.3 Processing Model

The remote end acts as a HTTP server reading requests from the client and writing responses, typically over TCP socket. For the purposes of this specification we model the data transmission between a particular local end and remote end with a connection to which the remote end may write bytes and read bytes. However the exact details of how this connection works and how it is established are out of scope.

After such a connection has been established, a remote end MUST run the following steps:

1. Read bytes from the connection until a complete HTTP request can be constructed from the data. Let request be a request object constructed from the received data, according to the requirements of [RFC7230].

2. Let request match be the result of the algorithm to match a request with request’s method and url as arguments.

3. If request match is of type error, send an error with request match’s error code and jump to step 1.

   Otherwise, let command, session id, and element id be request match’s data.

4. If command is not New Session:

   1. If session id is not equal to the id of any session in the list of active sessions, send an error with error code invalid session id, then jump to step 1 in this overall algorithm.

      Otherwise, let the current session be the session with id session id.

5. If request's method is POST:

   1. Let parse result be the result of parsing as JSON with request’s body as the argument.

   2. If parse result is an error or if it is a success but its associated data is not an Object object, send an error with error code invalid argument and jump back to step 1 in this overall algorithm.

      Otherwise, let parameters be parse result’s data.

   Otherwise, let parameters be null.

6. Let response result be the return value obtained by running the remote end steps for command with arguments element id and parameters.

7. If response result is an error, send an error with error code equal to response result’s error code.

   Otherwise, if response result is a success, let response data be response result’s data.

8. Send a response with status 200 and response data.

9. Jump to step 1.

When required to send an error, with error code, a remote end must run the following steps:

1. Let http status and name be the error response data for error code.

2. Let message be an implementation-defined string containing a human-readable description of the reason for the error.

3. Let stacktrace be an implementation-defined string containing a stack trace report of the active stack frames at the time when the error occurred.

4. Issue 5

   Really need a better way to construct JSON literals.

   Let data be a new JSON Object initialised with the following properties:

   "error"

   Value of name.

   "message"

   Value of message.

   "stacktrace"

   Value of stacktrace.

5. Send a response with status and data as arguments.

When required to send a response, with arguments status and data, a remote end must run the following steps:

1. Let response be a new response.

2. Set response’s status to status, and status message to the string corresponding to the description of status in the status code registry.

3. If data is not null, let response’s body be the result of serializing as JSON with data as the argument.

4. Let response bytes be the byte sequence resulting from serializing response according to the rules in [RFC7230].

5. Write response bytes to the connection.

4.4 Routing Requests

Request routing is the process of going from a HTTP request to the series of steps needed to implement the command represented by that request.

A remote end has an associated URL prefix, which is used as a prefix on all WebDriver-defined URLs on that remote end. This must either be the empty string, or an absolute path relative url.

In order to match a request given a method and url, the following steps must be taken:

1. Let endpoints be a list containing each row in the table of endpoints.

2. Remove each entry in endpoints for which the concatenation of the url prefix and the production in the "url" column does not match url according to the rules in [URI-Template].

3. If there are no entries in endpoints, return error with error code unknown command.

4. Remove each entry in endpoints for which the "method" column is not an exact case-sensitive match for method.

5. If there are no entries in endpoints, return error with error code unknown method.

6. There is now exactly one entry in endpoints; let entry be this entry.

7. Issue 6

   Check that URI-templates is being used in the right way here:

   If the match in step 2 populated a template variable called "sessionId", let session id be the value it was populated with. Otherwise let session id be null.

8. If the match in step 2 populated a template variable called "elementId", let element id be the value it was populated with. Otherwise let element id be null.

9. If the match in step 2 populated a template variable called "name", let name be the value it was populated with. Otherwise let name be null.

10. Let command be the command represented by the "command" column of entry.

11. Return success with data session id, element id, and command.

4.5 List of Endpoints

The following table of endpoints lists the method, URL, and command for each WebDriver command.

4.6 Handling Errors

Errors are represented in the WebDriver protocol with a HTTP response with a HTTP status in the 4xx or 5xx range, and a JSON body containing details of the error. This JSON body has three fields: error, containing a string indicating the error type; message, containing an implementation-defined string with a human readable description of the kind of error that occured; and stacktrace, containing an implementation-defined string with a stack trace report of the active stack frames at the time when the error occurred.

The following table lists each error code, its associated HTTP status, JSON error code, and a non-normative description of the error. The error response data for a particular error code is the values of the HTTP Status and JSON Error Code columns for the row corresponding to that error code.

4.7 Protocol Extensions

The protocol is designed to allow extension to meet vendor-specific needs. Commands that are specific to a user agent are called extension commands and behave no differently than other commands; each has a dedicated HTTP endpoint and a set of remote end steps.

Each extension command has an associated extension command name that is a lowercased ASCII string, and which should bear some resemblance to what the command performs. The name is used to form an extension command’s URL.

The extension command’s extension command URL is a URL composed of the extension prefix, followed by "/", and the extension command’s name. The extension command URL, along with the HTTP method and extension command, is added to the table of endpoints and thus follows the same rules for request routing as that of other built-in commands.

The remote end’s extension prefix is a lowercased ASCII string that forms a URL path element, separating extension commands from other commands to avoid potential resource conflicts with other implementations. It is suggested that vendors use their vendor prefixes without additional characters as outlined in [CSS21], notably in section 4.1.2.2 on vendor keywords, as the name for this path element.

6.1 New Session

The New Session command creates a new WebDriver session with the endpoint node. If the maximum active sessions has been reached, that is if the endpoint node already has a current session, there is a problem processing the given capabilities, or the provisioning of a remote end is impossible, a session not created error is returned.

If the remote end is an intermediary node, they are allowed to freely use the capabilities data e.g. to select a specific browser to test based on a combination of the required and desired capabilities. Typically the New Session response from the endpoint node selected in this process will then be relayed directly to the local end, as outlined in step 1 of the remote end steps.

The remote end steps are:

1. If the remote end is an intermediary node, take implementation-defined steps that either result in returning an error with error code session not created, or in returning a success with data that is isomorphic to that returned by remote ends according to the rest of this algorithm.

2. If the maximum active sessions is equal to the length of the list of active sessions, return error with error code session not created.

3. Let capabilities be the result of getting a property named "capabilities" from the parameters argument.

4. Let capabilities result be the result of processing capabilities with capabilities as an argument.

5. If capabilities result is an error, return error with error code session not created.

6. Let capabilities be capabilities result’s data.

7. Let session id be the result of generating a UUID.

8. Let session be a new session with the session ID of session id.

9. Set the current session to session.

10. Append session to active sessions.

11. Let body be a JSON Object initialised with:

    "sessionId"

    The value of session id.

    "capabilities"

    The value of resultant capabilities.

12. Initialise the following if not set while processing capabilities:

    1. Set the current session’s session script timeout to 30,000 milliseconds.

    2. Set the current session’s session page load timeout to 300,000 milliseconds.

    3. Set the current session’s session implicit wait timeout to 0 (zero) milliseconds.

    4. Set the current session’s page loading strategy to normal.

    5. Set the webdriver-active flag to true.

13. Return success with data body.

6.2 Delete Session

The Delete Session command closes any top-level browsing contexts associated with the current session, terminates the connection, and finally closes the current session.

The remote end steps are:

1. Close the session.

2. Return success with data null.

6.3 Set Timeout

The Set Timeout command sets timeouts associated with the current session. The timeouts that can be controlled are the session script timeout, the session page load timeout, and the session implicit wait timeout.

The following table of session timeouts lists pairs of different timeouts that may be changed with the string codes used to identify them:

The remote end steps for the Set Timeout command are:

1. For each row in the table of session timeouts, enumerated as type and identifier:

   1. If parameters does not have an own property identifier, continue to the next entry.

   2. Let timeout be the result of getting a property using identifier from parameters.

   3. If timeout is of the Number type and a non-negative integer, set the type timeout to timeout’s value in milliseconds.

      Otherwise, return error with error code invalid argument.

2. Return success.

7.1 Get

The Get command is used to cause the user agent to navigate the current top-level browsing context a new location. From a user’s point of view, it is as if they have entered a URL into the address bar of the browser’s chrome.

The remote end steps for the Get command are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let url be the result of getting a property named "url" from the parameters argument.

3. If url is undefined, return error with error code invalid argument.

4. Navigate the current top-level browsing context to url. If this navigation results in a HTTP 401 response, the remote end must proceed with the steps below, irrespective of how the authentication challenge is handled.

5. If the current session's page loading strategy is none jump to the next step in this overall set of steps. Otherwise:

   1. Let readiness target be "interactive" if the current session's page loading strategy is eager, or "complete" if it is normal.

   2. Wait for the current document readiness to reach readiness target, or for the session page load timeout milliseconds to pass, whichever occurs sooner.

   3. If the previous step completed by the load timeout being reached, and the browser is not currently displaying an alert, return error with error code timeout.

6. Return success with data null.

7.2 Get Current Url

The Get Current Url command returns the URL of the current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let url be the serialization of the current top-level browsing context’s active document’s url.

3. Let body be a JSON Object with the "value" property set to url.

4. Return success with data data.

7.3 Back

The Back command causes the browser to traverse one step backward in the joint session history of the current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Traverse the history by a delta -1 for the current browsing context.

3. If the task queued by that algorithm aborted before traversing the history, return success with data null.

4. Otherwise, wait until the current entry in the session history has changed, or for the session page load timeout milliseconds to pass, whichever occurs sooner.

   Issue 9

   This doesn't actually wait for the page to load if traversing the session history kicks off a navigation.

5. Issue 10

   Perhaps? Not sure if this is what the spec is trying to say?

   If the previous step completed by the session page load timeout being reached, and the browser is not currently displaying an alert, return error with error code timeout.

6. Return success with data null.

7.4 Forward

The Forward command causes the browser to traverse one step forwards in the joint session history of the current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Traverse the history by a delta 1 for the current browsing context.

3. If the task queued by that algorithm aborted before traversing the history, return success with data null.

4. Otherwise, wait until the current entry in the session history has changed, or for the session page load timeout milliseconds to pass, whichever occurs sooner.

   Issue 11

   This doesn't actually wait for the page to load if traversing the session history kicks off a navigation.

5. Issue 12

   Perhaps? Not sure if this is what the spec is trying to say.

   If the previous step completed by the session page load timeout being reached, and the browser is not currently displaying an alert, return error with error code timeout.

6. Return success with data null.

7.5 Refresh

The Refresh command causes the browser to reload the page in in current top-level browsing context.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Issue 13

   Not sure if this needs to consider the reload override flag.

   Navigate the current top-level browsing context to the same resource as its active document, with replacement enabled.

3. If the current session’s page load strategy is none, jump to the next step in this overall set of steps.

   Otherwise:

   1. Let readiness target be "interactive" if the current session’s page load strategy is eager, or "complete" if it is normal.

   2. Wait for the current document readiness to reach readiness target, or for the session page load timeout milliseconds to pass, whichever occurs sooner.

   3. Issue 14

      Perhaps? Not sure if this is what the spec is trying to say.

      If the previous step completed by the load timeout being reached, and the browser is not currently displaying an alert, return error with error code timeout.

4. Return success with data null.

7.6 Get Title

The Get Title command returns the document title of the current top-level browsing context, equivalent to calling window.top.document.title.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let title be the value of the current top-level browsing context's active document's title.

3. Let data be a new JSON Object.

4. Set the property "value" of data to the value of title.

5. Return success with data data.

9.1 Get Window Handle

The Get Window Handle command returns the window handle for the current top-level browsing context. It can be used as an argument to Switch To Window.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let data be a new JSON Object.

3. Set the property "value" on data to the value of the window handle associated with the current top-level browsing context.

4. Return success with data data.

9.2 Close Window

The remote end steps for the Close Window command are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Issue 16

   This can prompt unload, in which case the operation really failed.

   Close the current top-level browsing context.

3. If there are no more open top-level browsing contexts, then close the session.

4. Return the result of running the remote end steps for the Get Window Handles command.

9.3 Switch To Window

The Switch To Window command is used to select the current top-level browsing context for the current session, i.e. the one that will be used for processing commands.

The remote end steps are:

1. Let handle be the result of getting a property named "handle" from the parameters argument.

2. If handle is equal to the associated window handle for some top-level browsing context in the current session, set the session's current top-level browsing context to that browsing context, and return success with data null.

3. Otherwise, return error with error code no such window.

9.4 Get Window Handles

The Get Window Handles command returns a list of window handles for every open top-level browsing context. The order in which the window handles are returned is arbitary.

The remote end steps are:

1. Let handles be a JSON List.

2. For each top-level browsing context in the remote end, push the associated window handle onto handles.

3. Let body be a JSON object with the property "value" set to handles.

4. Return success with data body.

9.5 Switch To Frame

The Switch To Frame command is used to select the current top-level browsing context or a child browsing context of the current browsing context to use as the current browsing context for subsequent commands.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Let id be the result of getting a property named "id" from the parameters argument.

3. Run the substeps of the first matching condition:

   id is null

   1. Set the current browsing context to the current top-level browsing context.

   id is a Number object

   1. If id is less than 0 or greater than 2¹⁶ – 1, return error with error code no such frame.

   2. Let window be the associated window of the current browsing context’s active document.

   3. If id is not a supported property index of window, return error with error code no such frame.

   4. Let child window be the WindowProxy object obtained by determining the value of an indexed property of window with index id.

   5. Set the current browsing context to new window’s browsing context.

   id represents a web element

   1. Issue 17

      Note that representing a web element will have to do the same document checks, or something.

      Let element be the element represented by id.

   2. If element is not a frame or iframe element, return error with error code no such frame.

   3. Set the current browsing context to element’s nested browsing context.

   Otherwise

   1. Return error with error code no such frame.

4. Return success with data null.

9.6 Switch To Parent Frame

The Switch to Parent Frame command sets the current browsing context for future commands to the parent of the current browsing context.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. If the current browsing context is not equal to the current top-level browsing context, set the current browsing context to the parent browsing context of the current browsing context.

3. Return success with data null.

9.7 Resizing and Positioning Windows

WebDriver provides commands for interacting with the operating system window containing the current browsing context. Because different operating system's window managers provide different abilities, not all of the commands in this section can be supported by all remote ends. Where a command is not supported, an unsupported operation error is returned.

10.1 Finding Elements in a document

When the findElement() or findElements() WebDriver Command is called the following must be parameters after the local end has made a request to the remote end:

1. Let using contain the Element Location Strategy. If it is not a valid stategy:
   • Set the HTTP Response status code to 500
   • Let status be equal to Invalid Selector
   • Let value be a statement that the strategy is invalid. It MAY return a list of valid search strategies.
2. Let value contain a string that will be passed to the Element Location Strategy call. If value is an empty string or null:
   • Set the HTTP Response status code to 500
   • Let status be equal to Invalid Selector
   • Let value to a stating that the strategy is invalid. It MAY return a list of valid search strategies.
3. Call the relevant Element Location Strategy and return what is described in findElement() or findElements() WebDriver Command described below.

10.2 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.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.text
                    if text.search(seach_term) != -1:
                      result.append(element)
                

10.3 Element Displayedness

The visibility of an element is guided by what is perceptually visible to the human eye. In this context, an element's displayedness does not relate to the visibility or display style properties [CSS3BOX].

The approach used by WebDriver to ascertain an element's visibility is based on crude approximations about its nature and relationship in the tree. An element is in general to be considered visible if any part of it is drawn on the canvas within the bounderies of the viewport.

When asked to normalize style pixel values to floating point for a value s of the type string:

1. Let trimmed string be a substring of s where the suffix "px" is removed.

2. Let pixels be the result of parsing trimmed string as a float.

3. If pixels is not a valid float or the previous operation did not succeed, return 0.0.

4. Round off pixels using a ceiling function so that it has no more than four decimals.

5. Return pixels.

The element displayed algorithm is a boolean state where true signifies that the element is displayed and false signifies that the element is not displayed. To compute the state on element:

1. If the attribute hidden is set, return false.

2. If the computed value of the display style property is "none", return false.

3. Issue 24

   Not really sure what this means, needs review:

   If it has a [CSS3-2D-TRANSFORMS] or [CSS3-3D-TRANSFORMS] style property that gives a negative X or Y coordinates to the canvas, return false.

4. If element is the document's root element, that is document.documentElement:

   1. If the computed value of the background-color property is "transparent", run these substeps:

      1. If element is an HTML HTML element [html51], and the computed value of the background-color style property of the first BODY element descendant of the element in tree order, relative to that element, is also "transparent", return false. Otherwise return true.

5. If element is an option or optgroup element, and element's parent node is a select element:

   1. Apply the element displayed algorithm on element's parent node.

   2. If the return value is false, abort these steps and return that value.

6. If element is a map element:

   1. Let any images visible be a boolean initially set to false.

   2. For each img element, image element, in the document with a name attribute matching the value of element's usemap attribute, run these substeps:

      1. Run the element displayed algorithm on image element and set any images visible to any images visible bitwise OR its return value.

   3. If any images visible is true, abort these steps and return its value.

7. If element is an area element:

   1. For each ancestral element parent, in tree order:

      1. If parent is a map element, apply the element displayed algorithm on it.

      2. If the return value is false, abort these steps and return that value.

      3. Otherwise apply step 7.1 on parent.

8. If element is a [DOM4] text node, return true.

9. If it has equal to or more than one direct descendant elements:

   1. Let visible children be a boolean initially set to false.

   2. For each direct descendant element child:

      1. Let rectangle be the DOMRect returned by calling getBoundingClientRect on child.

      2. If the value of the height property of rectangle is greater than zero CSS reference pixels, and the value of the width property of rectangle is greater than zero CSS reference pixels:

         1. Set visible children to visible children bitwise OR true.

10. For each ancestral element parent, in tree order:

    1. Apply the element displayed algorithm to parent.

    2. If the return value is false, abort these steps and return that value.

    3. If parent is a block element box and the computed values of either overflow-x or overflow-y is "hidden":

       1. Let parent dimensions be the DOMRect that is the first element of the DOMRectList array returned by calling getClientRects on parent.

       2. Let element dimensions be the DOMRect that is the first element of the DOMRectList array returned by calling getClientRects on element.

       3. Let parent style be the computed style of parent.

       4. Return false if any the following conditions evaluate to false:

          • element dimension's top is less than (parent dimension's bottom − the normalized style pixel float value of parent style's borderBottomWidth).

          • element dimension's bottom is less than (parent dimension's top − the normalized style pixel float value of parent style's borderTopWidth).

          • element dimension's left is less than (parent dimension's right − the normalized style pixel float value of parent style's borderRightWidth casted as a float).

          • element dimension's right is less than (parent dimension's left − the normalized style pixel float value of parent style's borderLeftWidth casted as a float).

       5. Run step 10 on the parent elements of parent, if any.

11. Return true.

11.1 Is Element Displayed

The Is Element Displayed command is used to determine the element displayedness of a web element.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. If the current browsing context’s document type is not "xml", let visible be a boolean initially set to false

   Otherwise Let visible be equal to true and jump to the last step of this algorithm.

3. Let element result be the result of getting a known element by UUID parameter element id.

4. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

5. If element is stale, return error with error code stale element reference.

6. Apply the element displayed algorithm to element and set visible to its return value.

7. Let body be a new JSON Object with the "value" member set to element displayed.

8. Return success with data body.

11.2 Is Element Selected

Is Element Selected determines if the referenced element is selected or not. This operation only makes sense on input elements of the Checkbox- and Radio Button states, or option elements.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference element id.

3. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

4. If element is stale, return error with error code stale element reference.

5. Let selected be the value corresponding to the first matching statement:

   element is an input with a type attribute in the Checkbox- or Radio Button state

   The result of element’s checkedness.

   element is an option element

   The result of element’s selectedness.

   Otherwise

   False.

6. Let body be a JSON Object with the "value" member set to selected.

7. Return success with data body.

11.3 Get Element Attribute

The Get Element Attribute command will return the attribute of a web element.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference element id.

3. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

4. If element is stale, return error with error code stale element reference.

5. Let name be equal to "name" from match a request. if name is undefined return error with error code invalid argument.

6. Let result be the result of the first appropriate step below:

   If name is a boolean attribute:

   The first matching statement if the element has the attribute:

   true

   'true'.

   Otherwise

   Null.

   Otherwise:

   The result of getting the attribute by name.

7. Let body be a JSON Object with the "value" member set to result.

8. Return success with data body.

11.4 Get Element Property

The Get Element property command will return the result of getting a property of a element.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference element id.

3. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

4. If element is stale, return error with error code stale element reference.

5. Let property be the result of calling the [[GetProperty]] internal method of element with property name name.

6. Let result be the value of property if not undefined, or null.

7. Let body be a JSON Object with the "value" property set to result.

8. Return success with data body.

11.5 Get Element CSS Value

The Get Element CSS Value command retrieves the computed value of the given CSS property of the given web element.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID parameter element id.

3. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

4. If element is stale, return error with error code stale element reference.

5. Let computed value be the computed value of parameter property name from element’s style declarations if the current browsing context’s document type is not "xml" else let it be "carview.php?tsp=".

6. Let body be a JSON Object with the "value" member set to computed value.

7. Return success with data body.

11.6 getElementText()

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. The algorithm for determining this text is as follows:

Let lines equal an empty array. Then:

1. if the element is in the head element of the document, return an empty string otherwise carry on with the algorithm below.
2. For each descendent of node, at time of execution, in order:
   1. Get whitespace, text-transform, and then, if descendent is:
      • a node which is not displayed, do nothing
      • a [DOM4] text node let text equal the nodeValue property of descendent. Then:
        1. Remove any zero-width spaces (\u200b, \u200e, \u200f), 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 displayed. 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 descendent 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
3. The string MUST then have the white space normalised as defined in the [XPATH] normalize-space function which is then returned.

If the ELEMENT does not represent a Document element, or it represents a Document element that is no longer attached to the document's node tree, then the WebDriver implementation MUST immediately abort the command and return a stale element reference error. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.

11.7 Get Element Tag Name

The Get Element Tag Name command returns the qualified tag name name of the given web element.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference parameter element id.

3. If element result is an error, return element result.

4. Let element be element result’s data.

5. If element is stale, return error with error code stale element reference.

6. Let qualified name be the result of getting element’s tagName content attribute.

7. Let body be a JSON Object with the "value" member set to qualified name.

8. Return success with data body.

11.8 Get Element Rect

The Get Element Rect command returns the dimensions and coordinates of the given web element. The returned value is a dictionary with the following members:

x

X axis position of the top-left corner of the web element relative to the current browsing context’s document element in CSS pixels.

y

Y axis position of the top-left corner of the web element relative to the current browsing context’s document element in CSS pixels.

height

Height of the web element’s rectangle in CSS pixels.

width

Width of the web element’s rectangle in CSS pixels.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference parameter element id.

3. If element result is an error, return element result.

4. Let element be element result’s data.

5. If the element is stale, return error with error code stale element reference.

6. Calculate the absolute position of element and let it be coordinates.

7. Let rect be element’s DOMRect.

8. Let body be a new JSON Object initialised with:

   "x"

   The first value of coordinates.

   "y"

   The second value of coordinates.

   "height"

   Value of rect’s height.

   "width"

   Value of rect’s width.

9. Return success with data body.

11.9 Is Element Enabled

Is Element Enabled determines if the referenced element is enabled or not. This operation only makes sense on form controls.

The remote end steps are:

1. If the current top-level browsing context is no longer open, return error with error code no such window.

2. Let element result be the result of getting a known element by UUID reference element id.

3. If element result is a success, let element be element result’s data.

   Otherwise, return element result.

4. If element is stale, return error with error code stale element reference.

5. Let enabled be a boolean initially set to true If the current browsing context’s document type is not "xml".

   Otherwise, let enabled to false and jump to the last step of this algorithm.

6. Set enabled to false if a form control is disabled.

7. Let body be a JSON object with the "value" member set to enabled.

8. Return success with data body.

12.1 Execute Script

The Execute Script command executes a JavaScript function in the context of the current browsing context and returns the return value of the function.

The remote end steps are:

1. Let script arguments be the result of extracting the script arguments from a request with argument parameters.

2. If script arguments is an error, return script arguments.

3. Let body and arguments be script arguments’ data.

4. Let result be the result of calling execute a function body, with arguments body and arguments.

5. If result is an error, return result.

   Otherwise let value be result’s data.

6. Let data be a new Object.

7. Set the property value of data to value.

8. Return success with data data.

12.2 Execute Async Script

The Execute Async Script command causes JavaScript to execute as an anonymous function. Unlike the Execute Script command, the result of the function is ignored. Instead an additional argument is provided as the final argument to the function. This is a function that, when called, returns its first argument as the response.

The remote end steps are:

1. Let script arguments be the result of extracting the script arguments from a request with argument parameters.

2. If script arguments is an error, return script arguments.

3. Let body and arguments be script arguments’ data.

4. Issue 27

   This next step might not quite set up all the right machinery.

   Let webdriver callback result be a flag which can have three values: unset, expired, or set, with the set value having associated data. Initially it is in the unset state.

5. Let callback be a function whose [[Call]] internal method runs the execute async script callback algorithm initialized with argument webdriver callback result.

6. Append callback to arguments.

7. Let result be the result of calling execute a function body with arguments body and arguments.

8. If result is an error, return result.

9. Wait for webdriver callback result to enter the set state, or for session script timeout milliseconds to expire, whichever happens sooner.

10. If the previous step completed due the session script timeout being reached, set webdriver callback result to expired and return error with error code script timeout.

11. Otherwise, let result be webdriver callback result’s data.

12. If result is an error, return result.

13. Let value be result’s data.

14. Let data be a new Object.

15. Set the property value of data to value.

16. Return success with data data.

The execute async script callback algorithm is initialized with a single argument webdriver callback state. It defines a function with a single optional argument result. When this function is called, the following steps are run:

1. If webdriver callback state is not in the unset state, return undefined.

2. If result is not present, let result be null.

3. Let json result be a JSON clone of result.

4. Set the webdriver callback state to set with data json result.

5. Return undefined.

13.1 Get Cookie

The Get Cookie command returns all cookies associated with the address of the current browsing context’s active document.

Provided with an optional name parameter, the returned set will consist of only a single cookie matching an entry’s cookie-name in the cookie store, or be empty.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Let result be an initially empty JSON List.

3. For each cookie among all associated cookies of the current top-level browsing context’s active document, matching on name:

   cookie’s cookie-name

   Append a serialized cookie of cookie to result, and break out of the loop.

   undefined

   Append a serialized cookie of cookie to result.

4. Return success with data result.

13.2 Add Cookie

The Add Cookie command adds a single cookie to the cookie storage associated with the active document’s address.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. Let cookie be the result of getting a property named "cookie" from the parameters argument.

3. If cookie is not a JSON Object, return error with error code unable to set cookie.

4. If the current top-level browsing context’s document element is a cookie-averse Document object, return error with error code invalid cookie domain.

5. Set the value is cookie-name, as defined in [RFC6265], to the value of entry with key name. If nameis undefined, return error with error code unable to set cookie.

6. Set the value is cookie-value, as defined in [RFC6265], to the value of entry with key value. If valueis undefined, return error with error code unable to set cookie.

7. If cookie has an entry with key path set attribute-value of the last attribute in the cookie-attribute-list with an attribute-name of "Path".

8. If cookie has an entry with key domain set attribute-value of the last attribute in the cookie-attribute-list with an attribute-name of "Domain".

9. If cookie has an entry with key secure set attribute-value of the last attribute in the cookie-attribute-list with an attribute-name of "Secure".

10. If cookie has an entry with key expiry set attribute-value of the last attribute in the cookie-attribute-list with an attribute-name of "Expires".

11. Store the contents cookie in the user agent cookie manager following the steps described in Storage Model in [RFC6265]. If there is an error during this step, return error with error code unable to set cookie.

12. Return success with data null.

13.3 Delete Cookie

The Delete Cookie command allows you to delete either a single cookie by parameter name, or all the cookies associated with the active document’s address if name is undefined.

The remote end steps are:

1. If the current browsing context is no longer open, return error with error code no such window.

2. For each cookie among all associated cookies of the current top-level browsing context’s active document, if:

   name is undefined

   name is equal to cookie’s cookie-name

   Add an attribute to the attribute-list of cookie with attribute-name of Expires, and set its value to a time in the past.

3. Return success with data null.

14.1 Interactable elements

User actions that operate on an element require the element to be interactable. The following conditions must be met for the element to be considered interactable:

• The element MUST be displayed, 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 document, the element MUST be considered disabled if it does not support the disabled attribute (according to the [html51] spec), or if the disabled attribute is set in the case where that attribute is present.

14.2 Low-Level Actions

            [
              {
                "source": "string",
                "id": "string",
                "actions": [
                          { "name": "string: name of action primitive",
                            ... parameters to action commands...
                          },
                ]
              }
            ]
          

[
  {
    "source": "touch",
    "id": "1",
    "actions": [
              { "name": "pointerDown",
                "ELEMENT": "element1"
              },
              { "name": "pause",
                "duration": 0
              },
              { "name": "pointerUp"
              }
    ]
  },
  {
    "source": "touch",
    "id": "2",
    "actions": [
              { "name": "pointerDown",
                "ELEMENT": "element2"
              },
              { "name": "pointerMove",
                "ELEMENT": "element3"
              },
              { "name": "pointerUp"
              }
    ]
  }
]

[
  {
    "source": "touch",
    "id": "1",
    "actions": [
              { "name": "pointerDown",
                "ELEMENT": "element1"
              },
              { "name": "pointerUp"
              }
    ]
  },
  {
    "source": "touch",
    "id": "2",
    "actions": [
              { "name": "pointerDown",
                "ELEMENT": "element2"
              },
              { "name": "pointerMove",
                "ELEMENT": "element3"
              },
              { "name": "pointerUp"
              }
    ]
  }
]

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.

15.1 window.alert, window.prompt and window.confirm

When the remote end has a modal dialog such as those produced from window.alert, window.prompt and window.confirm it SHOULD allow the interrogation of the dialogues using the following interface.

15.2 Modal dialogs

If a browser supports Modal dialogs, as created by document.showModalDialog(), it MUST support handling of Modal dialogs via the WebDriver API. Modal dialogs can then be iterated over in the same approach as normal windows.

If close() is called on a parent window and it has modal dialogs open then the remote end SHOULD iterate over modal dialogs closing them before it closes the remaining windows so that it does not block the future commands to the remote end.

16.1 Take Screenshot

The Take Screenshot command takes a screenshot and return a lossless PNG encoded using Base64. If element is not populated or is null then the User Agent MUST return the screenshot of the current state of the document at the top level browsing context.

This command will return the screenshot of the current state of the document at the top level browsing context. Implementations of the remote end SHOULD capture the entire document, 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 Document, then the part of the Document 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 Document when the command is executed will be captured.

16.2 Take Element Screenshot

The Take Element Screenshot command takes a screenshot of the region encompassed by the bounding rectangle of an element, and returns it as a PNG file.

• Let element be the value from element from the URI-Template
• Let screenshot be a be a Base64 encoded, lossless PNG representation of area bounded by the clientBoundingRect of the DOMElement.
  1. If the element is not in the current viewport, the DOMElement must be scrolled into view.
  2. If the WebElement represents a FRAME or IFRAME element, this is equivalent of taking a screenshot of the frame's BODY elemen
• Return screenshot to the local end.