{
  "doc": {
    "id": "ui-coverage/troubleshooting",
    "title": "Troubleshooting | Cypress UI Coverage",
    "description": "Common problems and solutions for Cypress UI Coverage.",
    "section": "ui-coverage",
    "source_path": "/llm/markdown/ui-coverage/troubleshooting.md",
    "version": "7ada28c0cd90e81cf56fd3fc73de6e6d45c16de6",
    "updated_at": "2026-05-13T21:55:41.935Z",
    "headings": [
      {
        "id": "ui-coverage/troubleshooting#troubleshooting",
        "text": "Troubleshooting",
        "level": 1
      },
      {
        "id": "ui-coverage/troubleshooting#a-single-element-appears-as-multiple-elements",
        "text": "A single element appears as multiple elements",
        "level": 2
      },
      {
        "id": "ui-coverage/troubleshooting#solutions",
        "text": "Solutions",
        "level": 3
      },
      {
        "id": "ui-coverage/troubleshooting#multiple-different-elements-are-identified-as-the-same",
        "text": "Multiple different elements are identified as the same",
        "level": 2
      },
      {
        "id": "ui-coverage/troubleshooting#solutions",
        "text": "Solutions",
        "level": 3
      },
      {
        "id": "ui-coverage/troubleshooting#similar-elements-are-not-grouped-together",
        "text": "Similar elements are not grouped together",
        "level": 2
      },
      {
        "id": "ui-coverage/troubleshooting#solutions",
        "text": "Solutions",
        "level": 3
      },
      {
        "id": "ui-coverage/troubleshooting#different-elements-are-incorrectly-grouped-together",
        "text": "Different elements are incorrectly grouped together",
        "level": 2
      },
      {
        "id": "ui-coverage/troubleshooting#solutions",
        "text": "Solutions",
        "level": 3
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Troubleshooting"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "A single element appears as multiple elements"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When a single element is identified as multiple distinct elements in UI Coverage, it may indicate an issue with "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md",
            "children": [
              {
                "type": "text",
                "value": "Element Identification"
              }
            ]
          },
          {
            "type": "text",
            "value": ". This often occurs due to:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Auto-generated or dynamic attributes (e.g., UUIDs) that differ across snapshots."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Library-specific identifiers, such as id attributes generated by frameworks."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Solutions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Add Unique Identifiers: Assign a stable identifier like `data-cy` or `data-test` to the element."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Ignore Dynamic Attributes: Use "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`attributeFilters`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to exclude attributes that change across tests."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Manually Configure Identification: Use "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/elements.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "elements"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration to explicitly define how the element should be identified."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Multiple different elements are identified as the same"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If different elements are being grouped as one in UI Coverage, this could be due to insufficient or non-specific identifiers, such as:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Missing unique `data-*` or `id` attributes."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Generic identifiers like `data-test=\"button\"` shared across multiple elements."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Use of attributes not prioritized by UI Coverage, like `aria-label`."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Solutions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Add unique identifiers: Assign distinct identifiers like `data-cy` or `data-test` values to each element."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Filter generic attributes: Exclude unrepresentative attributes using "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`attributeFilters`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Customize attribute use: Update "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`significantAttributes`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration to prioritize relevant identifiers."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Manually Identify Elements: Use "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/elements.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "elements"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration to specify how elements should be identified."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Similar elements are not grouped together"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If elements performing the same action are not "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-grouping.md",
            "children": [
              {
                "type": "text",
                "value": "grouped"
              }
            ]
          },
          {
            "type": "text",
            "value": ", it may be due to:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Library-specific identifiers, like dynamic `id` values, are not representative of the element and prevent grouping."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Identifiers that include dynamic data, such as UUID's"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Solutions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Use Shared Identifiers: Apply consistent `data-cy` or `data-test` values across similar elements."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Ignore Dynamic Attributes: Configure "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`attributeFilters`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " to exclude varying attributes."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Manually Group Elements: Use "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`elementGroups`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration to define custom groupings."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Different elements are incorrectly grouped together"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "If unrelated elements are "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/ui-coverage/core-concepts/element-grouping.md",
            "children": [
              {
                "type": "text",
                "value": "grouped"
              }
            ]
          },
          {
            "type": "text",
            "value": ", it may be due to overly generic identifiers or shared attributes. Some common examples of this include:"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Missing unique attributes that could distinguish the elements."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Generic values like `data-test=\"button\"` shared across different elements."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Solutions"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Add Distinct Identifiers: Use unique `data-cy` or `data-test` values for each element."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Filter Shared Attributes: Exclude generic identifiers with "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/attributefilters.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`attributeFilters`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Update Identification Rules: Adjust "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/significantattributes.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`significantAttributes`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration to improve differentiation."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "Manually Separate Groups: Define individual groups using "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/ui-coverage/configuration/elementgroups.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`elementGroups`"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": " configuration."
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 516
}