Fixes nightwatchjs#1115 - Adds support for object-based selectors in page elements format

Author: senocular

lib/api/element-commands.js

@@ -2,6 +2,7 @@ var util = require('util');
 var events = require('events');
 var Logger = require('../util/logger.js');
 var Utils = require('../util/utils.js');
+var Element = require('../page-object/element.js');
 
 module.exports = function(client) {
   var Protocol = require('./protocol.js')(client);
@@ -341,10 +342,36 @@ module.exports = function(client) {
     events.EventEmitter.call(this);
 
     var $this = this;
-    var el = Protocol.element(using, value, function(result) {
+
+    // element commands support a single element but we use elements() to capture
+    // a full list of matching elements for the selector so that we can support
+    // the use of element.index if available.  If no index is used, the first
+    // element is matched
+
+    var el = Protocol.elements(using, value, function(result) {
+
+      // if the request was successful but no elements were returned, that's an error
+      // since we expect at least one to exist, so we change the status to failing.
+
+      if (result.status === 0 && result.value.length === 0) {
+        result.status = -1;
+      }
+
       if (result.status !== 0) {
+
         callback.call(client.api, result);
-        var errorMessage = 'ERROR: Unable to locate element: "' + value + '" using: ' + using;
+
+        var elem = Element.fromSelector(value, using);
+        var errorMessage = 'ERROR: Unable to locate element: "' + elem.selector + '" using: "' + elem.locateStrategy + '"';
+
+        // when an index is specified, include it in the error message
+        // but ignore it otherwise since its optional and only extra
+        // noise if not used
+
+        if (elem.index != undefined) {
+          errorMessage += ' at index: ' + elem.index;
+        }
+
         var stack = originalStackTrace.split('\n');
 
         stack.shift();
@@ -354,8 +381,14 @@ module.exports = function(client) {
         client.errors.push(errorMessage + '\n' + stack.join('\n'));
 
         $this.emit('complete', el, $this);
+
       } else {
-        result = result.value.ELEMENT;
+
+        // we only care about the first element. If an index was used, it would
+        // have already been applied to the result and first element ([0])
+        // would be that element
+
+        result = result.value[0].ELEMENT;
 
         args.push(function(r) {
           callback.call(client.api, r);

lib/api/element-commands/_elementByRecursion.js

@@ -8,7 +8,6 @@ var events = require('events');
  * @param {function} [callback] Optional callback function to be called when the command finishes.
  * @api protocol
  */
-
 function ElementByRecursion(client) {
   events.EventEmitter.call(this);
   this.protocol = require('../protocol.js')(client);
@@ -18,18 +17,23 @@ util.inherits(ElementByRecursion, events.EventEmitter);
 
 ElementByRecursion.prototype.command = function(elements, callback) {
   var self = this;
-  var allElements = elements.slice();
 
+  var allElements = elements.slice();
   var topElement = allElements.shift();
-  var el = this.protocol.element(topElement.locateStrategy, topElement.selector, function checkResult(result) {
+
+  // since we're dealing with an array of element objects the using
+  // parameter (null) in the protocol commands is redundant since
+  // its already encoded in the element object (topElement)
+
+  var el = this.protocol.element(null, topElement, function checkResult(result) {
     if (result.status !== 0) {
       callback(result);
       self.emit('complete', el, self);
     } else {
       var nextElement = allElements.shift();
       var parentId = result.value.ELEMENT;
       if (nextElement) {
-        self.protocol.elementIdElement(parentId, nextElement.locateStrategy, nextElement.selector, checkResult);
+        self.protocol.elementIdElement(parentId, null, nextElement, checkResult);
       } else {
         callback(result);
         self.emit('complete', el, self);

lib/api/element-commands/_elementsByRecursion.js

@@ -9,7 +9,6 @@ var Q = require('q');
  * @param {function} [callback] Optional callback function to be called when the command finishes.
  * @api protocol
  */
-
 function ElementsByRecursion(client) {
   events.EventEmitter.call(this);
   this.protocol = require('../protocol.js')(client);
@@ -65,7 +64,11 @@ ElementsByRecursion.prototype.command = function(elements, callback) {
   var allElements = elements.slice();
   var topElement = allElements.shift();
 
-  var el = this.protocol.elements(topElement.locateStrategy, topElement.selector, function checkResult() {
+  // since we're dealing with an array of element objects the using
+  // parameter (null) in the protocol commands is redundant since
+  // its already encoded in the element object (topElement)
+
+  var el = this.protocol.elements(null, topElement, function checkResult() {
     var result = aggregateResults(arguments);
     if (result.value.length === 0) {
       callback(result);
@@ -77,7 +80,7 @@ ElementsByRecursion.prototype.command = function(elements, callback) {
     if (nextElement) {
       var promises = [];
       result.value.forEach(function(el) {
-        var p = deferredElementIdElements(el.ELEMENT, nextElement.locateStrategy, nextElement.selector, checkResult);
+        var p = deferredElementIdElements(el.ELEMENT, null, nextElement, checkResult);
         promises.push(p);
       });
 

lib/api/element-commands/_waitForElement.js

@@ -204,7 +204,7 @@ WaitForElement.prototype.checkElement = function() {
   this.getProtocolCommand(function(result) {
     var now = new Date().getTime();
 
-    if (result.value && result.value.length > 0) {
+    if (result.status === 0 && result.value && result.value.length > 0) {
       if (result.value.length > 1) {
         var message = 'WaitForElement found ' + result.value.length + ' elements for selector "' + self.selector + '".';
         if (self.throwOnMultipleElementsReturned) {

lib/api/expect/_baseAssertion.js

@@ -208,7 +208,16 @@ BaseAssertion.prototype.scheduleRetry = function() {
 };
 
 BaseAssertion.prototype.formatMessage = function() {
-  this.message = Utils.format(this.message || this.message, this.selector);
+
+  // selector may be a simple string or an object. If an
+  // object, show a more meaningful string representation
+
+  var selectorStr = String(this.selector);
+  if (selectorStr === '[object Object]') {
+    selectorStr = JSON.stringify(this.selector);
+  }
+
+  this.message = Utils.format(this.message, selectorStr);
   this.message += this.messageParts.join('');
 };
 

lib/api/protocol.js

@@ -1,5 +1,6 @@
 var elementByRecursion = require('./element-commands/_elementByRecursion.js');
 var elementsByRecursion = require('./element-commands/_elementsByRecursion.js');
+var Element = require('../page-object/element.js');
 
 module.exports = function(Nightwatch) {
 
@@ -164,35 +165,35 @@ module.exports = function(Nightwatch) {
    * @api protocol
    */
   Actions.element = function(using, value, callback) {
-    if (using == 'recursion') {
-      return new elementByRecursion(Nightwatch).command(value, callback);
+
+    var elem = Element.fromSelector(value, using);
+
+    if (elem.locateStrategy == 'recursion') {
+
+      // when using recursion, the selector of the element is an
+      // array of elements which each need to individually
+      // and sequentially get resolved on top of each other
+
+      return new elementByRecursion(Nightwatch).command(elem.selector, callback);
     }
 
-    return element(using, value, callback);
+    return element(elem, callback);
   };
 
   /*!
    * element protocol action
    *
-   * @param {string} using
-   * @param {string} value
+   * @param {Object} elem
    * @param {function} callback
    * @private
    */
-  function element(using, value, callback) {
-    var strategies = ['class name', 'css selector', 'id', 'name', 'link text',
-      'partial link text', 'tag name', 'xpath'];
-    using = using.toLocaleLowerCase();
+  function element(elem, callback) {
 
-    if (strategies.indexOf(using) === -1) {
-      throw new Error('Provided locating strategy is not supported: ' +
-        using + '. It must be one of the following:\n' +
-        strategies.join(', '));
-    }
+    validateStrategy(elem.locateStrategy);
 
     return postRequest('/element', {
-      using: using,
-      value: value
+      using: elem.locateStrategy,
+      value: elem.selector
     }, callback);
   }
 
@@ -207,19 +208,14 @@ module.exports = function(Nightwatch) {
    * @api protocol
    */
   Actions.elementIdElement = function(id, using, value, callback) {
-    var strategies = ['class name', 'css selector', 'id', 'name', 'link text',
-      'partial link text', 'tag name', 'xpath'];
-    using = using.toLocaleLowerCase();
 
-    if (strategies.indexOf(using) === -1) {
-      throw new Error('Provided locating strategy is not supported: ' +
-        using + '. It must be one of the following:\n' +
-        strategies.join(', '));
-    }
+    var elem = Element.fromSelector(value, using);
+
+    validateStrategy(elem.locateStrategy);
 
     return postRequest('/element/' + id + '/element', {
-      using: using,
-      value: value
+      using: elem.locateStrategy,
+      value: elem.selector
     }, callback);
   };
 
@@ -234,32 +230,37 @@ module.exports = function(Nightwatch) {
    * @api protocol
    */
   Actions.elements = function(using, value, callback) {
-    if (using == 'recursion') {
-      return new elementsByRecursion(Nightwatch).command(value, callback);
+
+    var elem = Element.fromSelector(value, using);
+
+    if (elem.locateStrategy == 'recursion') {
+
+      // when using recursion, the selector of the element is an
+      // array of elements which each need to individually
+      // and sequentially get resolved on top of each other
+
+      return new elementsByRecursion(Nightwatch).command(elem.selector, callback);
     }
 
-    return elements(using, value, callback);
+    return elements(elem, callback);
   };
 
   /*!
    * elements protocol action
    *
-   * @param {string} using
-   * @param {string} value
+   * @param {Object} elem
    * @param {function} callback
    * @private
    */
-  function elements(using, value, callback) {
-    var check = /class name|css selector|id|name|link text|partial link text|tag name|xpath/gi;
-    if (!check.test(using)) {
-      throw new Error('Please provide any of the following using strings as the first parameter: ' +
-        'class name, css selector, id, name, link text, partial link text, tag name, or xpath. Given: ' + using);
-    }
+  function elements(elem, callback) {
+
+    validateStrategy(elem.locateStrategy);
 
     return postRequest('/elements', {
-      using: using,
-      value: value
-    }, callback);
+        using: elem.locateStrategy,
+        value: elem.selector
+      }, createIndexedElementCallback(elem, callback)
+    );
   }
 
   /**
@@ -273,21 +274,89 @@ module.exports = function(Nightwatch) {
    * @api protocol
    */
   Actions.elementIdElements = function(id, using, value, callback) {
+
+    var elem = Element.fromSelector(value, using);
+
+    validateStrategy(elem.locateStrategy);
+
+    return postRequest('/element/' + id + '/elements', {
+        using: elem.locateStrategy,
+        value: elem.selector
+      }, createIndexedElementCallback(elem, callback)
+    );
+  };
+
+  /**
+   * Wraps an elements protocol request callback to include logic to select
+   * a single element with an index if one was specified.
+   * @param {Object} elem
+   * @param {function} callback
+   * @private
+   */
+  function createIndexedElementCallback(elem, callback) {
+    return function (result) {
+
+      var usingIndex = elem.index != undefined;
+      if (usingIndex && result && result.status === 0) {
+
+        // if an element index is specified, we need to make sure its
+        // within the range of elements found. If not, we patch the
+        // result to show a failure
+
+        if (result.value.length <= elem.index) {
+
+          result.status = -1;
+
+          var errorId = 'NoSuchElement';
+          var errorInfo = errorById(errorId);
+          if (errorInfo) {
+            result.message = errorInfo.message;
+            result.errorStatus = errorInfo.status;
+          }
+
+        } else {
+
+          // with a valid element index, make the results that element
+          // as the first and only result
+
+          result.value = [result.value[elem.index]];
+        }
+      }
+
+      return callback(result);
+    };
+  }
+
+  /**
+   * Looks up error status info from an id string rather than id number
+   */
+  function errorById(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;
+  }
+
+  function validateStrategy(using) {
+
+    var usingLow = String(using).toLocaleLowerCase();
     var strategies = ['class name', 'css selector', 'id', 'name', 'link text',
       'partial link text', 'tag name', 'xpath'];
-    using = using.toLocaleLowerCase();
 
-    if (strategies.indexOf(using) === -1) {
+    if (strategies.indexOf(usingLow) === -1) {
       throw new Error('Provided locating strategy is not supported: ' +
         using + '. It must be one of the following:\n' +
         strategies.join(', '));
     }
-
-    return postRequest('/element/' + id + '/elements', {
-      using: using,
-      value: value
-    }, callback);
-  };
+  }
 
   /**
    * Get the element on the page that currently has focus.

lib/core/queue.js

@@ -158,6 +158,7 @@ AsyncTree.prototype.runCommand = function(node, callback) {
     }
     return node.context;
   } catch (err) {
+    err.originalStack = err.stack;
     err.stack = node.stackTrace;
     err.name = 'Error while running ' + node.name + ' command';
     this.emit('error', err);