Skip to main content
Cypress AccessibilityPremium Solution

attributeFilters

Cypress Accessibility identifies elements based on a combination of attributes and the surrounding DOM structure.

Some attributes used for identification may be auto-generated, dynamic, or unrepresentative, 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.
  • Streamlining reports: Eliminating noisy attributes reduces clutter in Cypress Accessibility or UI Coverage reports, making them easier to interpret and act upon.

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
    }
  ]
}

Options​

For every attribute that an element has, the first attributeFilters rule for which the attribute property matches the attribute's name and the value property matches the attribute's value, the include value is used to determine whether or not the attribute will be used for element identification and grouping. Attributes that do not match any rules are included by default.

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.

Examples​

Excluding common auto-generated id values​

{
  "uiCoverage": {
    "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>

Elements shown in UI Coverage​

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

Excluding auto-generated attribute names​

{
  "uiCoverage": {
    "attributeFilters": [
      {
        "attribute": "ng-include-me",
        "value": ".*",
        "include": true
      },
      {
        "attribute": "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>

Elements shown in UI Coverage​

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

Ignoring dynamic attributes for accurate grouping​

{
  "uiCoverage": {
    "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>

Elements shown in UI Coverage​

.user (2 instances)

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
{
  "uiCoverage": {
    "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>

Elements shown in UI Coverage​

label
input
p