{ "doc": { "id": "accessibility/core-concepts/element-identification", "title": "Uniquely identify test elements | Cypress Accessibility", "description": "Elements are uniquely identified across views and snapshots by their HTML attributes, location, and other signals in the DOM.", "section": "accessibility", "source_path": "/llm/markdown/accessibility/core-concepts/element-identification.md", "version": "524ff5211e60b5d53e55d6ad976d83966f66e7cd", "updated_at": "2026-04-30T14:20:05.396Z", "headings": [ { "id": "accessibility/core-concepts/element-identification#element-identification", "text": "Element Identification", "level": 1 }, { "id": "accessibility/core-concepts/element-identification#significant-attributes-for-identification", "text": "Significant attributes for identification", "level": 2 }, { "id": "accessibility/core-concepts/element-identification#configuring-element-identification", "text": "Configuring element identification", "level": 2 }, { "id": "accessibility/core-concepts/element-identification#attribute-filters", "text": "Attribute filters", "level": 3 }, { "id": "accessibility/core-concepts/element-identification#significant-attributes", "text": "Significant attributes", "level": 3 }, { "id": "accessibility/core-concepts/element-identification#component-attributes", "text": "Component attributes", "level": 3 }, { "id": "accessibility/core-concepts/element-identification#differences-compared-to-axe-core-element-identification", "text": "Differences compared to Axe-Core® element identification", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Element Identification" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress Accessibility identifies elements across views and snapshots using a combination of HTML attributes, location, and other signals in the DOM. Stable and unique identifiers are crucial for accurately tracking and de-duplicating elements throughout the various snapshots captured in your tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If your HTML uses attributes about things like component structure, design system versioning, or team ownership of certain DOM areas, Cypress Accessibility can be configured to include those as well. Configuration can also be used to avoid noisy locators that artificially inflate the count of issues, or to declare preferred identifiers that should be used." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Good element identification makes element selectors more readable and meaningful when " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/core-concepts/inspecting-violation-details.md", "children": [ { "type": "text", "value": "reviewing violation details" } ] }, { "type": "text", "value": ", and when " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/core-concepts/inspecting-violation-details.md#Create-Jira-issue", "children": [ { "type": "text", "value": "creating tickets" } ] }, { "type": "text", "value": ", or having the selectors interpreted by AI tools (see the we " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/work-with-ai-agents.md", "children": [ { "type": "text", "value": "Work with AI agents" } ] }, { "type": "text", "value": ")" } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Significant attributes for identification" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Certain attributes are prioritized by Cypress Accessibility for element identification. These include:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`data-cy`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`data-test`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`data-testid`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`data-test-id`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`data-qa`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`row-id`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`id`" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "`name`" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you already have Test IDs or similar attributes in your application, Cypress Accessibility will pick these up and use them to recognize the same element in a new place for improved deduplication. This behavior itself is configurable as well, so that highly-dynamic Test IDs can be avoided, for example." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Configuring element identification" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using these configuration properties helps you adjust the amount of deduplication Cypress will do to match what makes sense in your application. For example, a component-based Test ID might make a great identifier if the component renders static content, but the same exact test ID would be a poor identifier if the component renders different things everywhere - you might rather treat those instances as unique for accessibility purposes." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Attribute filters" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Exclude irrelevant or dynamically generated attributes to reduce noise in Cypress Accessibility reports. For example, this would avoid certain IDs that are commonly generated in React applications from being used as element references in Cypress Accessibility." } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"attributeFilters\": [ { \"attribute\": \"id\", \"value\": \":r.*:\", \"include\": false } ]}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Elements with these IDs will still be included in your accessibility report, but they will be identified in a different way." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Learn more about attribute filtering in the " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/configuration/attributefilters.md", "children": [ { "type": "text", "value": "Attribute Filters guide" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Significant attributes" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Define custom significant attributes to prioritize specific selectors that align with your application’s structure. For example:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"significantAttributes\": [\"data-custom-id\"]}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Refer to the " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/configuration/significantattributes.md", "children": [ { "type": "text", "value": "Significant Attributes" } ] }, { "type": "text", "value": " guide for detailed instructions." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Component attributes" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Require extra attributes (such as a component or team identifier) in the violation target selectors shown in reports, to provide consistency and readability in your selectors:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{ \"accessibility\": { \"components\": { \"componentAttributes\": [ { \"attributeName\": \"data-component-name\", \"includeInSelector\": true } ] } }}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "See the " }, { "type": "link", "title": null, "url": "/llm/markdown/accessibility/configuration/components.md", "children": [ { "type": "text", "value": "components" } ] }, { "type": "text", "value": " configuration guide for `componentAttributeFilters`, defaults, and examples." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Differences compared to Axe-Core® element identification" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The Cypress Cloud process replaces the underlying Axe-Core® library's default mechanism for identifying elements." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Axe-Core® captures a unique identifier for a given element in a specific DOM context, focused on one single state. This default behavior does not account for merging thousands of Axe-Core® scans into a single report or for comparing scans of the application as the application changes." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Taking control over how elements are tracked in your reports helps you get the right level of de-duplication across elements when they are truly the same, and track similar elements individually when they are different." } ] } ] }, "token_estimate": 752 }