@cypress/unique-selector 1.1.0 → 2.0.0

package/lib/getAttribute.js

@@ -1,33 +1,26 @@
-"use strict";
+'use strict';
 
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 /**
  * Returns the {attr} selector of the element
- * @param  { String } selectorType - The attribute selector to return.
- * @param  { String } attributes - The attributes of the element.
+ * @param  { Element } el - The element.
+ * @param  { String } attribute - The attribute name.
+ * @param { Function } filter
  * @return { String | null } - The {attr} selector of the element.
  */
+var getAttributeSelector = exports.getAttributeSelector = function getAttributeSelector(el, attribute, filter) {
+  var attributeValue = el.getAttribute(attribute);
 
-var getAttribute = exports.getAttribute = function getAttribute(selectorType, attributes) {
-  for (var i = 0; i < attributes.length; i++) {
-    // extract node name + value
-    var _attributes$i = attributes[i],
-        nodeName = _attributes$i.nodeName,
-        value = _attributes$i.value;
-
-    // if this matches our selector
-
-    if (nodeName === selectorType) {
-      if (value) {
-        // if we have value that needs quotes
-        return "[" + nodeName + "=\"" + value + "\"]";
-      }
+  if (attributeValue === null || filter && !filter('attribute', attribute, attributeValue)) {
+    return null;
+  }
 
-      return "[" + nodeName + "]";
-    }
+  if (attributeValue) {
+    // if we have value that needs quotes
+    return '[' + attribute + '="' + attributeValue + '"]';
   }
 
-  return null;
+  return '[' + attribute + ']';
 };

package/lib/getAttributes.js

@@ -9,18 +9,20 @@ function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr
 
 /**
  * Returns the Attribute selectors of the element
- * @param  { DOM Element } element
+ * @param  { Element } element
  * @param  { Array } array of attributes to ignore
+ * @param { Function } filter
  * @return { Array }
  */
 function getAttributes(el) {
   var attributesToIgnore = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : ['id', 'class', 'length'];
+  var filter = arguments[2];
   var attributes = el.attributes;
 
   var attrs = [].concat(_toConsumableArray(attributes));
 
   return attrs.reduce(function (sum, next) {
-    if (!(attributesToIgnore.indexOf(next.nodeName) > -1)) {
+    if (!(attributesToIgnore.indexOf(next.nodeName) > -1) && (!filter || filter('attribute', next.nodeName, next.value))) {
       sum.push('[' + next.nodeName + '="' + next.value + '"]');
     }
     return sum;

package/lib/getClasses.js

@@ -11,34 +11,40 @@ require('css.escape');
 /**
  * Get class names for an element
  *
- * @pararm { Element } el
+ * @param { Element } el
+ * @param { Function } filter
  * @return { Array }
  */
-function getClasses(el) {
+function getClasses(el, filter) {
   if (!el.hasAttribute('class')) {
     return [];
   }
 
   try {
-    return Array.prototype.slice.call(el.classList);
+    return Array.prototype.slice.call(el.classList).filter(function (cls) {
+      return !filter || filter('attribute', 'class', cls);
+    });
   } catch (e) {
     var className = el.getAttribute('class');
 
     // remove duplicate and leading/trailing whitespaces
-    className = className.trim().replace(/\s+/g, ' ');
+    className = className.trim();
 
-    // split into separate classnames
-    return className.split(' ');
+    // split into separate classnames, perform filtering
+    return className.split(/\s+/g).filter(function (cls) {
+      return !filter || filter('class', 'class', cls);
+    });
   }
 }
 
 /**
  * Returns the Class selectors of the element
  * @param  { Object } element
+ * @param { Function } filter
  * @return { Array }
  */
-function getClassSelectors(el) {
-  var classList = getClasses(el).filter(Boolean);
+function getClassSelectors(el, filter) {
+  var classList = getClasses(el, filter).filter(Boolean);
   return classList.map(function (cl) {
     return '.' + CSS.escape(cl);
   });

package/lib/getID.js

@@ -10,12 +10,13 @@ require('css.escape');
 /**
  * Returns the Tag of the element
  * @param  { Object } element
+ * @param { Function } filter
  * @return { String }
  */
-function getID(el) {
+function getID(el, filter) {
   var id = el.getAttribute('id');
 
-  if (id !== null && id !== '') {
+  if (id !== null && id !== '' && (!filter || filter('attribute', 'id', id))) {
     return '#' + CSS.escape(id);
   }
   return null;

package/lib/getName.js

@@ -7,12 +7,13 @@ exports.getName = getName;
 /**
  * Returns the `name` attribute of the element (if one exists)
  * @param  { Object } element
+ * @param { Function } filter
  * @return { String }
  */
-function getName(el) {
+function getName(el, filter) {
   var name = el.getAttribute('name');
 
-  if (name !== null && name !== '') {
+  if (name !== null && name !== '' && (!filter || filter('attribute', 'name', name))) {
     return '[name="' + name + '"]';
   }
   return null;

package/lib/getNthChild.js

@@ -10,9 +10,10 @@ var _isElement = require('./isElement');
 /**
  * Returns the selectors based on the position of the element relative to its siblings
  * @param  { Object } element
+ * @param { Function } filter
  * @return { Array }
  */
-function getNthChild(element) {
+function getNthChild(element, filter) {
   var counter = 0;
   var k = void 0;
   var sibling = void 0;
@@ -27,7 +28,7 @@ function getNthChild(element) {
       sibling = childNodes[k];
       if ((0, _isElement.isElement)(sibling)) {
         counter++;
-        if (sibling === element) {
+        if (sibling === element && (!filter || filter('nth-child', 'nth-child', counter))) {
           return ':nth-child(' + counter + ')';
         }
       }

package/lib/getTag.js

@@ -7,8 +7,15 @@ exports.getTag = getTag;
 /**
  * Returns the Tag of the element
  * @param  { Object } element
+ * @param { Function } filter
  * @return { String }
  */
-function getTag(el) {
-  return el.tagName.toLowerCase().replace(/:/g, '\\:');
+function getTag(el, filter) {
+  var tagName = el.tagName.toLowerCase().replace(/:/g, '\\:');
+
+  if (filter && !filter('tag', 'tag', tagName)) {
+    return null;
+  }
+
+  return tagName;
 }

package/lib/index.js

@@ -32,26 +32,76 @@ function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr
 var dataRegex = /^data-.+/;
 var attrRegex = /^attribute:(.+)/m;
 
+/**
+ * @typedef Filter
+ * @type {Function}
+ * @param {string} type - the trait being considered ('attribute', 'tag', 'nth-child').
+ * @param {string} key - your trait key (for 'attribute' will be the attribute name, for others will typically be the same as 'type').
+ * @param {string} value - the trait value.
+ * @returns {boolean} whether this trait can be used when building the selector (true = allow). Defaults to 'true' if no value returned.
+ */
+
 /**
  * Returns all the selectors of the element
  * @param  { Object } element
  * @return { Object }
  */
-function getAllSelectors(el, selectors, attributesToIgnore) {
+function getAllSelectors(el, selectors, attributesToIgnore, filter) {
+  var consolidatedAttributesToIgnore = [].concat(_toConsumableArray(attributesToIgnore));
+  var nonAttributeSelectors = [];
+  var _iteratorNormalCompletion = true;
+  var _didIteratorError = false;
+  var _iteratorError = undefined;
+
+  try {
+    for (var _iterator = selectors[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+      var selectorType = _step.value;
+
+      if (dataRegex.test(selectorType)) {
+        consolidatedAttributesToIgnore.push(selectorType);
+      } else if (attrRegex.test(selectorType)) {
+        consolidatedAttributesToIgnore.push(selectorType.replace(attrRegex, '$1'));
+      } else {
+        nonAttributeSelectors.push(selectorType);
+      }
+    }
+  } catch (err) {
+    _didIteratorError = true;
+    _iteratorError = err;
+  } finally {
+    try {
+      if (!_iteratorNormalCompletion && _iterator.return) {
+        _iterator.return();
+      }
+    } finally {
+      if (_didIteratorError) {
+        throw _iteratorError;
+      }
+    }
+  }
+
   var funcs = {
-    'tag': _getTag.getTag,
-    'nth-child': _getNthChild.getNthChild,
+    'tag': function tag(elem) {
+      return (0, _getTag.getTag)(elem, filter);
+    },
+    'nth-child': function nthChild(elem) {
+      return (0, _getNthChild.getNthChild)(elem, filter);
+    },
     'attributes': function attributes(elem) {
-      return (0, _getAttributes.getAttributes)(elem, attributesToIgnore);
+      return (0, _getAttributes.getAttributes)(elem, consolidatedAttributesToIgnore, filter);
     },
-    'class': _getClasses.getClassSelectors,
-    'id': _getID.getID,
-    'name': _getName.getName
+    'class': function _class(elem) {
+      return (0, _getClasses.getClassSelectors)(elem, filter);
+    },
+    'id': function id(elem) {
+      return (0, _getID.getID)(elem, filter);
+    },
+    'name': function name(elem) {
+      return (0, _getName.getName)(elem, filter);
+    }
   };
 
-  return selectors.filter(function (selector) {
-    return !dataRegex.test(selector) && !attrRegex.test(selector);
-  }).reduce(function (res, next) {
+  return nonAttributeSelectors.reduce(function (res, next) {
     res[next] = funcs[next](el);
     return res;
   }, {});
@@ -119,20 +169,18 @@ function getUniqueCombination(element, items, tag) {
  * @param  { Array } options
  * @return { String }
  */
-function getUniqueSelector(element, selectorTypes, attributesToIgnore) {
+function getUniqueSelector(element, selectorTypes, attributesToIgnore, filter) {
   var foundSelector = void 0;
 
-  var attributes = [].concat(_toConsumableArray(element.attributes));
+  var elementSelectors = getAllSelectors(element, selectorTypes, attributesToIgnore, filter);
 
-  var elementSelectors = getAllSelectors(element, selectorTypes, attributesToIgnore);
-
-  var _iteratorNormalCompletion = true;
-  var _didIteratorError = false;
-  var _iteratorError = undefined;
+  var _iteratorNormalCompletion2 = true;
+  var _didIteratorError2 = false;
+  var _iteratorError2 = undefined;
 
   try {
-    for (var _iterator = selectorTypes[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
-      var selectorType = _step.value;
+    for (var _iterator2 = selectorTypes[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true) {
+      var selectorType = _step2.value;
 
       var selector = elementSelectors[selectorType];
 
@@ -141,8 +189,7 @@ function getUniqueSelector(element, selectorTypes, attributesToIgnore) {
       var isAttributeSelectorType = !isDataAttributeSelectorType && attrRegex.test(selectorType);
       if (isDataAttributeSelectorType || isAttributeSelectorType) {
         var attributeToQuery = isDataAttributeSelectorType ? selectorType : selectorType.replace(attrRegex, '$1');
-        var attributeSelector = (0, _getAttribute.getAttribute)(attributeToQuery, attributes);
-
+        var attributeSelector = (0, _getAttribute.getAttributeSelector)(element, attributeToQuery, filter);
         // if we found a selector via attribute
         if (attributeSelector) {
           selector = attributeSelector;
@@ -179,16 +226,16 @@ function getUniqueSelector(element, selectorTypes, attributesToIgnore) {
       }
     }
   } catch (err) {
-    _didIteratorError = true;
-    _iteratorError = err;
+    _didIteratorError2 = true;
+    _iteratorError2 = err;
   } finally {
     try {
-      if (!_iteratorNormalCompletion && _iterator.return) {
-        _iterator.return();
+      if (!_iteratorNormalCompletion2 && _iterator2.return) {
+        _iterator2.return();
       }
     } finally {
-      if (_didIteratorError) {
-        throw _iteratorError;
+      if (_didIteratorError2) {
+        throw _iteratorError2;
       }
     }
   }
@@ -200,6 +247,12 @@ function getUniqueSelector(element, selectorTypes, attributesToIgnore) {
  * Generate unique CSS selector for given DOM element
  *
  * @param {Element} el
+ * @param {Object} options (optional) Customize various behaviors of selector generation
+ * @param {String[]} options.selectorTypes Specify the set of traits to leverage when building selectors in precedence order
+ * @param {String[]} options.attributesToIgnore Specify a set of attributes to *not* leverage when building selectors
+ * @param {Filter} options.filter Provide a filter function to conditionally reject various traits when building selectors.
+ * @param {Map<Element, String>} options.selectorCache Provide a cache to improve performance of repeated selector generation - it is the responsibility of the caller to handle cache invalidation. Caching is performed using the input Element as key. This cache handles Element -> Selector caching.
+ * @param {Map<String, Boolean>} options.isUniqueCache Provide a cache to improve performance of repeated selector generation - it is the responsibility of the caller to handle cache invalidation. Caching is performed using the input Element as key. This cache handles Selector -> isUnique caching.
  * @return {String}
  * @api private
  */
@@ -210,9 +263,18 @@ function unique(el) {
       selectorTypes = _options$selectorType === undefined ? ['id', 'name', 'class', 'tag', 'nth-child'] : _options$selectorType,
       _options$attributesTo = options.attributesToIgnore,
       attributesToIgnore = _options$attributesTo === undefined ? ['id', 'class', 'length'] : _options$attributesTo,
+      filter = options.filter,
       selectorCache = options.selectorCache,
       isUniqueCache = options.isUniqueCache;
+  // If filter was provided wrap it to ensure a default value of `true` is returned if the provided function fails to return a value
 
+  var normalizedFilter = filter && function (type, key, value) {
+    var result = filter(type, key, value);
+    if (result === null || result === undefined) {
+      return true;
+    }
+    return result;
+  };
   var allSelectors = [];
 
   var currentElement = el;
@@ -220,7 +282,7 @@ function unique(el) {
     var selector = selectorCache ? selectorCache.get(currentElement) : undefined;
 
     if (!selector) {
-      selector = getUniqueSelector(currentElement, selectorTypes, attributesToIgnore);
+      selector = getUniqueSelector(currentElement, selectorTypes, attributesToIgnore, normalizedFilter);
       if (selectorCache) {
         selectorCache.set(currentElement, selector);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cypress/unique-selector",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Given a DOM node, return a unique CSS selector matching only that element",
   "main": "./lib/index.js",
   "jsnext:main": "./src/index.js",