[js] Add the ability to do Relative Locators with all By types

This also adds documentation for the new features.

Fixes #9559

Author: AutomatedTester

javascript/node/selenium-webdriver/lib/by.js

@@ -258,8 +258,36 @@ class By {
   }
 }
 
+/**
+ * Start Searching for relative objects using the value returned from
+ * `By.tagName()`.
+ *
+ * Note: this method will likely be removed in the future please use
+ * `locateWith`.
+ * @param {By} The value returned from calling By.tagName()
+ * @returns
+ */
 function withTagName(tagName) {
-  return new RelativeBy(tagName)
+  return new RelativeBy({ 'css selector': tagName })
+}
+
+/**
+ * Start searching for relative objects using search criteria with By.
+ * @param {string} A By map that shows how to find the initial element
+ * @returns {RelativeBy}
+ */
+function locateWith(by) {
+  return new RelativeBy(getLocator(by));
+}
+
+function getLocator(locatorOrElement) {
+  let toFind
+  if (locatorOrElement instanceof By) {
+    toFind = locatorOrElement.toObject()
+  } else {
+    toFind = locatorOrElement
+  }
+  return toFind
 }
 
 /**
@@ -269,11 +297,11 @@ function withTagName(tagName) {
  */
 class RelativeBy {
   /**
-   * @param {string} tagName
+   * @param {By} findDetails
    * @param {Array<Object>} filters
    */
-  constructor(tagName, filters = null) {
-    this.root = tagName
+  constructor(findDetails, filters = null) {
+    this.root = findDetails
     this.filters = filters || []
   }
 
@@ -285,7 +313,7 @@ class RelativeBy {
   above(locatorOrElement) {
     this.filters.push({
       kind: 'above',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -298,7 +326,7 @@ class RelativeBy {
   below(locatorOrElement) {
     this.filters.push({
       kind: 'below',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -311,7 +339,7 @@ class RelativeBy {
   toLeftOf(locatorOrElement) {
     this.filters.push({
       kind: 'left',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -324,7 +352,7 @@ class RelativeBy {
   toRightOf(locatorOrElement) {
     this.filters.push({
       kind: 'right',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -337,7 +365,7 @@ class RelativeBy {
   near(locatorOrElement) {
     this.filters.push({
       kind: 'near',
-      args: [this.getLocator(locatorOrElement)],
+      args: [getLocator(locatorOrElement)],
     })
     return this
   }
@@ -350,22 +378,12 @@ class RelativeBy {
   marshall() {
     return {
       relative: {
-        root: { 'css selector': this.root },
+        root: this.root,
         filters: this.filters,
       },
     }
   }
 
-  getLocator(locatorOrElement) {
-    let toFind
-    if (locatorOrElement instanceof By) {
-      toFind = locatorOrElement.toObject()
-    } else {
-      toFind = locatorOrElement
-    }
-    return toFind
-  }
-
   /** @override */
   toString() {
     // The static By.name() overrides this.constructor.name.  Shame...
@@ -411,5 +429,6 @@ module.exports = {
   By: By,
   RelativeBy: RelativeBy,
   withTagName: withTagName,
+  locateWith: locateWith,
   checkedLocator: check,
 }

javascript/node/selenium-webdriver/test/element_finding_test.js

@@ -21,6 +21,7 @@ const assert = require('assert')
 const promise = require('../lib/promise')
 const { Browser, By, error, withTagName, until } = require('..')
 const { Pages, ignore, suite, whereIs } = require('../lib/test')
+const { locateWith } = require('../lib/by')
 
 suite(function (env) {
   const browsers = (...args) => env.browsers(...args)
@@ -61,7 +62,7 @@ suite(function (env) {
 
       it(
         'should find multiple elements by ID even though that is ' +
-          'malformed HTML',
+        'malformed HTML',
         async function () {
           await driver.get(Pages.nestedPage)
 
@@ -306,7 +307,7 @@ suite(function (env) {
 
       it(
         'should find first matching element when searching by ' +
-          'compound CSS selector',
+        'compound CSS selector',
         async function () {
           await driver.get(Pages.xhtmlTestPage)
 
@@ -349,7 +350,7 @@ suite(function (env) {
 
       it(
         'should be able to find element with short ' +
-          'boolean attribute selector',
+        'boolean attribute selector',
         async function () {
           await driver.get(
             whereIs('locators_tests/boolean_attribute_selected.html')
@@ -362,7 +363,7 @@ suite(function (env) {
 
       it(
         'should be able to find element with short boolean attribute ' +
-          'selector on HTML4 page',
+        'selector on HTML4 page',
         async function () {
           await driver.get(
             whereIs('locators_tests/boolean_attribute_selected_html4.html')
@@ -462,6 +463,12 @@ suite(function (env) {
         )
         assert.deepStrictEqual(await element.getAttribute('id'), `third`)
       })
+
+      it('should search by passing in a by object', async function () {
+        await driver.get(Pages.relativeLocators)
+        let element = await driver.findElement(locateWith(By.css('p')).above(await driver.findElement(By.id('below'))))
+        assert.deepStrictEqual(await element.getAttribute('id'), 'mid')
+      })
     })
 
     describe('switchTo().activeElement()', function () {

javascript/node/selenium-webdriver/test/lib/by_test.js

@@ -89,7 +89,8 @@ describe('by', function () {
 
   describe('RelativeBy', function () {
     it('marshalls the RelativeBy object', function () {
-      let relative = by.withTagName('p').above(by.By.name('foobar'))
+      let relative = by.locateWith(by.By.tagName('p')).above(by.By.name('foobar'))
+
       let expected = {
         relative: {
           root: { 'css selector': 'p' },
@@ -110,7 +111,7 @@ describe('by', function () {
     })
 
     it('accepts custom locator functions', function () {
-      let original = function () {}
+      let original = function () { }
       let locator = by.checkedLocator(original)
       assert.strictEqual(locator, original)
     })