diff --git a/01_introduction.html b/01_introduction.html --- a/01_introduction.html +++ b/01_introduction.html @@ -48,9 +48,67 @@

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

Conformance Classes

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

+ +
+

Terminology

+ +

In equations, all numbers are integers, subtraction is + represented by “−”, and bitwise OR by “|”. The characters “(” + and “)” are used to provide logical grouping in these contexts. +

+ +
+

Common Infrastructure

+ +

Style Pixel Values

+ +

When asked to normalize style pixel values to integer + for a value s: + +

    +
  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 an integer. + +
  3. If pixels is not a valid integer or the previous + operation did not succeed, return 0. + +
  4. Return pixels. +
+ +

When asked to normalize style pixel values to floating + point for a value s: + +

    +
  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 ceil so that + it has no more than four decimals. + +
  5. Return pixels. +
+ +

These operations are almost equivalent to calling + parseInt + and parseFloat + from [[!ECMA-262]] with the exception that non-valid integer + or float return values are returned as 0 or 0.0. +

+ diff --git a/05_navigation.html b/05_navigation.html --- a/05_navigation.html +++ b/05_navigation.html @@ -78,18 +78,18 @@ GET /session/{sessionId}/url

WebDriver implementations MUST allow the users to be able to get the - current URL. In the case of a Nested Browsing Context WebDriver MUST return the URL of the [[html51]] top level browsing context. - It is the equivalent to returning document.location.href for the [[html51]] top level browsing context. + current URL. In the case of a Nested Browsing Context WebDriver MUST return the URL of the [[!HTML51]] top level browsing context. + It is the equivalent to returning document.location.href for the [[!HTML51]] top level browsing context.

If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.

void goBack()
@@ -98,17 +98,17 @@
Notes
POST /session/{sessionId}/back
-

The "goBack" command is equivalent to a user hitting the "back" button in their browser, and MUST behave as a traversal of the browser history by a delta of -1 (as defined in [[!html51]]). If a user calls "goBack" when there are no further pages in the browser's history stack, then this call MUST be a no-op. +

The "goBack" command is equivalent to a user hitting the "back" button in their browser, and MUST behave as a traversal of the browser history by a delta of -1 (as defined in [[!HTML51]]). If a user calls "goBack" when there are no further pages in the browser's history stack, then this call MUST be a no-op.

If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.

void goForward()
@@ -116,17 +116,17 @@
HTTP MethodNotes
POST /session/{sessionId}/forward
-

The "goForward" command is equivalent to a user hitting the "forward" button in their browser, and MUST behave as a traversal of the browser history by a delta of +1 (as defined in [[!html51]]). If a user calls "goForward" when there are no further pages in the browser's history stack, then this call MUST be a no-op. +

The "goForward" command is equivalent to a user hitting the "forward" button in their browser, and MUST behave as a traversal of the browser history by a delta of +1 (as defined in [[!HTML51]]). If a user calls "goForward" when there are no further pages in the browser's history stack, then this call MUST be a no-op.

If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.

void refresh()
@@ -155,17 +155,17 @@
POST /session/{sessionId}/title

- The "getTitle" command MUST return the contents of the <title> element like it would for document.title. In the case of a Nested Browsing Context WebDriver MUST return the title of the [[html51]] top level browsering context. + The "getTitle" command MUST return the contents of the <title> element like it would for document.title. In the case of a Nested Browsing Context WebDriver MUST return the title of the [[HTML51]] top level browsering context.

If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.

Invalid SSL Certificates

diff --git a/06_controlling_windows.html b/06_controlling_windows.html --- a/06_controlling_windows.html +++ b/06_controlling_windows.html @@ -1,15 +1,15 @@

Controlling Windows

Definitions

-

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

+

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

TODO: define "frame"

A Window Handow is an opaque string that MUST uniquely identify the top level browsing context and MUST NOT be "current". This MAY be a UUID.

Window Handles

diff --git a/07_switching.html b/07_switching.html --- a/07_switching.html +++ b/07_switching.html @@ -1,17 +1,17 @@

Where Commands Are Handled

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

Default Content

-

WebDriver's default content is [[!html51]]'s top level browsing context that is currently receiving WebDriver commands.

+

WebDriver's default content is [[!HTML51]]'s top level browsing context that is currently receiving WebDriver commands.

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

Switching Windows

@@ -84,13 +84,13 @@ Notes POST /session/{sessionId}/frame/parent -

The "switchToParentFrame" command MUST set the context of future commands to the window.parent. If the current context is the [[!html51]]'s top level browsing context, the context remains unchanged.

+

The "switchToParentFrame" command MUST set the context of future commands to the window.parent. If the current context is the [[!HTML51]]'s top level browsing context, the context remains unchanged.

diff --git a/08_focus.html b/08_focus.html --- a/08_focus.html +++ b/08_focus.html @@ -1,13 +1,13 @@

Running Without Window Focus

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

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

diff --git a/09_elements.html b/09_elements.html --- a/09_elements.html +++ b/09_elements.html @@ -92,12 +92,232 @@ result.append(element)

Where "search_term" is the link text being searched for, and "result" contains the list of elements to return.

XPath

Strategy name: xpath

-

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

+

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

+ +
+

Element Visibility

+ +

The visibility of a Document element + is guided by what is perceptually visible to the human eye. + An element's visibility does in this context thus not relate + in any way 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 the element's + 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. + +

An element's element visibility + is a boolean state where true signifies visibility and false + invisibility. 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. 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. + +
      2. Otherwise return false. +
      +
    + +
  5. If element is an option or + optgroup element: + +
      +
    1. For each immediate ancestral element parent + of element: + +
        +
      1. If parent is a select element, + return the result of applying the element visibility + algorithm on it if its result is false. +
      +
    + +
  6. If element is a map element, run + these substeps: + +
      +
    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 visibility 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, run the following substeps: + +
        +
      1. If parent is a map element, + apply the element visibility 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 descendant element child, in tree + order, run the following substeps: + +
        +
      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 pixels, and the value of the + width property of rectangle is + greater than zero CSS pixels: + +
          +
        1. Set visible children to visible + children bitwise OR true. +
        +
      +
    + +
  10. For each ancestral element parent, in tree + order, run the following substeps: + +
      +
    1. Apply the element visibility 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: + + + +
      5. Run step 10 on the parent elements of parent, + if any. +
      +
    + +
  11. Return true. +
+ +

If the steps above return true, then the element MUST also + be interactable should it + meet the other criteria for being interactable. If any part of + the BODY can be brought into the current viewport, the return + value MUST be true. +

diff --git a/10_element_state.html b/10_element_state.html --- a/10_element_state.html +++ b/10_element_state.html @@ -9,74 +9,93 @@
The y coordinate for the top left of the element
double height
Height of the element in CSS reference pixels
double width
Width of the element in CSS reference pixels
boolean isDisplayed()
-

+

- +
HTTP Method Path Template Notes
GET/session/{sessionId}/element/{ELEMENT}/displayed/session/{sessionId}/element/{element}/displayed
-

Determining if an element is displayed

-

The following steps MUST be used to determine if an element is displayed to a user.

- -

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

-
-

- The common usage pattern for isDisplayed is typically something similar to (in python):

- 
-              element = driver.find_element(by = TAG_NAME, value= = "button")
-              if element.is_displayed():
-                  element.click()
-              else
-                  # So other deep magic of the unseen ages.
-
-
-

If isDisplayed returns true, then the element MUST also be - interactable should it meet the other criteria for being interactable. If any part of the BODY can be brought into the current viewport, this MUST return true. -

-

This implies that isDisplayed MUST return true if the centre of the element could be brought into the viewport. The exception to this would be the BODY element, which is generally assumed to always be displayed by users of the WebDriver spec. It is possible to interact with elements which may not have the centre point brought into the viewport by using the low level commands. This means that if any part of the element could be brought into the viewport by user action and its position could be used by low-level commands then a WebDriver implementation MAY return true.

-
-

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

The command is used to determine the element + visibility of the Document element + connected with the web element reference given by + the element fragment in the path. + +

The response is composed using the following algorithm:

+ +
    +
  1. Let response be an initially empty + response. + +
  2. Let visible be a boolean initially set to + false. + +
  3. Let element be an initially undefined Document + element. + +
  4. Let element reference be a string with the + value of the element fragment from the path. + +
  5. If element reference is null or has a + length equal to 0, set response's status to the invalid + argument status and return response. + +
  6. If the default content's top + level browsing context is no longer open, set + response's status + to the no such window status and return + response. + +
  7. Set element be the Document element + found after applying the web element lookup algorithm + to the element reference map.
  8. If element + is null or element does not represent a Document + element, set response's status to the no such + element status and return response. + +
  9. If element represents Document element + that is no longer attached to the document's node tree, + set response's status + to the stale element reference status and return + response. + +
  10. Apply the element visibility algorithm to + element and set visible to its + return value.
    11. + +
  11. Set response's status to success and + its value to visible. + +
  12. Return response. +
+
boolean isSelected()

@@ -85,18 +104,18 @@
HTTP Method Path Template Notes
/session/{sessionId}/element/{ELEMENT}/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. -
  2. If the Document node represented by the WebElement is an OPTION element, the "selectedness" of the element, as defined in [[!html51]] determines whether the element is selected.
    3. -
  3. Otherwise, the value of the Document node's "checked" property determines whether the element is selected. This MUST reflect the element's "checkedness" as defined in [[!html51]].
    4. +
  4. If the Document node represented by the WebElement is an OPTION element, the "selectedness" of the element, as defined in [[!HTML51]] determines whether the element is selected.
    5. +
  5. Otherwise, the value of the Document node's "checked" property determines whether the element is selected. This MUST reflect the element's "checkedness" as defined in [[!HTML51]].

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

DOMString getElementAttribute()

@@ -104,17 +123,17 @@
HTTP MethodNotes
GET /session/{sessionId}/element/{ELEMENT}/attribute/{name}
-

Although the [[!html51]] spec is very clear about the difference between the properties and attributes of a Document 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 Document element 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.

+

Although the [[!HTML51]] spec is very clear about the difference between the properties and attributes of a Document 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 Document element 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.

The algorithm to implement this MUST be (where name refers to the name parameter of the getElementAttribute command):

  1. If name case insensitively matches "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.
    • 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): 
      @@ -331,17 +350,17 @@
                GET
                /session/{sessionId}/element/{ELEMENT}/enabled
                
              
            
         
      The "isEnabled" command MUST return false if all the following criteria are met otherwise return true:
           
      
 
         
      If the ELEMENT does not represent a Document element, or it represents a Document element that is no longer attached to the document 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.
diff --git a/12_cookies.html b/12_cookies.html --- a/12_cookies.html +++ b/12_cookies.html @@ -1,14 +1,14 @@

Cookies

This section describes the interaction with cookies - as described in the HTML Specification ([[!html51]]). When retrieving + as described in the HTML Specification ([[!HTML51]]). When retrieving and setting a cookie it MUST be in the format of a Cookie.

Conformance tests for this section can be found in the webdriver module under the "cookies" folder.

Cookie

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

DOMString name
The name of the cookie. This MUST be set.
diff --git a/14_user_input.html b/14_user_input.html --- a/14_user_input.html +++ b/14_user_input.html @@ -11,17 +11,17 @@

Interactable elements

Some user actions 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 + attribute (according to the [[!HTML51]] spec), or if the disabled attribute is set in the case where that attribute is present.

Low Level Commands

@@ -402,32 +402,32 @@

Typing keys

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

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

-

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

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

void clear()
Clears the value of the element.
void sendKeys()
DOMString value
diff --git a/webdriver-spec.html b/webdriver-spec.html --- a/webdriver-spec.html +++ b/webdriver-spec.html @@ -147,17 +147,75 @@ code a:visited, code a:link {

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

Conformance Classes

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

+ +
+

Terminology

+ +

In equations, all numbers are integers, subtraction is + represented by “−”, and bitwise OR by “|”. The characters “(” + and “)” are used to provide logical grouping in these contexts. +

+ +
+

Common Infrastructure

+ +

Style Pixel Values

+ +

When asked to normalize style pixel values to integer + for a value s: + +

    +
  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 an integer. + +
  3. If pixels is not a valid integer or the previous + operation did not succeed, return 0. + +
  4. Return pixels. +
+ +

When asked to normalize style pixel values to floating + point for a value s: + +

    +
  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 ceil so that + it has no more than four decimals. + +
  5. Return pixels. +
+ +

These operations are almost equivalent to calling + parseInt + and parseFloat + from [[!ECMA-262]] with the exception that non-valid integer + or float return values are returned as 0 or 0.0. +

+

Commands and Responses

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

Command

interface Command {
@@ -625,18 +683,18 @@ A Command instance MUST be 
           
           
             GET
             /session/{sessionId}/url
             
           
         
         
WebDriver implementations MUST allow the users to be able to get the
-          current URL. In the case of a Nested Browsing Context WebDriver MUST return the URL of the [[html51]] top level browsing context.
-          It is the equivalent to returning document.location.href for the [[html51]] top level browsing context.
+          current URL. In the case of a Nested Browsing Context WebDriver MUST return the URL of the [[!HTML51]] top level browsing context.
+          It is the equivalent to returning document.location.href for the [[!HTML51]] top level browsing context.
         
 If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.
       
 
       
       
void goBack()

       

         
@@ -645,17 +703,17 @@ A Command instance MUST be 
             

           
Notes
           

           

             POST
             /session/{sessionId}/back
             
           

         

-        
The "goBack" command is equivalent to a user hitting the "back" button in their browser, and MUST behave as a traversal of the browser history by a delta of -1 (as defined in [[!html51]]). If a user calls "goBack" when there are no further pages in the browser's history stack, then this call MUST be a no-op.
+        
The "goBack" command is equivalent to a user hitting the "back" button in their browser, and MUST behave as a traversal of the browser history by a delta of -1 (as defined in [[!HTML51]]). If a user calls "goBack" when there are no further pages in the browser's history stack, then this call MUST be a no-op.
         

         
 If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.
       

       
void goForward()

       

         
@@ -663,17 +721,17 @@ A Command instance MUST be 
             

           

             HTTP MethodNotes
           

           

             POST
             /session/{sessionId}/forward
             
           

         

-        
The "goForward" command is equivalent to a user hitting the "forward" button in their browser, and MUST behave as a traversal of the browser history by a delta of +1 (as defined in [[!html51]]). If a user calls "goForward" when there are no further pages in the browser's history stack, then this call MUST be a no-op.
+        
The "goForward" command is equivalent to a user hitting the "forward" button in their browser, and MUST behave as a traversal of the browser history by a delta of +1 (as defined in [[!HTML51]]). If a user calls "goForward" when there are no further pages in the browser's history stack, then this call MUST be a no-op.
         
 If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.
       

 
       
       
void refresh()

       

         
@@ -702,17 +760,17 @@ A Command instance MUST be 
           

           

           

             POST
             /session/{sessionId}/title
             
           

         

         

-          The "getTitle" command MUST return the contents of the <title> element like it would for document.title. In the case of a Nested Browsing Context WebDriver MUST return the title of the [[html51]] top level browsering context.
+          The "getTitle" command MUST return the contents of the <title> element like it would for document.title. In the case of a Nested Browsing Context WebDriver MUST return the title of the [[HTML51]] top level browsering context.
 
           
 If the page takes too long as specified by the timeouts a timeout error MUST be raised. If the top level browsing context currently receiving commands is no longer open a no such window error MUST be raised.
         

       

     
 
     

       
Invalid SSL Certificates

@@ -741,17 +799,17 @@ A Command instance MUST be

Controlling Windows

Definitions

-

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

+

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

TODO: define "frame"

A Window Handow is an opaque string that MUST uniquely identify the top level browsing context and MUST NOT be "current". This MAY be a UUID.

Window Handles

@@ -926,17 +984,17 @@ A Command instance MUST be

Where Commands Are Handled

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

Default Content

-

WebDriver's default content is [[!html51]]'s top level browsing context that is currently receiving WebDriver commands.

+

WebDriver's default content is [[!HTML51]]'s top level browsing context that is currently receiving WebDriver commands.

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

Switching Windows

@@ -1009,27 +1067,27 @@ A Command instance MUST be Notes POST /session/{sessionId}/frame/parent -

The "switchToParentFrame" command MUST set the context of future commands to the window.parent. If the current context is the [[!html51]]'s top level browsing context, the context remains unchanged.

+

The "switchToParentFrame" command MUST set the context of future commands to the window.parent. If the current context is the [[!HTML51]]'s top level browsing context, the context remains unchanged.

Running Without Window Focus

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

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

@@ -1126,19 +1184,239 @@ A Command instance MUST be result.append(element)

Where "search_term" is the link text being searched for, and "result" contains the list of elements to return.

XPath

Strategy name: xpath

-

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

+

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

+ +
+

Element Visibility

+ +

The visibility of a Document element + is guided by what is perceptually visible to the human eye. + An element's visibility does in this context thus not relate + in any way 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 the element's + 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. + +

An element's element visibility + is a boolean state where true signifies visibility and false + invisibility. 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. 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. + +
      2. Otherwise return false. +
      +
    + +
  5. If element is an option or + optgroup element: + +
      +
    1. For each immediate ancestral element parent + of element: + +
        +
      1. If parent is a select element, + return the result of applying the element visibility + algorithm on it if its result is false. +
      +
    + +
  6. If element is a map element, run + these substeps: + +
      +
    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 visibility 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, run the following substeps: + +
        +
      1. If parent is a map element, + apply the element visibility 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 descendant element child, in tree + order, run the following substeps: + +
        +
      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 pixels, and the value of the + width property of rectangle is + greater than zero CSS pixels: + +
          +
        1. Set visible children to visible + children bitwise OR true. +
        +
      +
    + +
  10. For each ancestral element parent, in tree + order, run the following substeps: + +
      +
    1. Apply the element visibility 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: + + + +
      5. Run step 10 on the parent elements of parent, + if any. +
      +
    + +
  11. Return true. +
+ +

If the steps above return true, then the element MUST also + be interactable should it + meet the other criteria for being interactable. If any part of + the BODY can be brought into the current viewport, the return + value MUST be true. +

Reading Element State

Conformance tests for this section can be found in the webdriver module under the "element_state" folder.

double x
The x coordinate for the top left of the element
@@ -1146,74 +1424,93 @@ A Command instance MUST be
The y coordinate for the top left of the element
double height
Height of the element in CSS reference pixels
double width
Width of the element in CSS reference pixels
boolean isDisplayed()
-

+

- +
HTTP Method Path Template Notes
GET/session/{sessionId}/element/{ELEMENT}/displayed/session/{sessionId}/element/{element}/displayed
-

Determining if an element is displayed

-

The following steps MUST be used to determine if an element is displayed to a user.

-
    -
  • The BODY element MUST be displayed irrespective of any CSS style. This is due to the backgrounds of special elements showing through from the document canvas.
    • -
  • Any INPUT elements of "type=hidden" MUST NOT be displayed.
    • -
  • Any NOSCRIPT elements MUST NOT be displayed.
    • -
  • OPTIONs and OPTGROUP elements MUST be displayed if and only if the enclosing select element is displayed.
    • -
  • MAP elements are displayed if and only if the image it uses is displayed. Areas within - a map are displayed if the enclosing MAP is displayed.
    • -
  • If element is a [[!DOM4]] - text node then it MUST be displayed.
    • -
  • The element MUST NOT be displayed if there is a [[!css3-2d-transforms]] or [[!css3-3d-transforms]] - property that gives a negative x or y to the canvas. The User Agent MUST NOT allow negative scrolling.
    • -
  • The element MUST NOT be displayed if that element, or any of its ancestors, - has a hidden attribute - or has display:none in its computed CSS style.
    • -
  • If element or at least one of its descendents have both - DOMRect - height and a DOMRect - width greater than 0px, as returned by element.getBoundingClientRect() - then it MUST be displayed.
    • -
  • The element MUST NOT be displayed if any ancestor of the element has a fixed size, and has the CSS style with one of the following overflow:hidden, overflow-x:hidden or overflow-y:hidden, and the element's location as determined by getClientRects is not within the fixed size of the parent.
    • -
-

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

-
-

- The common usage pattern for isDisplayed is typically something similar to (in python):

- 
-              element = driver.find_element(by = TAG_NAME, value= = "button")
-              if element.is_displayed():
-                  element.click()
-              else
-                  # So other deep magic of the unseen ages.
-
-
-

If isDisplayed returns true, then the element MUST also be - interactable should it meet the other criteria for being interactable. If any part of the BODY can be brought into the current viewport, this MUST return true. -

-

This implies that isDisplayed MUST return true if the centre of the element could be brought into the viewport. The exception to this would be the BODY element, which is generally assumed to always be displayed by users of the WebDriver spec. It is possible to interact with elements which may not have the centre point brought into the viewport by using the low level commands. This means that if any part of the element could be brought into the viewport by user action and its position could be used by low-level commands then a WebDriver implementation MAY return true.

-
-

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

The command is used to determine the element + visibility of the Document element + connected with the web element reference given by + the element fragment in the path. + +

The response is composed using the following algorithm:

+ +
    +
  1. Let response be an initially empty + response. + +
  2. Let visible be a boolean initially set to + false. + +
  3. Let element be an initially undefined Document + element. + +
  4. Let element reference be a string with the + value of the element fragment from the path. + +
  5. If element reference is null or has a + length equal to 0, set response's status to the invalid + argument status and return response. + +
  6. If the default content's top + level browsing context is no longer open, set + response's status + to the no such window status and return + response. + +
  7. Set element be the Document element + found after applying the web element lookup algorithm + to the element reference map.
  8. If element + is null or element does not represent a Document + element, set response's status to the no such + element status and return response. + +
  9. If element represents Document element + that is no longer attached to the document's node tree, + set response's status + to the stale element reference status and return + response. + +
  10. Apply the element visibility algorithm to + element and set visible to its + return value.
    11. + +
  11. Set response's status to success and + its value to visible. + +
  12. Return response. +
+
boolean isSelected()

@@ -1222,18 +1519,18 @@ A Command instance MUST be
HTTP Method Path Template Notes
/session/{sessionId}/element/{ELEMENT}/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. -
  2. If the Document node represented by the WebElement is an OPTION element, the "selectedness" of the element, as defined in [[!html51]] determines whether the element is selected.
    3. -
  3. Otherwise, the value of the Document node's "checked" property determines whether the element is selected. This MUST reflect the element's "checkedness" as defined in [[!html51]].
    4. +
  4. If the Document node represented by the WebElement is an OPTION element, the "selectedness" of the element, as defined in [[!HTML51]] determines whether the element is selected.
    5. +
  5. Otherwise, the value of the Document node's "checked" property determines whether the element is selected. This MUST reflect the element's "checkedness" as defined in [[!HTML51]].

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

DOMString getElementAttribute()

@@ -1241,17 +1538,17 @@ A Command instance MUST be
HTTP MethodNotes
GET /session/{sessionId}/element/{ELEMENT}/attribute/{name}
-

Although the [[!html51]] spec is very clear about the difference between the properties and attributes of a Document 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 Document element 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.

+

Although the [[!HTML51]] spec is very clear about the difference between the properties and attributes of a Document 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 Document element 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.

The algorithm to implement this MUST be (where name refers to the name parameter of the getElementAttribute command):

  1. If name case insensitively matches "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.
    • 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): 
      @@ -1468,18 +1765,18 @@ A Command instance MUST be 
                GET
                /session/{sessionId}/element/{ELEMENT}/enabled
                
              
            
         
      The "isEnabled" command MUST return false if all the following criteria are met otherwise return true:
           
      
 
         
      If the ELEMENT does not represent a Document element, or it represents a Document element that is no longer attached to the document 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.
@@ -1671,17 +1968,17 @@ A Command instance MUST be

Cookies

This section describes the interaction with cookies - as described in the HTML Specification ([[!html51]]). When retrieving + as described in the HTML Specification ([[!HTML51]]). When retrieving and setting a cookie it MUST be in the format of a Cookie.

Conformance tests for this section can be found in the webdriver module under the "cookies" folder.

Cookie

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

DOMString name
The name of the cookie. This MUST be set.
@@ -1812,17 +2109,17 @@ A Command instance MUST be

Interactable elements

Some user actions 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 + attribute (according to the [[!HTML51]] spec), or if the disabled attribute is set in the case where that attribute is present.

Low Level Commands

@@ -2203,32 +2500,32 @@ A Command instance MUST be

Typing keys

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

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

-

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

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

void clear()
Clears the value of the element.
void sendKeys()
DOMString value
@@ -2794,17 +3091,17 @@ A Command instance MUST be
  • /session/{sessionId}/window_handles
  • /session/{sessionId}/window_handle
  • /session/{sessionId}/window/size
  • /session/{sessionId}/window/size
  • /session/{sessionId}/window/maximize
  • /session/{sessionId}/window
  • /session/{sessionId}/frame
  • /session/{sessionId}/frame/parent
    • -
  • /session/{sessionId}/element/{ELEMENT}/displayed
    • +
  • /session/{sessionId}/element/{element}/displayed
  • /session/{sessionId}/element/{ELEMENT}/selected
  • /session/{sessionId}/element/{ELEMENT}/attribute/{name}
  • /session/{sessionId}/element/{ELEMENT}/css/{propertyName}
  • /session/{sessionId}/element/{ELEMENT}/text
  • /session/{sessionId}/element/{ELEMENT}/name
  • /session/{sessionId}/element/{ELEMENT}/rect
  • /session/{sessionId}/element/{ELEMENT}/enabled
  • /session/{sessionId}/execute