Return results from Relative locators sorted by proximity to the anchor

Where "proximity" is measued as "distance from the centre points of
the bounding client rects"

Author: shs96c

java/client/src/org/openqa/selenium/support/locators/RelativeLocator.java

@@ -39,6 +39,37 @@
 
 import static org.openqa.selenium.json.Json.MAP_TYPE;
 
+/**
+ * Used for finding elements by their location on a page, rather than their
+ * position on the DOM. Elements are returned ordered by their proximity to
+ * the last anchor element used for finding them. As an example:
+ * <pre>
+ *   List<WebElement> elements = driver.findElements(withTagName("p").above(lowest));
+ * </pre>
+ * Would return all {@code p} elements above the {@link WebElement}
+ * {@code lowest} sorted by the proximity to {@code lowest}.
+ * <p>
+ * Proximity is determined by simply comparing the distance to the center
+ * point of each of the elements in turn. For some non-rectangular shapes
+ * (such as paragraphs of text that take more than one line), this may lead
+ * to some surprising results.
+ * <p>
+ * In addition, be aware that the relative locators all use the "client
+ * bounding rect" of elements to determine whether something is "left",
+ * "right", "above" or "below" of another. Given the example:
+ * <pre>
+ *   +-----+
+ *   |  a  |---+
+ *   +-----+ b |
+ *       +-----+
+ * </pre>
+ * Where {@code a} partially overlaps {@code b}, {@code b} is none of
+ * "above", "below", "left" or "right" of {@code a}. This is because of
+ * how these are calculated using the box model. {@code b}'s bounding
+ * rect has it's left-most edge to the right of {@code a}'s bounding
+ * rect's right-most edge, so it is not considered to be "right" of
+ * {@code a}. Similar logic applies for the other directions.
+ */
 public class RelativeLocator {
 
   private static final Json JSON = new Json();
@@ -58,6 +89,10 @@ public class RelativeLocator {
       throw new UncheckedIOException(e);
     }
   }
+
+  /**
+   * Start of a relative locator, finding elements by tag name.
+   */
   public static RelativeBy withTagName(String tagName) {
     Require.nonNull("Tag name to look for", tagName);
     return new RelativeBy(By.tagName(tagName));

java/client/test/org/openqa/selenium/support/locators/RelativeLocatorTest.java

@@ -41,7 +41,7 @@ public void shouldBeAbleToFindElementsAboveAnother() {
     List<WebElement> elements = driver.findElements(withTagName("p").above(lowest));
     List<String> ids = elements.stream().map(e -> e.getAttribute("id")).collect(Collectors.toList());
 
-    assertThat(ids).isEqualTo(Arrays.asList("above", "mid"));
+    assertThat(ids).isEqualTo(Arrays.asList("mid", "above"));
   }
 
   @Test

javascript/atoms/locators/relative.js

@@ -152,7 +152,6 @@ bot.locators.relative.near_ = function(selector, opt_distance) {
     distance = 50;
   }
 
-
   /**
    * @param {!Element} compareTo
    * @return {boolean}
@@ -251,6 +250,13 @@ bot.locators.relative.STRATEGIES_ = {
   'near': bot.locators.relative.near_,
 };
 
+bot.locators.relative.RESOLVERS_ = {
+  'left': bot.locators.relative.resolve_,
+  'right': bot.locators.relative.resolve_,
+  'above': bot.locators.relative.resolve_,
+  'below': bot.locators.relative.resolve_,
+  'near': bot.locators.relative.resolve_,
+};
 
 /**
  * @param {!IArrayLike<!Element>} allElements
@@ -292,7 +298,54 @@ bot.locators.relative.filterElements_ = function(allElements, filters) {
     },
     null);
 
-  return toReturn;
+  // We want to sort the returned elements by proximity to the last "anchor"
+  // element in the filters.
+  var finalFilter = goog.array.last(filters);
+  var name = finalFilter ? finalFilter["kind"] : "unknown";
+  var resolver = bot.locators.relative.RESOLVERS_[name];
+  if (!!!resolver) {
+    return toReturn;
+  }
+  var lastAnchor = resolver.apply(null, finalFilter["args"]);
+  if (!!!lastAnchor) {
+    return toReturn;
+  }
+
+  return bot.locators.relative.sortByProximity_(lastAnchor, toReturn);
+};
+
+
+/**
+ * @param {!Element} anchor
+ * @param {!Array<!Element>} elements
+ * @return {!Array<!Element>}
+ * @private
+ */
+bot.locators.relative.sortByProximity_ = function(anchor, elements) {
+  var anchorRect = bot.dom.getClientRect(anchor);
+  var anchorCenter = {
+    x: anchorRect.left + (Math.max(1, anchorRect.width) / 2),
+    y: anchorRect.top + (Math.max(1, anchorRect.height) / 2)
+  };
+
+  var distance = function(e) {
+    var rect = bot.dom.getClientRect(e);
+    var center = {
+      x: rect.left + (Math.max(1, rect.width) / 2),
+      y: rect.top + (Math.max(1, rect.height) / 2)
+    };
+
+    var x = Math.pow(anchorCenter.x - center.x, 2);
+    var y = Math.pow(anchorCenter.y - center.y, 2);
+
+    return Math.sqrt(x + y);
+  };
+
+  goog.array.sort(elements, function(left, right) {
+    return distance(left) - distance(right);
+  });
+
+  return elements;
 };
 
 

javascript/atoms/test/relative_locator_test.html

@@ -84,16 +84,16 @@
       var found = bot.locators.findElements({relative: {root: {"tag name": "p"}, filters: [above(lowest)]}});
 
       assertEquals(2, found.length);
-      assertEquals("above", found[0].getAttribute("id"));
-      assertEquals("mid", found[1].getAttribute("id"));
+      assertEquals("mid", found[0].getAttribute("id"));
+      assertEquals("above", found[1].getAttribute("id"));
     }
 
     function testCanFindAllElementsAboveAnother() {
       var found = bot.locators.findElements({relative: {root: {tagName: 'td'}, filters: [above({id: "center"})]}});
 
       assertEquals(3, found.length);
-      assertEquals("first", found[0].getAttribute("id"));
-      assertEquals("second", found[1].getAttribute("id"));
+      assertEquals("second", found[0].getAttribute("id"));
+      assertEquals("first", found[1].getAttribute("id"));
       assertEquals("third", found[2].getAttribute("id"));
     }
 
@@ -112,30 +112,31 @@
       // don't expect the three cells on the left of the table to be found.
       var found = bot.locators.findElements({relative: {root: {tagName: 'td'}, filters: [{kind: "near", args: [{id: "sixth"}]}]}});
 
+      // Elements are sorted by proximity to "sixth"
       assertEquals(5, found.length);
-      assertEquals("second", found[0].getAttribute("id"));
-      assertEquals("third", found[1].getAttribute("id"));
+      assertEquals("third", found[0].getAttribute("id"));
+      assertEquals("ninth", found[1].getAttribute("id"));
       assertEquals("center", found[2].getAttribute("id"));
       // Note: an element is not near itself.
-      assertEquals("eighth", found[3].getAttribute("id"));
-      assertEquals("ninth", found[4].getAttribute("id"));
+      assertEquals("second", found[3].getAttribute("id"));
+      assertEquals("eighth", found[4].getAttribute("id"));
     }
 
     function testShouldBeAbleToFindAnElementToTheLeftOfAnother() {
       var found = bot.locators.findElements({relative: {root: {tagName: 'td'}, filters: [leftOf({id: "center"})]}});
 
       assertEquals(3, found.length);
-      assertEquals("first", found[0].getAttribute("id"));
-      assertEquals("fourth", found[1].getAttribute("id"));
+      assertEquals("fourth", found[0].getAttribute("id"));
+      assertEquals("first", found[1].getAttribute("id"));
       assertEquals("seventh", found[2].getAttribute("id"));
     }
 
     function testShouldBeAbleToFindAnElementTheRightOfAnother() {
       var found = bot.locators.findElements({relative: {root: {tagName: 'td'}, filters: [rightOf({id: "center"})]}});
 
       assertEquals(3, found.length);
-      assertEquals("third", found[0].getAttribute("id"));
-      assertEquals("sixth", found[1].getAttribute("id"));
+      assertEquals("sixth", found[0].getAttribute("id"));
+      assertEquals("third", found[1].getAttribute("id"));
       assertEquals("ninth", found[2].getAttribute("id"));
     }
 
@@ -201,9 +202,11 @@
           }
         })
 
-        // console.log(found);
-        //
-        // assertEquals([blue, yellow, green], found);
+        var expected = [blue, yellow, green];
+        assertEquals(expected.length, found.length);
+        for (var i = 0; i < expected.length; i++) {
+          assertEquals(expected[i], found[i]);
+        }
       } finally {
         bot.setWindow(current);
       }