diff --git a/docs/accessibility/configuration/attributefilters.mdx b/docs/accessibility/configuration/attributefilters.mdx
new file mode 100644
index 0000000000..0f161f1ee5
--- /dev/null
+++ b/docs/accessibility/configuration/attributefilters.mdx
@@ -0,0 +1,16 @@
+---
+title: 'Attribute Filters | Cypress Accessibility'
+description: 'The `attributeFilters` configuration property allows users to specify patterns for attributes and their values that should not be used for identifying and grouping elements.'
+sidebar_label: attributeFilters
+sidebar_position: 50
+---
+
+
+
+# attributeFilters
+
+Cypress Accessibility [identifies elements](/ui-coverage/core-concepts/element-identification) based on a combination of attributes and the surrounding DOM structure.
+
+{' '}
+
+
diff --git a/docs/accessibility/configuration/elementfilters.mdx b/docs/accessibility/configuration/elementfilters.mdx
index c3ba856877..9555fc213e 100644
--- a/docs/accessibility/configuration/elementfilters.mdx
+++ b/docs/accessibility/configuration/elementfilters.mdx
@@ -2,7 +2,7 @@
title: 'Element Filters | Cypress Accessibility'
description: 'The `elementFilters` property allows you to specify selectors for elements that should be excluded from Cypress Accessibility.'
sidebar_label: elementFilters
-sidebar_position: 20
+sidebar_position: 30
---
diff --git a/docs/accessibility/configuration/overview.mdx b/docs/accessibility/configuration/overview.mdx
index 32acf9053d..eac51fe0bf 100644
--- a/docs/accessibility/configuration/overview.mdx
+++ b/docs/accessibility/configuration/overview.mdx
@@ -1,7 +1,7 @@
---
sidebar_label: Overview
title: 'Configuration | Cypress Accessibility'
-description: 'Configuration allows you to customize and fine-tune Accessibility in Cypress.'
+description: 'Configuration allows you to customize and fine-tune Cypress Accessibility.'
sidebar_position: 10
---
@@ -9,7 +9,7 @@ sidebar_position: 10
# Configuration
-Configuration allows you to customize and fine-tune Accessibility in Cypress. While Accessibility is designed to work seamlessly out of the box, there are instances where custom configuration may be necessary to address unique application structures, testing requirements, or edge cases. This section guides you through setting configuration to enhance the functionality and accuracy of Accessibility.
+Configuration allows you to customize and fine-tune accessibility reports in Cypress. While Cypress Accessibility is designed to work seamlessly out of the box, there are instances where custom configuration may be necessary, or preferred. Using configuration, you can avoid reporting on pages or elements that don't matter to your team, combine related urls together into a single View, and modify the element identification and deduplication behavior to reflect your application's specific structure.
**Note**: By default, setting configuration is limited to Admin users. At your request, this can be changed to allow setting config by all users. Reach out to your Cypress point-of-contact if you would like to change this.
@@ -26,12 +26,6 @@ You can use the provided editor to write configuration in JSON format. A complet
```typescript
{
- "elementFilters": [
- {
- "selector": string,
- "include": boolean
- }
- ],
"views": [
{
"pattern": string,
@@ -45,6 +39,22 @@ You can use the provided editor to write configuration in JSON format. A complet
"pattern": string,
"include": boolean
}
+ ],
+ "elementFilters": [
+ {
+ "selector": string,
+ "include": boolean
+ }
+ ],
+ "significantAttributes": [
+ string
+ ]
+ "attributeFilters": [
+ {
+ "attribute": string,
+ "value": string,
+ "include": boolean
+ }
]
}
```
diff --git a/docs/accessibility/configuration/significantattributes.mdx b/docs/accessibility/configuration/significantattributes.mdx
new file mode 100644
index 0000000000..15a3dc8e66
--- /dev/null
+++ b/docs/accessibility/configuration/significantattributes.mdx
@@ -0,0 +1,12 @@
+---
+title: 'Significant Attributes | Cypress Accessibility'
+description: 'The `significantAttributes` configuration property allows users to specify custom attributes that should be considered "significant" for the purpose of identification and grouping.'
+sidebar_label: significantAttributes
+sidebar_position: 40
+---
+
+
+
+# significantAttributes
+
+
diff --git a/docs/accessibility/configuration/viewfilters.mdx b/docs/accessibility/configuration/viewfilters.mdx
index 45b45648c5..baec67f407 100644
--- a/docs/accessibility/configuration/viewfilters.mdx
+++ b/docs/accessibility/configuration/viewfilters.mdx
@@ -2,7 +2,7 @@
title: 'View Filters | Cypress Accessibility'
description: 'The `viewFilters` property allows you to specify URL patterns for URLs that should be excluded from Accessibility.'
sidebar_label: viewFilters
-sidebar_position: 30
+sidebar_position: 20
---
diff --git a/docs/accessibility/configuration/views.mdx b/docs/accessibility/configuration/views.mdx
index a20b30059b..2ff2a79746 100644
--- a/docs/accessibility/configuration/views.mdx
+++ b/docs/accessibility/configuration/views.mdx
@@ -2,7 +2,7 @@
title: 'Views of URLs and mounted components | Cypress Accessibility'
description: 'Cypress Accessibility automatically groups certain URL patterns to create views. For URLs that are not automatically grouped, the views property allows you to specify your own URL patterns that represent views.'
sidebar_label: views
-sidebar_position: 40
+sidebar_position: 10
---
diff --git a/docs/accessibility/core-concepts/compare-reports.mdx b/docs/accessibility/core-concepts/compare-reports.mdx
index c98e18685b..bbffe3f60a 100644
--- a/docs/accessibility/core-concepts/compare-reports.mdx
+++ b/docs/accessibility/core-concepts/compare-reports.mdx
@@ -18,6 +18,15 @@ See the video below for an example of using Branch Review in a Pull Request:
title="Accessibility branch review demo"
/>
+Comparing two accessibility reports manually is usually a challenge:
+
+- each report may test thousands of application snapshots for a single Cypress run
+- 80+ accessibility rules are tested for each snapshot
+- many different pages or components are tested and may have changes
+- elements might be identified differently in each run
+
+Branch Review for Cypress Accessibility is set up to help you easily browse this nested set of changes and find what's important. You can review any accessibility violation increases found for specific rules, and drill into the Views where those changes happened.
+
## Use cases
Comparing the results from different runs is useful in multiple scenarios.
@@ -34,38 +43,124 @@ Comparing the results from different runs is useful in multiple scenarios.
## Content of the report
-The Branch Review report is prioritized into three sections:
+The key to understanding the run comparison report is that the Changed run is the focal point for all data that will be displayed, and the Base run is used as a reference point for comparison. So everywhere that you see an element, or drill in for more details, you will only see data from the Changed run.
+
+The Branch Review report is divided into two sections:
-- **New failed rules**: Rules that were passing every time they ran on the `base` run but now have failures in the `changed` run.
-- **Resolved rules**: Rules that had some failures detected in the `base` run but have no failures on the `changed` run. This helps you celebrate the wins and recognize when a new run has gone green.
-- **Failed rules with changes**: Rules that were failing in both runs, where the elements with failures detected have increased, decreased, or changed in some way.
+- **New failed elements**: Counts of elements that have failures in the Changed run, where matching failures were not found on the Base run. These are listed by View, for each accessibility rule where new failures were detected.
+- **Resolved elements**: Counts of elements that had failures detected in the Base run which are no longer detected in the Changed run. These are also listed as improvements in each View, under the accessibility rules that had improvements.
-This organization of the report brings the most significant results to the top - regressions of rules that had been fully passing in the `base` run. Increases or decreases in the element counts for rules that already have some failures provide a good sense of progress, but can tend to be noisier, especially if the runs have different content or other conditions have changed in between.
+If the Changed run is associated with a Pull Request and runs the same overall test suite as the Base run, the changes in the report are likely due to code changes in the pull request.
## How to compare runs
The first step is to get to the [Branch Review](/cloud/features/branch-review.mdx) area of Cypress Cloud, which will let you compare one branch against another - or different runs on the same branch, if needed.
You can access this area by clicking the branch name associated with a run, or in several other ways. [Learn more about how to compare runs](/cloud/features/branch-review.mdx).
-## FAQ
+## Details of each section
+
+### New failed elements
+
+A **new failed element** is any failed element which either did not exist in the Base run at all, or existed in the Base run but was passing its accessibility checks.
+
+
+
+Any rules with new failed elements will appear here. There are two ways to explore this list. You can open each rule and choose from he list of Views where a new failed element was detected, or if you click the "View All" link, you will see a full report containing all of the net-new failures in the run, across all rules and views.
+
+Either path will take you to the detailed report, either for a single View or for all View combined. This report works exactly like the main Cypress Accessibility report, with full-page snapshot examples for every violation. The only difference is that all issues that are the same on both runs have been removed, leaving just what's new - either for the specific View you've chosen, or across all views.
+
+
+
+#### Single-View diff vs whole-run diff
+
+Each rule has an "All Views" comparison as the first item, and then lists individual Views below that. Depending on the level of detail you are looking for, you can drill into a specific page or component and see the changes in accessibility there, or just look at the combined report.
+
+The combined "All Views" report for a single rule is especially useful if violations tend to move around between pages over time. For example, if there is a popup with an accessibility problem that appears on a random page in every run, it may appear "new" for a View in the Changed run, and "resolved" for the View where it was in the Base run, but in reality your accessibility score is the same and the problem is the same. "All Views" allows you to sidestep any noise of this kind if needed.
+
+### Resolved elements
+
+A **resolved element** is an element that had a failed accessibility rule in the Base Run, where a matching failure is not found in the Changed run.
+
+
+
+Resolved elements are calculated for every rule and View, but are not displayed individually. This is because, as far as the Changed report is concerned, the failures do not exists, so there is not a guarantee the element is still present in the "new" report.
+
+If you have a use case for seeing the specific elements that are no longer detected to have failures, please reach out to your Cypress representative for further discussion. For the time being the focus of Branch Review is on **new problems** - we avoid mixing old and new data in the same report to minimize the chances of confusion.
+
+### What if there are no changes?
-### How do I ensure a good comparison?
+If there are no changes, the Accessibility Branch Review report still displays all the sections, and explains that there are no elements that appear to be new or resolved in Changed run:
-The best subjects to compare are passing runs that ran similar tests on the same set of content. This means that each run visited roughly the same pages and completed the same kinds of workflows. In this situation, any diff in the results is likely the result of changes present in the newer run. This is usually what happens out-of-the box when comparing a pull-request branch with your main branch.
+
+
+This means the reports are identical, and that the Changed run has not had any impact on accessibility.
+
+## Ensuring a good comparison
+
+The easiest subjects to compare are **passing runs** that ran **similar tests** on the **similar content**. This means that each run visited roughly the same pages and completed the same kinds of workflows. In this situation, any diff in the results is likely the result of changes present in the newer run. This is usually what happens out-of-the box when comparing a pull-request branch with your main branch, for example - assuming the same tests run on both branches.
That said, it still possible and valid to compare runs from different points in time with different sets of test results, as long as you bear in mind all the potential sources of difference between the two runs, which you can evaluate for yourself as you explore the results.
In order to see unified changes for your entire test suite, you need to group all the tests together under a single Cypress run, for each report. Learn more about this in the [Branch Review Best Practices documentation](/cloud/features/branch-review#Best-Practices).
-### What is the purpose of the Beta label?
+### Stabilizing the comparison
-This indicates the feature is ready for use and actively seeking feedback based on real usage of the current implementation. We have a few known issues to work through on our side before we consider this fully production-ready and remove the beta label. These issues only affect a subset of projects -- in most cases everything is working as intended. If you see anything unexpected, please use the feedback button and let us know.
+On most projects, comparing accessibility reports will work nicely out of the box. But in some cases, configuration is useful to handle dynamic values that might be present in page URLs or element locator. You may also want to take steps to improve the consistency of the elements under test.
-### Why do I see some views (pages or components) changing from run-to-run?
+### Stable Views
URLs with dynamic slugs in them can appear as "new" pages in some situations. This behavior can be adjusted with [View configuration](/accessibility/configuration/views) to make sure page names will match across runs by wildcarding parts of the URL as needed.
+
+Cypress performs this process automatically for certain known patterns. For example, the default behavior is to track a URL like `https://example.com/products/123` as `https://example.com/products/*` so that the underlying product pages are grouped together as one View, and then between runs that View is recognized in a stable way.
+
+If a View appears to be "new", it is identified with a green plus icon, and a tooltip explaining that this View was seen on the Changed run but not on the base run, as seen here in the New Failed Elements section:
+
+
+
+Likewise, if a rule appears to have resolved elements on Views that are simply no longer captured on the Changed run, this is identified in the Resolved Elements section:
+
+
+
+These changes in Views may be because a new page was actually added to the application, or a new page was reached by testing that wasn't reached before. It will be clear to you if configuration is needed to improve View stability across runs, as you will see unexpected added and removed URLs.
+
+### Stable Elements
+
+Cypress stores a string that represents each failed element in a report, determined using a standardized [element identification process](/accessibility/core-concepts/element-identification). This operates in a different way to the standard Axe-Core® element identification algorithm, to support the comparison of runs from different builds of the application, and make use of the testing-related attributes you may already have created in the DOM.
+
+Where possible, we prioritize known stable locators like `data-cy` or `data-testid`. In some cases the identification strings will contain dynamic values that change on every build of your application, introducing noise in a diff. The element identification behavior is flexible and can be configured to meet your needs and fully avoid dynamic values as identifiers.
+
+For example, if an element's default locator includes a class like `.css-21kj23` in Build A, and a slightly different class like `.css-2309kj` in Build B, it will appear as though there was a "resolved element" and "new violation".
+
+This behavior is highly customizable so that you can avoid depending on values that don't matter to you, but also you can choose specific attributes that _do_ matter for element recognition and get sensible deduplication and matching behavior based on your own goals.
+
+Learn more about the [`attributeFilters`](/accessibility/configuration/attributefilters) and [`significantAttributes`](/accessibility/configuration/significantattributes) configuration available, or reach out to us for any assistance on dialing in the behavior.
+
+### Stable underlying reporting area
+
+It's likely that your tests have never been used for always-on accessibility tests before, and while most codebases produce stable results, some projects have inherent differences between runs due to the performance of specific processes during testing.
+
+For example, sometimes the test may spend enough time on a page to see a confirmation message after a form is submitted, unless the server response is slow, then the test may finish without rendering the state.
+
+There are different solutions depending on the nature of the issue. If you want to ensure the state is always picked up in Cypress Accessibility, you can add some assertion about that state to your tests. On the other hand, if you do not want to account for this state at all, it can be ignored with [`elementFilters`](/accessibility/configuration/elementfilters) configuration. Either approach will lead to a more stable branch comparison.
diff --git a/docs/accessibility/core-concepts/element-identification.mdx b/docs/accessibility/core-concepts/element-identification.mdx
new file mode 100644
index 0000000000..6033739478
--- /dev/null
+++ b/docs/accessibility/core-concepts/element-identification.mdx
@@ -0,0 +1,63 @@
+---
+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.'
+sidebar_label: Element identification
+sidebar_position: 20
+---
+
+
+
+# Element Identification
+
+Cypress Accessibility uniquely 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.
+
+This process replaces the underlying Axe-Core® library's default mechanism for identifying elements, which also uses strings but focusing on capturing a unique identifier for a given element in a specific DOM context. The default behavior does not account for situations where sometimes tens of thousands of Axe-Core® scans need to be merged together for a single run, or later compared based on different builds of the application. Both of these happen in Cypress Cloud, and are much more effective when the element identification process is controllable by the user and can be customized for your project.
+
+## Significant attributes for identification
+
+Certain attributes are prioritized by Cypress Accessibility for element identification. These include:
+
+- `data-cy`
+- `data-test`
+- `data-testid`
+- `data-test-id`
+- `data-qa`
+- `row-id`
+- `id`
+- `name`
+
+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.
+
+## Configuring element identification
+
+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.
+
+### Attribute filters
+
+Exclude irrelevant or dynamically generated attributes to reduce noise in Cypress Accessibility reports. For example:
+
+```json
+{
+ "attributeFilters": [
+ {
+ "attribute": "id",
+ "value": ":r.*:",
+ "include": false
+ }
+ ]
+}
+```
+
+Learn more about attribute filtering in the [Attribute Filters](/accessibility/configuration/attributefilters) guide.
+
+### Significant attributes
+
+Define custom significant attributes to prioritize specific selectors that align with your application’s structure. For example:
+
+```json
+{
+ "significantAttributes": ["data-custom-id"]
+}
+```
+
+Refer to the [Significant Attributes](/accessibility/configuration/significantattributes) guide for detailed instructions.
diff --git a/docs/accessibility/guides/maintain-accessibility.mdx b/docs/accessibility/guides/maintain-accessibility.mdx
index 6c08f73a10..d91ff5baab 100644
--- a/docs/accessibility/guides/maintain-accessibility.mdx
+++ b/docs/accessibility/guides/maintain-accessibility.mdx
@@ -1,5 +1,5 @@
---
-sidebar_label: Maintain Accessibility
+sidebar_label: Maintain accessibility
title: 'Maintain Accessibility | Cypress Accessibility Documentation'
description: 'Learn how to maintain long-term accessibility with Cypress, using continuous feedback and monitoring to prevent regressions and keep your application accessible.'
sidebar_position: 30
@@ -13,7 +13,7 @@ Accessibility isn't a one-time project—it's a continuous process. This guide e
## Switching from "improving" to "maintaining"
-When a specific accessibility rule reaches zero violations for a page, component, or application, you enter _maintenance mode_ for that rule. From this point a few areas are imprortant to focus on:
+When a specific accessibility rule reaches zero violations for a page, component, or application, you enter _maintenance mode_ for that rule. From this point a few areas are important to focus on:
- **Pre-Merge Insights**: Any new violations detected on a feature branch are clear indicators that changes on that branch introduced the issue. This could stem from updates in application code that impact accessibility or expanded test coverage revealing new issues.
- **Post-Merge Monitoring**: If violations resurface on the main branch, tracing their introduction to specific pull requests helps pinpoint code or test changes causing the problem and facilitate follow-ups and training for developers.
diff --git a/docs/accessibility/results-api.mdx b/docs/accessibility/results-api.mdx
index 0579af2f1c..76da044dd7 100644
--- a/docs/accessibility/results-api.mdx
+++ b/docs/accessibility/results-api.mdx
@@ -33,6 +33,7 @@ Fetching Accessibility results for a run supports fetching results for the follo
- [GitHub Actions](/app/continuous-integration/github-actions)
- [GitLab](/app/continuous-integration/gitlab-ci)
- [Jenkins](/app/continuous-integration/overview#Jenkins)
+- [AWS CodeBuild](/app/continuous-integration/aws-codebuild)
Please reach out to Cypress Support to request support for a different provider.
@@ -410,5 +411,38 @@ workflows:
- run-cypress
```
+
+
+
+
+```diff title="buildspec.yaml"
+phases:
+ install:
+ runtime-versions:
+ nodejs: latest
+ commands:
+ # Set COMMIT_INFO variables to send Git specifics to Cypress Cloud when recording
+ # https://docs.cypress.io/app/continuous-integration/overview#Git-information
+ - export COMMIT_INFO_BRANCH="$(git rev-parse HEAD | xargs git name-rev |
+ cut -d' ' -f2 | sed 's/remotes\/origin\///g')"
+ - export COMMIT_INFO_MESSAGE="$(git log -1 --pretty=%B)"
+ - export COMMIT_INFO_EMAIL="$(git log -1 --pretty=%ae)"
+ - export COMMIT_INFO_AUTHOR="$(git log -1 --pretty=%an)"
+ - export COMMIT_INFO_SHA="$(git log -1 --pretty=%H)"
+ - export COMMIT_INFO_REMOTE="$(git config --get remote.origin.url)"
+ - npm ci
+ pre_build:
+ commands:
+ - npm run cypress:verify
+ - npm run cypress:info
+ build:
+ commands:
+ - CYPRESS_INTERNAL_ENV=staging CYPRESS_PROJECT_ID=[slug] npx cypress run --record --key [KEY]
++ post_build:
++ commands:
++ - npm install --force https://cdn.cypress.io/extract-cloud-results/v1/extract-cloud-results.tgz
++ - CYPRESS_INTERNAL_ENV=staging CYPRESS_PROJECT_ID=[slug] CYPRESS_RECORD_KEY=[KEY] node ./scripts/verifyAccessibilityResults.js
+```
+
diff --git a/docs/partials/_attributefilters.mdx b/docs/partials/_attributefilters.mdx
new file mode 100644
index 0000000000..91474d0613
--- /dev/null
+++ b/docs/partials/_attributefilters.mdx
@@ -0,0 +1,183 @@
+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
+
+```json
+{
+ "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.
+
+| 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
+
+```json
+{
+ "uiCoverage": {
+ "attributeFilters": [
+ {
+ "attribute": "id",
+ "value": ":r.*:",
+ "include": false
+ }
+ ]
+ }
+}
+```
+
+#### HTML
+
+```xml
+
+
+
+
+```
+
+#### Elements shown in UI Coverage
+
+```
+[name="my-button"]
+[name="other-button"]
+```
+
+---
+
+### Excluding auto-generated attribute names
+
+```json
+{
+ "uiCoverage": {
+ "attributeFilters": [
+ {
+ "attribute": "ng-include-me",
+ "value": ".*",
+ "include": true
+ },
+ {
+ "attribute": "ng-.*",
+ "value": ".*",
+ "include": false
+ }
+ ]
+ }
+}
+```
+
+#### HTML
+
+```xml
+
+
+
+
+```
+
+#### 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
+
+
+```
+
+#### Elements shown in UI Coverage
+
+```
+.user (2 instances)
+```
+
+### Filtering related dynamic attributes
+
+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
+
+```json
+{
+ "uiCoverage": {
+ "attributeFilters": [
+ {
+ "attribute": "id|for|name|aria-.*",
+ "value": "dynamic-.*",
+ "include": false
+ }
+ ]
+ }
+}
+```
+
+#### HTML
+
+```xml
+
+
+
+
Enter your first name
+
+```
+
+#### Elements shown in UI Coverage
+
+```
+label
+input
+p
+```
diff --git a/docs/partials/_elementfilters.mdx b/docs/partials/_elementfilters.mdx
index ab84b9e918..a71b966a0a 100644
--- a/docs/partials/_elementfilters.mdx
+++ b/docs/partials/_elementfilters.mdx
@@ -2,17 +2,17 @@ The `elementFilters` property allows you to specify selectors for elements that
## Why use element filters?
+- **Ignoring 3rd Party Components**: Libraries or widgets that are not part of your application logic may be excluded from reports.
+- **Streamlining Reports**: Reducing noise by filtering out non-essential elements makes reports more actionable.
+
+## Syntax
+
:::info
**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.
:::
-- **Ignoring 3rd Party Components**: Libraries or widgets that are not part of your application logic may be excluded from reports.
-- **Streamlining Reports**: Reducing noise by filtering out non-essential elements makes reports more actionable.
-
-## Syntax
-
```json
{
"elementFilters": [
diff --git a/docs/partials/_significantattributes.mdx b/docs/partials/_significantattributes.mdx
new file mode 100644
index 0000000000..4c67dc3715
--- /dev/null
+++ b/docs/partials/_significantattributes.mdx
@@ -0,0 +1,138 @@
+The `significantAttributes` property allows you to specify which attributes should be considered significant for UI Coverage analysis.
+
+## Why use significant attributes?
+
+- **Focus on Important Changes**: Track attributes that are most relevant to user interaction and functionality
+- **Reduce False Positives**: Avoid flagging changes in non-essential attributes as coverage issues
+- **Improve Report Clarity**: Make coverage reports more meaningful by focusing on attributes that matter
+
+## Scope
+
+:::info
+**Note:** setting `significantAttributes` 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
+
+```json
+{
+ "significantAttributes": [
+ {
+ "selector": string,
+ "attributes": string[]
+ }
+ ]
+}
+```
+
+### Options
+
+The first `significantAttributes` rule for which the selector property matches the element is used to determine which attributes should be considered significant. Attributes that do not match any rules are not considered significant by default.
+
+| Option | Required | Default | Description |
+| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. |
+| `attributes` | Required | | An array of attribute names that should be considered significant for coverage analysis. |
+
+## Examples
+
+### Marking specific attributes as significant for all elements
+
+#### Config
+
+```json
+{
+ "significantAttributes": [
+ {
+ "selector": "*",
+ "attributes": ["class", "id", "role"]
+ }
+ ]
+}
+```
+
+#### HTML
+
+```xml
+
+
+
+```
+
+#### Significant attributes tracked
+
+```
+class="primary", id="submit", role="button"
+```
+
+---
+
+### Marking different attributes as significant for different elements
+
+#### Config
+
+```json
+{
+ "significantAttributes": [
+ {
+ "selector": "input",
+ "attributes": ["type", "name", "required"]
+ },
+ {
+ "selector": "button",
+ "attributes": ["type", "disabled"]
+ }
+ ]
+}
+```
+
+#### HTML
+
+```xml
+
+
+
+
+```
+
+#### Significant attributes tracked
+
+```
+input: type="text", name="username", required="required"
+button: type="submit", disabled="disabled"
+```
+
+### Using attribute patterns
+
+#### Config
+
+```json
+{
+ "significantAttributes": [
+ {
+ "selector": "*",
+ "attributes": ["aria-*"]
+ }
+ ]
+}
+```
+
+#### HTML
+
+```xml
+
+
+ Content
+
+
+```
+
+#### Significant attributes tracked
+
+```
+aria-label="Main content", aria-hidden="false"
+```
diff --git a/docs/partials/_viewfilters.mdx b/docs/partials/_viewfilters.mdx
index 8fb7b26b78..409f9beb10 100644
--- a/docs/partials/_viewfilters.mdx
+++ b/docs/partials/_viewfilters.mdx
@@ -1,18 +1,22 @@
-By default, every URL visited within a test run is included in reports. However, not all URLs are relevant for your analysis. The `viewFilters` property allows you to specify patterns for URLs that should be excluded, ensuring your reports focus on meaningful parts of your application. Excluding a URL also excludes all links pointing to that URL.
+By default, every URL visited within a test run is included in reports. However, not all URLs are relevant for your analysis. The `viewFilters` property allows you to specify patterns for URLs that should be excluded, ensuring your reports focus on meaningful parts of your application.
+
+In UI Coverage, excluding a URL excludes all application snapshots from that URL from the reports, and **also** excludes all links pointing to that URL from being counted towards coverage scores.
## Why use view filters?
+- **Exclude Third-Party URLs**: If your application integrates with third-party services, you might want to exclude their URLs from analysis.
+- **Exclude Admin Pages**: URLs that are not part of the user-facing application, such as admin pages, could be excluded from reports.
+- **Reduce Noise**: Certain URLs visited during tests (e.g., error pages or redirects) may not represent meaningful user flows. Exclude these to clean up your reports.
+- **Optimize Performance**: Filtering out irrelevant URLs reduces the amount of data processed, speeding up analysis and improving report readability.
+
+## Scope
+
:::info
**Note:** setting `viewFilters` impacts both Accessibility and UI Coverage reports.
Nesting this property under an `accessibility` or `uiCoverage` key is
supported, if you need to split them up.
:::
-- **Exclude Third-Party URLs**: If your application integrates with third-party services, you might want to exclude their URLs from analysis.
-- **Exclude Admin Pages**: URLs that are not part of the user-facing application, such as admin pages, could be excluded from reports.
-- **Reduce Noise**: Certain URLs visited during tests (e.g., error pages or redirects) may not represent meaningful user flows. Exclude these to clean up your reports.
-- **Optimize Performance**: Filtering out irrelevant URLs reduces the amount of data processed, speeding up analysis and improving report readability.
-
## Syntax
```json
diff --git a/docs/ui-coverage/configuration/attributefilters.mdx b/docs/ui-coverage/configuration/attributefilters.mdx
index 9e3907e906..6cb1ce3555 100644
--- a/docs/ui-coverage/configuration/attributefilters.mdx
+++ b/docs/ui-coverage/configuration/attributefilters.mdx
@@ -2,186 +2,15 @@
title: 'Attribute Filters | Cypress UI Coverage'
description: 'The `attributeFilters` configuration property allows users to specify patterns for attributes and their values that should not be used for identifying and grouping elements.'
sidebar_label: attributeFilters
+sidebar_position: 60
---
# attributeFilters
-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.
+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.
-By using `attributeFilters`, you can ensure UI Coverage selects more appropriate identifiers, leading to cleaner and more accurate coverage reports.
+{' '}
-## 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 coverage reports, making them easier to interpret and act upon.
-
-## Syntax
-
-```json
-{
- "uiCoverage": {
- "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.
-
-| 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
-
-```json
-{
- "uiCoverage": {
- "attributeFilters": [
- {
- "attribute": "id",
- "value": ":r.*:",
- "include": false
- }
- ]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-
-
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-[name="my-button"]
-[name="other-button"]
-```
-
----
-
-### Excluding auto-generated attribute names
-
-```json
-{
- "uiCoverage": {
- "attributeFilters": [
- {
- "attribute": "ng-include-me",
- "value": ".*",
- "include": true
- },
- {
- "attribute": "ng-.*",
- "value": ".*",
- "include": false
- }
- ]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-
-
-
-```
-
-#### 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
-
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-.user (2 instances)
-```
-
-### Filtering related dynamic attributes
-
-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
-
-```json
-{
- "uiCoverage": {
- "attributeFilters": [
- {
- "attribute": "id|for|name|aria-.*",
- "value": "dynamic-.*",
- "include": false
- }
- ]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-
-
-
Enter your first name
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-label
-input
-p
-```
+
diff --git a/docs/ui-coverage/configuration/elementfilters.mdx b/docs/ui-coverage/configuration/elementfilters.mdx
index 1157bf43f8..e620147647 100644
--- a/docs/ui-coverage/configuration/elementfilters.mdx
+++ b/docs/ui-coverage/configuration/elementfilters.mdx
@@ -2,6 +2,7 @@
title: 'Element Filters | Cypress UI Coverage'
description: 'The `elementFilters` property allows you to specify selectors for elements that should be excluded from UI Coverage.'
sidebar_label: elementFilters
+sidebar_position: 40
---
diff --git a/docs/ui-coverage/configuration/elementgroups.mdx b/docs/ui-coverage/configuration/elementgroups.mdx
index 9ed36289d6..812fde8ed6 100644
--- a/docs/ui-coverage/configuration/elementgroups.mdx
+++ b/docs/ui-coverage/configuration/elementgroups.mdx
@@ -2,6 +2,7 @@
title: 'Element Groups | Cypress UI Coverage'
description: 'The `elementGroups` configuration allows you to group elements in UI Coverage using custom logic.'
sidebar_label: elementGroups
+sidebar_position: 80
---
diff --git a/docs/ui-coverage/configuration/elements.mdx b/docs/ui-coverage/configuration/elements.mdx
index d5edff34d6..d768403c03 100644
--- a/docs/ui-coverage/configuration/elements.mdx
+++ b/docs/ui-coverage/configuration/elements.mdx
@@ -2,6 +2,7 @@
title: 'Elements | Cypress UI Coverage'
description: 'The `elements` configuration allows you to uniquely identify elements in UI Coverage using custom logic.'
sidebar_label: elements
+sidebar_position: 70
---
diff --git a/docs/ui-coverage/configuration/significantattributes.mdx b/docs/ui-coverage/configuration/significantattributes.mdx
index 90256c3bf5..9518e13cf2 100644
--- a/docs/ui-coverage/configuration/significantattributes.mdx
+++ b/docs/ui-coverage/configuration/significantattributes.mdx
@@ -2,121 +2,11 @@
title: 'Significant Attributes | Cypress UI Coverage'
description: 'The `significantAttributes` configuration property allows users to specify custom attributes that should be considered "significant" for the purpose of identification and grouping in UI Coverage.'
sidebar_label: significantAttributes
+sidebar_position: 50
---
# significantAttributes
-UI Coverage provides logic to automatically [identify](/ui-coverage/core-concepts/element-identification) and [group](/ui-coverage/core-concepts/element-grouping) elements based on their attributes and DOM structure. However, your application may rely on custom attributes for identification that are not prioritized by default in UI Coverage. The `significantAttributes` configuration allows you to specify these attributes, ensuring accurate identification and grouping.
-
-## Why use significant attributes?
-
-- **Handle Custom Identifiers**: Prioritize custom attributes like `data-custom-id` that are essential for identifying elements in your application.
-- **Avoid Misclassification**: In cases where elements share generic attributes like class or name, prioritizing more specific attributes prevents incorrect grouping.
-- **Streamline Dynamic Elements**: Attributes that change dynamically can disrupt accurate identification. Specifying significant attributes ensures stability.
-
-## Syntax
-
-```json
-{
- "uiCoverage": {
- "significantAttributes": [
- string
- ]
- }
-}
-```
-
-### Options
-
-The attributes listed in `significantAttributes` are considered "significant" and are prioritized above the default significant attributes, but below `data-cy-ui-id` and `data-cy-ui-group`, for the purpose of identification and grouping.
-
-| Option | Required | Default | Description |
-| ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `significantAttributes` | Required | | An array of attribute names to prioritize for element identification and grouping.Supports any valid HTML attribute names. |
-
-## Examples
-
-### Consider a custom attribute significant
-
-#### Config
-
-```json
-{
- "uiCoverage": {
- "significantAttributes": ["data-role"]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-[data-role="email"]
-[data-role="interests"] (2 instances)
-```
-
-### Prioritize stable attributes over dynamic
-
-#### Config
-
-```json
-{
- "uiCoverage": {
- "significantAttributes": ["data-type"]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-
Search
-
Filter
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-[data-type="search"]
-[data-type="filter"]
-```
-
-### Define aria attributes as significant
-
-#### Config
-
-```json
-{
- "uiCoverage": {
- "significantAttributes": ["aria-label"]
- }
-}
-```
-
-#### HTML
-
-```xml
-
-
-```
-
-#### Elements shown in UI Coverage
-
-```
-[aria-label="Close"]
-[data-cy="submit"]
-```
+
diff --git a/docs/ui-coverage/configuration/viewfilters.mdx b/docs/ui-coverage/configuration/viewfilters.mdx
index 37ad9576ec..db2f68c8d1 100644
--- a/docs/ui-coverage/configuration/viewfilters.mdx
+++ b/docs/ui-coverage/configuration/viewfilters.mdx
@@ -2,6 +2,7 @@
title: 'View Filters | Cypress UI Coverage'
description: 'The `viewFilters` property allows you to specify URL patterns for URLs that should be excluded from UI Coverage.'
sidebar_label: viewFilters
+sidebar_position: 30
---
diff --git a/docs/ui-coverage/configuration/views.mdx b/docs/ui-coverage/configuration/views.mdx
index 7beada406d..313215b57c 100644
--- a/docs/ui-coverage/configuration/views.mdx
+++ b/docs/ui-coverage/configuration/views.mdx
@@ -2,6 +2,7 @@
title: 'Views | Cypress UI Coverage'
description: 'The `views` configuration allows you to group URLs in UI Coverage using custom logic.'
sidebar_label: views
+sidebar_position: 20
---
diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js
index 7278cf3b90..20a4edcb49 100644
--- a/src/theme/MDXComponents.js
+++ b/src/theme/MDXComponents.js
@@ -2,6 +2,7 @@
import MDXComponents from "@theme-original/MDXComponents";
import AnatomyOfAnError from "@site/docs/partials/_anatomy-of-an-error.mdx";
import AccessibilityPremiumNote from "@site/docs/partials/_accessibility-premium-note.mdx";
+import AttributeFilters from "@site/docs/partials/_attributefilters.mdx";
import AutoCancellationBenefits from "@site/docs/partials/_auto-cancellation-benefits.mdx";
import Badge from "@site/src/components/badge";
import Btn from "@site/src/components/button";
@@ -27,6 +28,7 @@ import Icon from "@site/src/components/icon";
import ImportMountFunctions from "@site/docs/partials/_import-mount-functions.mdx";
import IntellisenseCodeCompletion from "@site/docs/partials/_intellisense-code-completion.mdx";
import ProductHeading from "@site/src/components/product-heading";
+import SignificantAttributes from "@site/docs/partials/_significantattributes.mdx";
import SourceMaps from "@site/docs/partials/_source-maps.mdx";
import SupportFileConfiguration from "@site/docs/partials/_support-file-configuration.mdx";
import Tabs from "@theme/Tabs";
@@ -164,6 +166,7 @@ export default {
...MDXComponents,
AnatomyOfAnError,
AccessibilityPremiumNote,
+ AttributeFilters,
AutoCancellationBenefits,
Badge,
Btn,
@@ -188,6 +191,7 @@ export default {
ImportMountFunctions,
IntellisenseCodeCompletion,
ProductHeading,
+ SignificantAttributes,
SourceMaps,
SupportFileConfiguration,
Tabs,
diff --git a/static/img/accessibility/core-concepts/added-views.png b/static/img/accessibility/core-concepts/added-views.png
new file mode 100644
index 0000000000..6ecff0511b
Binary files /dev/null and b/static/img/accessibility/core-concepts/added-views.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-a11y-detail-view.png b/static/img/accessibility/core-concepts/branch-review-a11y-detail-view.png
new file mode 100644
index 0000000000..ace1399367
Binary files /dev/null and b/static/img/accessibility/core-concepts/branch-review-a11y-detail-view.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-a11y-empty-state.png b/static/img/accessibility/core-concepts/branch-review-a11y-empty-state.png
new file mode 100644
index 0000000000..c9cae6b84e
Binary files /dev/null and b/static/img/accessibility/core-concepts/branch-review-a11y-empty-state.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-a11y-new-failed.png b/static/img/accessibility/core-concepts/branch-review-a11y-new-failed.png
new file mode 100644
index 0000000000..cb14cd6990
Binary files /dev/null and b/static/img/accessibility/core-concepts/branch-review-a11y-new-failed.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-a11y-resolved-elements.png b/static/img/accessibility/core-concepts/branch-review-a11y-resolved-elements.png
new file mode 100644
index 0000000000..4e783a585b
Binary files /dev/null and b/static/img/accessibility/core-concepts/branch-review-a11y-resolved-elements.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-example-diff.png b/static/img/accessibility/core-concepts/branch-review-example-diff.png
index 847e09417c..03e99301d9 100644
Binary files a/static/img/accessibility/core-concepts/branch-review-example-diff.png and b/static/img/accessibility/core-concepts/branch-review-example-diff.png differ
diff --git a/static/img/accessibility/core-concepts/branch-review-intro.png b/static/img/accessibility/core-concepts/branch-review-intro.png
deleted file mode 100644
index 4ae8b75a71..0000000000
Binary files a/static/img/accessibility/core-concepts/branch-review-intro.png and /dev/null differ
diff --git a/static/img/accessibility/core-concepts/removed-views.png b/static/img/accessibility/core-concepts/removed-views.png
new file mode 100644
index 0000000000..34a81798a8
Binary files /dev/null and b/static/img/accessibility/core-concepts/removed-views.png differ