@cypress/unique-selector 2.1.2 → 2.2.0

package/README.md

@@ -56,6 +56,32 @@ Generates a unique CSS selector for the given DOM element.
 
 - **`isUniqueCache`** (Map<String, Boolean>, optional) - Cache to improve performance of repeated uniqueness checks. The caller is responsible for cache invalidation.
 
+- **`requiredAttributes`** (Object, optional) - Specifies attributes that must appear in the generated selector regardless of whether they are needed for uniqueness. When provided, matching attribute selectors are woven into every element's segment of the `>` chain, and ancestors above the unique chain are prepended using descendant combinators.
+
+  This option takes precedence over `selectorTypes` and `filter` for the attributes it names — if an element has a required attribute, its `[attr="value"]` selector will appear in the output even if `filter` would reject that attribute for uniqueness purposes, and even if the attribute is not listed in `selectorTypes`.
+
+  The `requiredAttributes` object has the following shape:
+
+  - **`attributeNames`** (String[]) - The attribute names to inject into the selector (e.g., `['data-component', 'data-cy']`). Exact attribute names only — not patterns or regexes. Names are used as-provided in the generated selector with no internal normalization, so the casing you supply is the casing that appears in the output. When an attribute in `attributeNames` is already present in the base selector (from `selectorTypes`), dedup detection is case-insensitive, so duplicate injection is correctly suppressed regardless of case differences.
+  - **`filter`** (Function, optional) - A filter function with the same signature as the top-level `filter` option, applied independently to control which attribute _values_ are allowed to be injected. Return `false` to skip injection for a given element. This filter is separate from the top-level `filter` and serves a different purpose: the top-level `filter` controls which traits are eligible for building a _unique_ selector, while `requiredAttributes.filter` controls which attribute values are eligible for _injection_. The `key` argument passed to this function will match the casing of the name as provided in `attributeNames`.
+  - **`elementCache`** (Map<Element, (string|null)[]>, optional) - Cache for per-element required attribute selectors. Each cached entry is an array of individual selector strings parallel to `attributeNames` (null for attributes not present or filtered out). The caller is responsible for cache invalidation.
+
+  ```javascript
+  unique(element, {
+    requiredAttributes: {
+      attributeNames: ['data-component', 'data-cy'],
+      filter: (type, key, value) => {
+        // Exclude auto-generated component names from injection
+        if (type === 'attribute' && key === 'data-component') {
+          return !value.startsWith('jss-');
+        }
+        return true;
+      },
+      elementCache: new Map(),
+    }
+  });
+  ```
+
 #### Returns
 
 - **String** - A unique CSS selector for the element, or `null` if no unique selector can be generated
@@ -118,6 +144,68 @@ const selector = unique(element, {
 });
 ```
 
+### Required Attributes
+
+Use `requiredAttributes` when you want specific attributes to always appear in the generated selector, regardless of whether they contribute to uniqueness. This is useful when your application uses semantic component attributes (e.g., `data-component`, `data-cy`) that you want reflected in every selector for readability or stability.
+
+```javascript
+// Always include data-component in the selector, even when an ID alone would be unique
+const selector = unique(element, {
+    requiredAttributes: {
+        attributeNames: ['data-component']
+    }
+});
+// '#submit-button' becomes '#submit-button[data-component="PrimaryButton"]'
+// Ancestors with data-component are prepended with descendant combinators:
+// '[data-component="Form"] #submit-button[data-component="PrimaryButton"]'
+```
+
+Required attributes take precedence over `selectorTypes` and `filter`. If an element has a required attribute, it will be injected into the selector even if:
+- The attribute is not listed in `selectorTypes`
+- The top-level `filter` would reject that attribute for uniqueness purposes
+
+```javascript
+// The top-level filter rejects data-component for uniqueness building,
+// but requiredAttributes.filter allows it to still be injected.
+const selector = unique(element, {
+    filter: (type, key) => key !== 'data-component',
+    requiredAttributes: {
+        attributeNames: ['data-component'],
+        // No requiredAttributes.filter — all values are injected
+    }
+});
+// data-component still appears in the output
+```
+
+Use `requiredAttributes.filter` independently to control which attribute _values_ get injected, without affecting how uniqueness is determined:
+
+```javascript
+// Inject data-component only when the value doesn't look auto-generated
+const selector = unique(element, {
+    requiredAttributes: {
+        attributeNames: ['data-component'],
+        filter: (type, key, value) => {
+            if (type === 'attribute' && key === 'data-component') {
+                return !value.startsWith('jss-');
+            }
+            return true;
+        },
+        elementCache: new Map(), // reuse across calls for performance
+    }
+});
+```
+
+When multiple `attributeNames` are specified, each is matched independently on every element:
+
+```javascript
+const selector = unique(element, {
+    requiredAttributes: {
+        attributeNames: ['data-cy', 'data-region']
+    }
+});
+// '[data-region="main"] [data-cy="dashboard"] .widget[data-cy="widget-a"]'
+```
+
 ### Performance Optimization with Caching
 
 ```javascript
@@ -157,6 +245,7 @@ The library follows this strategy to generate unique selectors:
 3. **Selector type precedence**: Uses the `selectorTypes` array to determine which selector types to try first
 4. **Combination fallback**: For classes and attributes, tries combinations of multiple selectors if single selectors aren't unique
 5. **Nth-child fallback**: Uses nth-child positioning as a last resort
+6. **Required attribute injection**: After the unique `>` chain is determined, any `requiredAttributes` are woven into each element's segment of the chain. Ancestors above the chain that carry a required attribute are prepended as descendant combinators. Required attributes are injected even when they are not needed for uniqueness and even when the top-level `filter` would exclude them from consideration.
 
 ## Examples of Generated Selectors
 

package/lib/getAttribute.js

@@ -3,6 +3,10 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.getAttributeSelector = undefined;
+
+var _utils = require('./utils');
+
 /**
  * Returns the {attr} selector of the element
  * @param  { Element } el - The element.
@@ -19,7 +23,7 @@ var getAttributeSelector = exports.getAttributeSelector = function getAttributeS
 
   if (attributeValue) {
     // if we have value that needs quotes
-    return '[' + attribute + '="' + attributeValue + '"]';
+    return '[' + attribute + '="' + (0, _utils.escapeAttributeValue)(attributeValue) + '"]';
   }
 
   return '[' + attribute + ']';

package/lib/getAttributes.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.getAttributes = getAttributes;
 
+var _utils = require('./utils');
+
 function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } else { return Array.from(arr); } }
 
 /**
@@ -23,7 +25,7 @@ function getAttributes(el) {
 
   return attrs.reduce(function (sum, next) {
     if (!(attributesToIgnore.indexOf(next.nodeName) > -1) && (!filter || filter('attribute', next.nodeName, next.value))) {
-      sum.push('[' + next.nodeName + '="' + next.value + '"]');
+      sum.push('[' + next.nodeName + '="' + (0, _utils.escapeAttributeValue)(next.value) + '"]');
     }
     return sum;
   }, []);

package/lib/getName.js

@@ -4,6 +4,9 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.getName = getName;
+
+var _utils = require('./utils');
+
 /**
  * Returns the `name` attribute of the element (if one exists)
  * @param  { Object } element
@@ -14,7 +17,7 @@ function getName(el, filter) {
   var name = el.getAttribute('name');
 
   if (name !== null && name !== '' && (!filter || filter('attribute', 'name', name))) {
-    return '[name="' + name + '"]';
+    return '[name="' + (0, _utils.escapeAttributeValue)(name) + '"]';
   }
   return null;
 }

package/lib/index.js

@@ -27,6 +27,8 @@ var _getAttribute = require('./getAttribute');
 
 var _isShadowRoot = require('./isShadowRoot');
 
+var _utils = require('./utils');
+
 function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr2 = Array(arr.length); i < arr.length; i++) { arr2[i] = arr[i]; } return arr2; } else { return Array.from(arr); } } /**
                                                                                                                                                                                                      * Expose `unique`
                                                                                                                                                                                                      */
@@ -34,6 +36,70 @@ function _toConsumableArray(arr) { if (Array.isArray(arr)) { for (var i = 0, arr
 var dataRegex = /^data-.+/;
 var attrRegex = /^attribute:(.+)/m;
 
+/**
+ * @typedef CompiledRequiredAttr
+ * @property { string } attributeName - The DOM attribute name (e.g. 'data-cy')
+ * @property { RegExp } dedupPattern - Matches `[attrName=` or `[attrName]` in a selector string to detect existing usage.
+ *   Case-insensitive so it catches any casing the base selector builder may have used for the attribute name.
+ */
+
+/**
+ * Returns per-attribute selector strings for all required attributes on an element.
+ * Each entry in the returned array corresponds to the same-index entry in compiledAttrs:
+ * a `[attr="value"]` string if the attribute is present and passes the filter, otherwise null.
+ * @param { Element } el
+ * @param { CompiledRequiredAttr[] } compiledAttrs
+ * @param { Function | undefined } filter
+ * @return { (string|null)[] }
+ */
+function getPerAttrSelectors(el, compiledAttrs, filter) {
+  return compiledAttrs.map(function (_ref) {
+    var attributeName = _ref.attributeName;
+
+    var attrValue = el.getAttribute(attributeName);
+    if (attrValue === null) return null;
+    if (filter && !filter('attribute', attributeName, attrValue)) return null;
+    return attrValue ? '[' + attributeName + '="' + (0, _utils.escapeAttributeValue)(attrValue) + '"]' : '[' + attributeName + ']';
+  });
+}
+
+/**
+ * Returns per-attribute selectors for an element, using the cache when available.
+ * @param { Element } el
+ * @param { CompiledRequiredAttr[] } compiledAttrs
+ * @param { Function | undefined } filter
+ * @param { Map<Element, (string|null)[]> | undefined } cache
+ * @return { (string|null)[] }
+ */
+function getCachedPerAttrSelectors(el, compiledAttrs, filter, cache) {
+  if (cache && cache.has(el)) return cache.get(el);
+  var selectors = getPerAttrSelectors(el, compiledAttrs, filter);
+  if (cache) cache.set(el, selectors);
+  return selectors;
+}
+
+/**
+ * Merges required attribute selectors into an element's base selector, placing them
+ * before any :nth-child pseudo-class. Attributes already present in the base selector
+ * are excluded from injection via a case-insensitive dedupPattern check.
+ * @param { String } selector - A single element's selector (no combinators)
+ * @param { (string|null)[] } perAttrSelectors - Per-attribute selector strings parallel to compiledAttrs
+ * @param { CompiledRequiredAttr[] } compiledAttrs
+ * @return { String }
+ */
+function insertRequiredAttrIntoSelector(selector, perAttrSelectors, compiledAttrs) {
+  var toInject = perAttrSelectors.filter(function (s, i) {
+    return s !== null && !compiledAttrs[i].dedupPattern.test(selector);
+  }).join('');
+  if (!toInject) return selector;
+  // Insert before :nth-child so the attribute qualifier binds to the element tag/class
+  var nthChildIndex = selector.indexOf(':nth-child');
+  if (nthChildIndex !== -1) {
+    return selector.slice(0, nthChildIndex) + toInject + selector.slice(nthChildIndex);
+  }
+  return selector + toInject;
+}
+
 /**
  * @typedef Filter
  * @type {Function}
@@ -246,8 +312,8 @@ function getUniqueSelector(element, selectorTypes, attributesToIgnore, filter) {
 }
 
 /**
- * Generate unique CSS selector for given DOM element. Selector uniqueness is determined based on the given element's root node. 
- * Elements rendered within Shadow DOM will derive a selector that is unique within the associated ShadowRoot context. 
+ * Generate unique CSS selector for given DOM element. Selector uniqueness is determined based on the given element's root node.
+ * Elements rendered within Shadow DOM will derive a selector that is unique within the associated ShadowRoot context.
  * Otherwise, a selector that is unique within the element's owning document will be derived.
  *
  * @param {Element} el
@@ -255,10 +321,10 @@ function getUniqueSelector(element, selectorTypes, attributesToIgnore, filter) {
  * @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.
+ * @param {Map<Element, String>} options.selectorCache Cache for Element -> Selector mappings. Caller is responsible for invalidation.
+ * @param {Map<String, Boolean>} options.isUniqueCache Cache for Selector -> isUnique mappings. Caller is responsible for invalidation.
+ * @param {{ attributeNames: string[], filter?: Function, elementCache?: Map<Element, (string|null)[]> }} options.requiredAttributes Attributes that must appear in the generated selector. Specifies the attribute names to inject, an optional filter function to control which values are allowed, and an optional element cache. Matching attributes are woven into the selector chain and ancestor context.
  * @return {String}
- * @api private
  */
 function unique(el) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
@@ -268,9 +334,30 @@ function unique(el) {
       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
-
+      isUniqueCache = options.isUniqueCache,
+      requiredAttributes = options.requiredAttributes;
+
+  var _ref2 = requiredAttributes || {},
+      requiredAttributeNames = _ref2.attributeNames,
+      requiredAttributesFilter = _ref2.filter,
+      requiredAttributesElementCache = _ref2.elementCache;
+
+  // Precompile required attribute patterns once per call to avoid repeated
+  // RegExp construction during the element walk.
+
+
+  var hasRequiredAttrs = requiredAttributeNames && requiredAttributeNames.length > 0;
+  var compiledRequiredAttrs = hasRequiredAttrs ? requiredAttributeNames.map(function (attributeName) {
+    // Escape regex metacharacters: - [ ] / { } ( ) * + ? . \ ^ $ |
+    var escaped = attributeName.replace(/[-[\]/{}()*+?.\\^$|]/g, '\\$&');
+    return {
+      attributeName: attributeName,
+      // Case-insensitive: catches any casing the base selector builder may have used for the attribute name.
+      dedupPattern: new RegExp('\\[' + escaped + '[=\\]]', 'i')
+    };
+  }) : null;
+
+  // Wrap filter to default to `true` when the provided function returns null/undefined
   var normalizedFilter = filter && function (type, key, value) {
     var result = filter(type, key, value);
     if (result === null || result === undefined) {
@@ -286,6 +373,13 @@ function unique(el) {
 
     if (!selector) {
       selector = getUniqueSelector(currentElement, selectorTypes, attributesToIgnore, normalizedFilter);
+
+      // Merge any matching required attributes into the element's selector
+      if (hasRequiredAttrs) {
+        var perAttrSelectors = getCachedPerAttrSelectors(currentElement, compiledRequiredAttrs, requiredAttributesFilter, requiredAttributesElementCache);
+        selector = insertRequiredAttrIntoSelector(selector, perAttrSelectors, compiledRequiredAttrs);
+      }
+
       if (selectorCache) {
         selectorCache.set(currentElement, selector);
       }
@@ -304,7 +398,7 @@ function unique(el) {
       // to prefix the selector with `:host >` to anchor against the root. This helps
       // address the possibility of a unique path segment not existing before reaching
       // the root.
-      if (!isUniqueSelector && (0, _isShadowRoot.isShadowRoot)(el.parentNode)) {
+      if (!isUniqueSelector && el.parentNode && (0, _isShadowRoot.isShadowRoot)(el.parentNode)) {
         maybeUniqueSelector = ':host > ' + maybeUniqueSelector;
         isUniqueSelector = (0, _isUnique.isUnique)(el, maybeUniqueSelector);
 
@@ -315,6 +409,22 @@ function unique(el) {
     }
 
     if (isUniqueSelector) {
+      // Prepend required attribute selectors from ancestors above the unique
+      // chain using descendant combinators (e.g. '[data-cy="app"] [data-cy="nav"] .btn').
+      if (hasRequiredAttrs) {
+        var ancestorSelectors = [];
+        var ancestor = currentElement.parentElement;
+        while (ancestor) {
+          var _perAttrSelectors = getCachedPerAttrSelectors(ancestor, compiledRequiredAttrs, requiredAttributesFilter, requiredAttributesElementCache);
+          var combined = _perAttrSelectors.filter(Boolean).join('');
+          if (combined) ancestorSelectors.unshift(combined);
+          ancestor = ancestor.parentElement;
+        }
+        if (ancestorSelectors.length > 0) {
+          return ancestorSelectors.join(' ') + ' ' + maybeUniqueSelector;
+        }
+      }
+
       return maybeUniqueSelector;
     }
 

package/lib/utils.js

@@ -0,0 +1,17 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.escapeAttributeValue = escapeAttributeValue;
+function escapeAttributeValue(value) {
+  // Ultra-minimal escaping purely for attribute values that will be used inside quotes
+  // Using `CSS.escape` would create valid but non-minimal strings (escaping things like spaces)
+  // whereas this only escapes absolutely necessary characters for attribute values that
+  // will be used inside quotes.
+  return value.replace(/\\/g, '\\\\') // backslash
+  .replace(/"/g, '\\"') // quote
+  .replace(/\n/g, '\\A ') // newline
+  .replace(/\r/g, '\\D ') // carriage return
+  .replace(/\f/g, '\\C '); // form feed
+}

package/package.json

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