Bug 1255955 - Document clickElement and calculateCentreCoords; r=automatedtester, a=test-only
authorAndreas Tolfsen <ato@mozilla.com>
Sat, 13 Aug 2016 20:54:15 +0200
changeset 342394 11781f2941a9501252f0707777865d8e1541837a
parent 342393 a6cb9a93d51e122302bcfb60754c2ef70a59d5fc
child 342395 8466497088808d2f4e3b24958184ca58f96abb69
push id1183
push userraliiev@mozilla.com
push dateMon, 05 Sep 2016 20:01:49 +0000
treeherdermozilla-release@3148731bed45 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersautomatedtester, test-only
bugs1255955
milestone49.0
Bug 1255955 - Document clickElement and calculateCentreCoords; r=automatedtester, a=test-only MozReview-Commit-ID: tSC5xRAVAl
testing/marionette/interaction.js
--- a/testing/marionette/interaction.js
+++ b/testing/marionette/interaction.js
@@ -74,22 +74,45 @@ const SELECTED_PROPERTY_SUPPORTED_XUL = 
   "TAB",
 ]);
 
 this.interaction = {};
 
 /**
  * Interact with an element by clicking it.
  *
+ * The element is scrolled into view before visibility- or interactability
+ * checks are performed.
+ *
+ * Selenium-style visibility checks will be performed if |specCompat|
+ * is false (default).  Otherwise pointer-interactability checks will be
+ * performed.  If either of these fail an {@code ElementNotVisibleError}
+ * is returned.
+ *
+ * If |strict| is enabled (defaults to disabled), further accessibility
+ * checks will be performed, and these may result in an {@code
+ * ElementNotAccessibleError} being returned.
+ *
+ * When |el| is not enabled, an {@code InvalidElementStateError}
+ * is returned.
+ *
  * @param {DOMElement|XULElement} el
  *     Element to click.
  * @param {boolean=} strict
  *     Enforce strict accessibility tests.
  * @param {boolean=} specCompat
  *     Use WebDriver specification compatible interactability definition.
+ *
+ * @throws {ElementNotVisibleError}
+ *     If either Selenium-style visibility check or
+ *     pointer-interactability check fails.
+ * @throws {ElementNotAccessibleError}
+ *     If |strict| is true and element is not accessible.
+ * @throws {InvalidElementStateError}
+ *     If |el| is not enabled.
  */
 interaction.clickElement = function(el, strict = false, specCompat = false) {
   let a11y = accessibility.get(strict);
   return a11y.getAccessible(el, true).then(acc => {
     let win = getWindow(el);
 
     let selectEl;
     let visibilityCheckEl = el;
@@ -135,16 +158,26 @@ interaction.clickElement = function(el, 
         let centre = interaction.calculateCentreCoords(el);
         let opts = {};
         event.synthesizeMouseAtPoint(centre.x, centre.y, opts, win);
       }
     }
   });
 };
 
+/**
+ * Calculate the in-view centre point, that is the centre point of the
+ * area of the first DOM client rectangle that is inside the viewport.
+ *
+ * @param {DOMElement} el
+ *     Element to calculate the visible centre point of.
+ *
+ * @return {Object.<string, number>}
+ *     X- and Y-position.
+ */
 interaction.calculateCentreCoords = function(el) {
   let rects = el.getClientRects();
   return {
     x: rects[0].left + rects[0].width / 2.0,
     y: rects[0].top + rects[0].height / 2.0,
   };
 };