Skip to main content
UI CoveragePremium Solution

attributeFilters

UI Coverage identifies and groups elements based on their attributes and structure in the DOM.

Some attributes used for identification may be auto-generated, dynamic, or state-based, leading to inaccurate identification or grouping. The attributeFilters configuration property allows you to exclude specific attributes or patterns that should not be used for these purposes.

By using attributeFilters, you can ensure Cypress selects more appropriate identifiers, leading to cleaner and more accurate reports, with better element de-deduplication across distinct states of the application being tested.

Why use attribute filters?​

  • Handling library-specific attributes: Attributes generated by libraries may not represent the element's purpose and should be ignored.
  • Improving grouping accuracy: By filtering out irrelevant attributes, you ensure similar elements are grouped correctly.
  • Avoiding state-based duplication: Classes like link--focused can clutter report findings.

Scope​

info

Note: setting attributeFilters impacts both Cypress Accessibility and UI Coverage reports if set at the root of the configuration. Nesting this property under an accessibility or uiCoverage key is supported, if you need to split them up.

Syntax​

{
  "attributeFilters": [
    {
      "attribute": string,
      "value": string,
      "include": boolean,
      "comment": string
    }
  ]
}

Options​

Whether Cypress is allowed to use a certain attribute to identify an element when processing it for UI Coverage or Cypress Accessibility reports will be controlled by the first filter that matches the name and value of that attribute.

This means that catch-all rules can be added at the bottom of the list by setting include to false, and exceptions can be defined earlier in the list using include: true. For example, you could avoid all use of aria-label for identification of elements as a catch-call filter, but then define exceptions for certain values it may have where it is a good identifier.

Attributes that do not match any rules are included by default and used if needed, so include: true is only required for defining exceptions. If you want to make sure an attribute is preferred as an identifier when available, add it to your attributeFilters.

OptionRequiredDefaultDescription
attributeRequiredA regex string to match attribute names
valueOptional.*A regex string to match attribute values
includeOptionaltrueA boolean to specify whether the matched attribute should be included.
commentOptionalA comment describing the purpose of this filter rule.

Examples​

Excluding common auto-generated ID values​

Some component libraries generate

{
  "attributeFilters": [
    {
      "attribute": "id",
      "value": ":r.*",
      "include": false
    }
  ]
}

HTML​

<body>
  <button id=":r11:" name="my-button">Button 1</button>
  <button id=":r12:" name="other-button">Button 2</button>
</body>

Element identifiers displayed​

[name="my-button"]
[name="other-button"]

When filtering dynamic id attributes, you should also filter attributes that reference those IDs to prevent elements from being identified by these related dynamic values. Common relationships include:

  • Form associations (for attributes on labels)
  • ARIA relationships (aria-labelledby, aria-describedby, aria-controls, aria-owns, aria-details)
  • Name attributes that may mirror IDs in certain frameworks
{
  "attributeFilters": [
    {
      "attribute": "id|for|name|aria-.*",
      "value": "dynamic-.*",
      "include": false
    }
  ]
}

HTML​

<div>
  <label for="dynamic-input-1">First Name</label>
  <input id="dynamic-input-1" name="dynamic-input-1" aria-describedby="dynamic-help-1" />
  <p id="dynamic-help-1">Enter your first name</p>
</div>

Element identifiers displayed​

label
input
p

Excluding auto-generated attribute names​

{
  "attributeFilters": [
    {
      "attribute": "ng-include-me",
      "value": ".*",
      "include": true
    },
    {
      "attribute": "ng-.*|_ng.*",
      "value": ".*",
      "include": false
    }
  ]
}

HTML​

<body>
  <button ng-include-me="my-button">Button 1</button>
  <button ng-but-not-me="other-button">Button 2</button>
</body>

Element identifiers displayed​

[ng-include-me="my-button"]
:nth-child(2)

Ignoring dynamic attributes for accurate grouping​

{
  "attributeFilters": [
    {
      "attribute": "data-cy",
      "value": "user-\\d+",
      "include": false
    }
  ]
}

HTML​

<button data-cy="user-123" class="user">Harper</button>
<button data-cy="user-456" class="user">Amara</button>

Element identifiers displayed​

.user (2 instances)