Add a few guides to UI Coverage

docs/accessibility/configuration/elementfilters.mdx

@@ -11,8 +11,8 @@ sidebar_position: 20
 
 :::info
 
-Note: setting `elementFilters` impacts both Accessibility and UI Coverage
-reports. Nesting this property under an `accessibility` or `uiCoverage` key is
+**Note:** setting `elementFilters` impacts both 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.
 :::
 

docs/ui-coverage/configuration/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Configuration",
-  "position": 30
+  "position": 40
 }

docs/ui-coverage/configuration/attributefilters.mdx

@@ -8,13 +8,17 @@ sidebar_label: attributeFilters
 
 <UICovAddon />
 
-UI Coverage has logic that automatically [identifies](/ui-coverage/core-concepts/element-identification) and [groups](/ui-coverage/core-concepts/element-grouping) elements based on their appearance and structure in the DOM.
+UI Coverage [identifies](/ui-coverage/core-concepts/element-identification) and [groups](/ui-coverage/core-concepts/element-grouping) elements based on their attributes and structure in the DOM. However, some attributes 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.
 
-Sometimes, an element may have attributes that are auto-generated or otherwise not representative of the element that Cypress's UI Coverage algorithm uses for identification and grouping. This can cause the same element to be identified as multiple different elements, or multiple different elements to be identified as the same element.
+By using `attributeFilters`, you can ensure UI Coverage selects more appropriate identifiers, leading to cleaner and more accurate coverage reports.
 
-The `attributeFilters` configuration property allows users to specify patterns for attributes and their values that should **not** be used for identifying and grouping elements, thereby allowing UI Coverage to find more suitable identifiers for the impacted elements.
+## Why use `attributeFilters`?
 
-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.
+### Common use cases
+
+- **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 coverage reports, making them easier to interpret and act upon.
 
 ## Syntax
 
@@ -32,49 +36,24 @@ For every attribute that an element has, the first `attributeFilters` rule for w
 }
 ```
 
-### attributeFilters
-
-_Optional._ Object\[]
-
-An array of objects used to determine whether or not an attribute will be used for element identification and grouping. _**Each object can have the following properties:**_
-
-### attribute
-
-_Required._ String (Regex)
-
-Used to match the attribute names.
-
-### value
-
-_Optional._ String (Regex)
-
-_Default_: `.*` (matches any value).
-
-Used to match the attribute values.
+### Options
 
-### include
-
-_Optional._ Boolean
-
-_Default:_ `true`
+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.
 
-Whether or not a matched attribute should be used for element identification and grouping.
+| Option      | Required | Default | Description                                                            |
+| ----------- | -------- | ------- | ---------------------------------------------------------------------- |
+| `attribute` | Required |         | A regex string to match attribute names                                |
+| `value`     | Optional | `.*`    | A regex string to match attribute values                               |
+| `include`   | Optional | `true`  | A boolean to specify whether the matched attribute should be included. |
 
 ## Examples
 
 ### Excluding common auto-generated id values
 
-#### Config
-
 ```json
 {
   "uiCoverage": {
     "attributeFilters": [
-      {
-        "attribute": "id",
-        "value": "sizzle.*",
-        "include": false
-      },
       {
         "attribute": "id",
         "value": ":r.*:",
@@ -89,12 +68,12 @@ Whether or not a matched attribute should be used for element identification and
 
 ```xml
 <body>
-  <button id="sizzle123" name="my-button">Button 1</button>
-  <button id=":r10:" name="other-button">Button 2</button>
+  <button id=":r11:" name="my-button">Button 1</button>
+  <button id=":r12:" name="other-button">Button 2</button>
 </body>
 ```
 
-#### Elements shown in UI
+#### Elements shown in UI Coverage
 
 ```
 [name="my-button"]
@@ -105,8 +84,6 @@ Whether or not a matched attribute should be used for element identification and
 
 ### Excluding auto-generated attribute names
 
-#### Config
-
 ```json
 {
   "uiCoverage": {
@@ -135,9 +112,38 @@ Whether or not a matched attribute should be used for element identification and
 </body>
 ```
 
-#### Elements shown in UI
+#### Elements shown in UI Coverage
 
 ```
 [ng-include-me="my-button"]
 :nth-child(2)
 ```
+
+### Ignoring dynamic attributes for accurate grouping
+
+```json
+{
+  "uiCoverage": {
+    "attributeFilters": [
+      {
+        "attribute": "data-cy",
+        "value": "user-\\d+",
+        "include": false
+      }
+    ]
+  }
+}
+```
+
+#### HTML
+
+```xml
+<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)
+```

docs/ui-coverage/configuration/elementfilters.mdx

@@ -8,15 +8,21 @@ sidebar_label: elementFilters
 
 <UICovAddon />
 
+By default, every interactive and visible element is included in UI Coverage. The `elementFilters` property allows you to specify selectors for elements that should be excluded from these reports. This configuration is particularly useful for removing irrelevant or non-actionable elements to streamline coverage analysis.
+
+## Why use element filters?
+
 :::info
-Note: setting `elementFilters` impacts both Accessibility and UI Coverage
-reports. Nesting this property under an `accessibility` or `uiCoverage` key is
+**Note:** setting `elementFilters` impacts both 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.
 :::
 
-By default, every interactive and visible element is included in UI Coverage. The `elementFilters` property allows you to specify selectors for elements that should be excluded from UI Coverage.
+### Common use cases
 
-For every element considered interactive and visible by UI Coverage, the first `elementFilters` rule for which the `selector` property matches the element is used to either include or exclude the element based on the `include` value. Elements that do not match any rules are included by default.
+- **Excluding Irrelevant Elements**: Decorative icons, marketing banners, or tooltips that do not require testing can clutter reports. Use elementFilters to exclude them.
+- **Ignoring 3rd Party Components**: Libraries or widgets that are not part of your application logic can be excluded from coverage reports.
+- **Streamlining Reports**: Reducing noise by filtering out non-essential elements makes coverage reports more actionable.
 
 ## Syntax
 
@@ -31,28 +37,14 @@ For every element considered interactive and visible by UI Coverage, the first `
 }
 ```
 
-### elementFilters
-
-_Optional._ Object\[]
-
-An array of objects used to specify elements to exclude from UI Coverage. _**Each object can have the following properties:**_
-
-### selector
-
-_Required._ String (CSS Selector)
-
-A CSS selector used to identify elements.
-
-- Supports all standard CSS selector syntax including IDs, classes, attributes, and combinators
-- The selector matches exactly what is specified - for example, `#container` matches the container element itself, while `#container *` matches all elements within the container
+### Options
 
-### include
+For every element considered interactive and visible by UI Coverage, the first `elementFilters` rule for which the selector property matches the element is used to either include or exclude the element based on the `include` value. Elements that do not match any rules are included by default.
 
-_Optional._ Boolean
-
-_Default:_ `true`
-
-A boolean that represents whether or not a matched element should be included in UI Coverage.
+| Option     | Required | Default | Description                                                                                                                      |
+| ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `selector` | Required |         | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
+| `include`  | Optional | `true`  | A boolean indicating whether the matched elements should be included in UI Coverage.                                             |
 
 ## Examples
 
@@ -80,7 +72,7 @@ A boolean that represents whether or not a matched element should be included in
 </body>
 ```
 
-#### Elements shown in UI
+#### Elements shown in UI Coverage
 
 ```
 #button-1
@@ -116,15 +108,15 @@ A boolean that represents whether or not a matched element should be included in
 </body>
 ```
 
-#### Elements shown in UI
+#### Elements shown in UI Coverage
 
 ```
 #start
 ```
 
 ---
 
-### Including only elements in a container
+### Including only elements in a specific container
 
 #### Config
 
@@ -161,3 +153,67 @@ A boolean that represents whether or not a matched element should be included in
 ```
 #name
 ```
+
+---
+
+### Excluding Elements by Attribute
+
+#### Config
+
+```json
+{
+  "elementFilters": [
+    {
+      "selector": "[data-role='decorative']",
+      "include": false
+    }
+  ]
+}
+```
+
+```xml
+<body>
+  <button data-role="decorative">
+    <img src="icon.png" />
+  </button>
+  <button data-role="primary">
+    View
+  </button>
+</body>
+```
+
+#### Elements shown in UI Coverage
+
+```
+[data-role="primary"]
+```
+
+### Excluding dynamic elements by pattern
+
+#### Config
+
+```json
+{
+  "elementFilters": [
+    {
+      "selector": "[class^='auth']",
+      "include": false
+    }
+  ]
+}
+```
+
+#### HTML
+
+```xml
+<body>
+  <button class="cancel">Cancel</button>
+  <button class="auth908283794">Login</button>
+</body>
+```
+
+#### Elements shown in UI Coverage
+
+```
+.cancel
+```