fixes nightwatchjs#1115 - adds optional index property to element objects

Author: senocular

lib/api/element-commands.js

@@ -341,12 +341,15 @@ module.exports = function(client) {
   function CommandAction(using, value, protocolAction, args, callback, originalStackTrace) {
     events.EventEmitter.call(this);
 
-    var $this = this;
-    var el = Protocol.element(using, value, function(result) {
+    var elem = Element.fromSelector(value, using);
+    var multipleElements = Element.requiresFiltering(elem);
+    var elementAction = multipleElements ? 'elements' : 'element';
+
+    var self = this;
+    var el = Protocol[elementAction](using, value, function(result) {
       if (result.status !== 0) {
         callback.call(client.api, result);
 
-        var elem = Element.fromSelector(value, using);
         var errorMessage = 'ERROR: Unable to locate element: "' + elem.selector + '" using: "' + elem.locateStrategy + '"';
         var stack = originalStackTrace.split('\n');
 
@@ -356,18 +359,18 @@ module.exports = function(client) {
         client.results.errors++;
         client.errors.push(errorMessage + '\n' + stack.join('\n'));
 
-        $this.emit('complete', el, $this);
+        self.emit('complete', el, self);
       } else {
-        result = result.value.ELEMENT;
+        var elemId = multipleElements ? result.value[0].ELEMENT : result.value.ELEMENT;
 
         args.push(function(r) {
           callback.call(client.api, r);
         });
 
-        args.unshift(result);
+        args.unshift(elemId);
 
         var c = Protocol[protocolAction].apply(Protocol, args).once('complete', function() {
-          $this.emit('complete', c, $this);
+          self.emit('complete', c, self);
         });
       }
     });

lib/api/element-commands/_elementByRecursion.js

@@ -1,5 +1,6 @@
 var util = require('util');
 var events = require('events');
+var Element = require('../../page-object/element.js');
 
 /**
  * Search for an element on the page, starting with the first element of the array, and where each element in the passed array is nested under the previous one. The located element will be returned as a WebElement JSON object.
@@ -21,15 +22,26 @@ ElementByRecursion.prototype.command = function(elements, callback) {
   var allElements = elements.slice();
 
   var topElement = allElements.shift();
-  var el = this.protocol.element(null, topElement, function checkResult(result) {
+  var multipleElements = Element.requiresFiltering(topElement);
+  var elementAction = multipleElements ? 'elements' : 'element';
+
+  var el = this.protocol[elementAction](null, topElement, function checkResult(result) {
     if (result.status !== 0) {
       callback(result);
       self.emit('complete', el, self);
     } else {
+
+      if (multipleElements) {
+        result.value = result.value[0];
+      }
+
       var nextElement = allElements.shift();
-      var parentId = result.value.ELEMENT;
+
       if (nextElement) {
-        self.protocol.elementIdElement(parentId, null, nextElement, checkResult);
+        var parentId = result.value.ELEMENT;
+        multipleElements = Element.requiresFiltering(nextElement);
+        elementAction = multipleElements ? 'elementIdElements' : 'elementIdElement';
+        self.protocol[elementAction](parentId, null, nextElement, checkResult);
       } else {
         callback(result);
         self.emit('complete', el, self);

lib/api/protocol.js

@@ -243,7 +243,7 @@ module.exports = function(Nightwatch) {
     return postRequest('/elements', {
         using: elem.locateStrategy,
         value: elem.selector
-      }, callback
+      }, filterElementsForCallback(elem, callback)
     );
   }
 
@@ -264,7 +264,7 @@ module.exports = function(Nightwatch) {
     return postRequest('/element/' + id + '/elements', {
         using: elem.locateStrategy,
         value: elem.selector
-      }, callback
+      }, filterElementsForCallback(elem, callback)
     );
   };
 
@@ -281,6 +281,64 @@ module.exports = function(Nightwatch) {
     }
   }
 
+  /**
+   * Wraps an elements protocol request callback to include logic to select
+   * a subset of elements if that request requires filtering.
+   * 
+   * @param {Object} elem
+   * @param {function} callback
+   * @private
+   */
+  function filterElementsForCallback(elem, callback) {
+    if (!Element.requiresFiltering(elem)) {
+      return callback;
+    }
+
+    return callback && function elementsCallbackWrapper(result) {
+      if (result && result.status === 0) {
+
+        var filtered = Element.applyFiltering(elem, result.value);
+        if (filtered) {
+
+          result.value = filtered;
+
+        } else {
+
+          result.status = -1;
+          result.value = [];
+          var errorId = 'NoSuchElement';
+          var errorInfo = findErrorById(errorId);
+          if (errorInfo) {
+            result.message = errorInfo.message;
+            result.errorStatus = errorInfo.status;
+          }
+        }
+      }
+
+      return callback(result);
+    };
+  }
+
+  /**
+   * Looks up error status info from an id string rather than id number.
+   * 
+   * @param {string} id String id to look up an error with.
+   */
+  function findErrorById(id) {
+    var errorCodes = require('./errors.json');
+    for (var status in errorCodes) {
+      if (errorCodes[status].id === id) {
+        return {
+          status: status,
+          id: id,
+          message: errorCodes[status].message
+        };
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Get the element on the page that currently has focus.
    *

lib/page-object/element.js

@@ -22,19 +22,25 @@ function Element(definition, options) {
 
   this.selector = definition.selector;
   this.locateStrategy = definition.locateStrategy || options.locateStrategy;
+  this.index = definition.index;
   this.parent = options.parent;
 }
 
 Element.prototype.toString = function() {
   if (Array.isArray(this.selector)) { // recursive
     return this.selector.join(',');
   }
+
+  var index = parseInt(this.index, 10);
+  var indexStr = isNaN(index) ? '' : '[' + index + ']';
+
   if (!this.name) { // inline (not defined in page or section)
     return this.selector;
   }
+
   var classType = this.constructor.name;
   var prefix = this.constructor === Element ? '@' : '';
-  return classType + '[name=' + prefix + this.name + ']';
+  return classType + '[name=' + prefix + this.name + indexStr + ']';
 };
 
 /**
@@ -78,7 +84,7 @@ Element.prototype.getRecursiveLookupElement = function () {
  * @param {Object} source The object to capture values from.
  */
 Element.copyDefaults = function(target, source) {
-  var props = ['name', 'parent', 'selector', 'locateStrategy'];
+  var props = ['name', 'parent', 'selector', 'locateStrategy', 'index'];
   props.forEach(function(prop) {
     if (target[prop] === undefined || target[prop] === null) {
       target[prop] = source[prop];
@@ -119,6 +125,48 @@ Element.fromSelector = function(value, using) {
   return new Element(definition, options);
 };
 
+/**
+ * Returns true when an elements() request is needed to capture
+ * the result of the Element definition.  When false, it means the
+ * Element targets the first result the selector match meaning an
+ * element() (single match only) result can be used.
+ * 
+ * @param {Object} element The Element instance to check to see if
+ *    it will apply filtering.
+ */
+Element.requiresFiltering = function(element) {
+
+  var usingIndex = !isNaN(parseInt(element.index, 10));
+  if (usingIndex) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Filters an elements() results array to a more specific set based
+ * on an Element object's definition.
+ * 
+ * @param {Object} element The Element instance to check to see if
+ *    it will apply filtering.
+ * @param {Array} resultElements Array of WebElement JSON objects
+ *    returned from a call to elements() or elementIdElements().
+ * @returns {Array} A filtered version of the elements array or, if
+ *    the filter failed (no matches found) null.
+ */
+Element.applyFiltering = function(element, resultElements) {
+
+  var index = parseInt(element.index, 10);
+  var usingIndex = !isNaN(index);
+  if (usingIndex) {
+    var foundElem = resultElements[index];
+    return foundElem ? [foundElem] : null; // null = not found
+  }
+
+  return resultElements;
+};
+
 /**
  * Gets a simple description of the element based on whether or not
  * it is used as an inline selector in a command call or a definition

lib/page-object/section.js

@@ -7,7 +7,7 @@ var CommandWrapper = require('./command-wrapper.js');
  * Class that all sections subclass from
  *
  * @param {Object} definition User-defined section options defined in page object
- * @param {Object} options Additional options to be given to the element.
+ * @param {Object} options Additional options to be given to the section.
  * @constructor
  */
 function Section(definition, options) {

test/extra/pageobjects/simplePageObj.js

@@ -9,14 +9,20 @@ module.exports = {
   elements: {
     loginAsString: '#weblogin',
     loginCss: { selector: '#weblogin' },
+    loginIndexed: { selector: '#weblogin', index: 1 },
     loginXpath: { selector: '//weblogin', locateStrategy: 'xpath' },
     loginId: { selector: 'weblogin', locateStrategy: 'id' }
   },
   sections: {
     signUp: {
       selector: '#signupSection',
       sections: {
-        getStarted: { selector: '#getStarted' }
+        getStarted: {
+          selector: '#getStarted',
+          elements: {
+            start: { selector: '#getStartedStart' }
+          }
+        }
       },
       elements: {
         help: { selector: '#helpBtn' }

test/lib/nockselements.js

@@ -8,14 +8,14 @@ module.exports = {
   _requestUri: 'http://localhost:10195',
   _protocolUri: '/wd/hub/session/1352110219202/',
 
-  elementFound : function(selector, using) {
+  elementFound : function(selector, using, foundElem) {
     nock(this._requestUri)
       .persist()
       .post(this._protocolUri + 'element', {'using':using || 'css selector','value':selector || '#nock'})
       .reply(200, {
         status: 0,
         state: 'success',
-        value: { ELEMENT: '0' }
+        value: foundElem || { ELEMENT: '0' }
       });
     return this;
   },
@@ -57,14 +57,14 @@ module.exports = {
     return this;
   },
 
-  elementByXpath : function(selector) {
+  elementByXpath : function(selector, foundElem) {
     nock(this._requestUri)
       .persist()
       .post(this._protocolUri + 'element', {'using':'xpath','value':selector || '//[@id="nock"]'})
       .reply(200, {
         status: 0,
         state: 'success',
-        value: { ELEMENT: '0' }
+        value: foundElem || { ELEMENT: '0' }
       });
     return this;
   },
@@ -81,15 +81,15 @@ module.exports = {
     return this;
   },
 
-  elementId : function (id, selector, using) {
+  elementId : function (id, selector, using, foundElem) {
     nock(this._requestUri)
       .persist()
       .post(this._protocolUri + 'element/' + (id || 0) + '/element',
         {'using':using || 'css selector','value':selector || '#nock'})
       .reply(200, {
         status: 0,
         state : 'success',
-        value: { ELEMENT: '0' }
+        value: foundElem || { ELEMENT: '0' }
       });
     return this;
   },