Add Cypress Accessibility Branch Review documentation

docs/accessibility/changelog.mdx

@@ -9,6 +9,14 @@ sidebar_position: 200
 
 # Changelog
 
+## Week of 2/24/2025
+
+- [Cypress Accessibility Branch Review](/accessibility/core-concepts/comparing-reports) has entered beta. Read the docs to learn how to compare runs and automatically spot newly introduced issues.
+
+## Week of 1/13/2025
+
+- Cypress Accessibility results are now included in the Enterprise Reporting area of Cypress Cloud. Filter by project and branch and see trends over time.
+
 ## Week of 11/11/2024
 
 - A "Share Issue" button has been added to the element details section for each reported rule violation. This allows for easily copying the key details and related links for a particular issue into your clipboard to add to a message or to a ticket in your issue tracking system.

docs/accessibility/core-concepts/accessibility-score.mdx

@@ -2,7 +2,7 @@
 title: 'Accessibility score | Cypress Documentation'
 description: 'Cypress produces a top-line percentage score that indicates a general sense of accessibility for a project.'
 sidebar_label: Accessibility score
-sidebar_position: 30
+sidebar_position: 40
 ---
 
 <ProductHeading product="accessibility" />
@@ -19,7 +19,7 @@ _Note: WCAG standards do not categorize Success Criteria by severity; all failur
 
 ## Scoring algorithm
 
-The accessibility score calculation applies the following weights:
+The accessibility score calculation applies the following weights to failed accessibility checks in a snapshot.
 
 | Severity of Issue | Weight |
 | ----------------- | ------ |
@@ -36,6 +36,8 @@ The accessibility score calculation applies the following weights:
 - Calculate the total weight of failed checks.
 - Compute the score as: `Score = (Passed Weights) / (Passed Weights + Failed Weights)`
 
+**Note**: Incomplete and Ignored element statuses do not have any effect on your score. Only clear failures of a rule are counted.
+
 2. **View Score:**
 
 - Average the scores of all snapshots within the View.

docs/accessibility/core-concepts/comparing-reports.mdx

@@ -0,0 +1,108 @@
+---
+title: 'Comparing Accessibility Reports | Cypress Documentation'
+description: 'Review the main areas to pay attention to when first reviewing an accessibility report for a Cypress run.'
+sidebar_position: 40
+sidebar_label: Compare reports
+---
+
+<ProductHeading product="accessibility" />
+
+# Compare reports
+
+Accessibility reports from different runs can be compared in the [Branch Review](/cloud/features/branch-review#Getting-Started) area of Cypress Cloud. This allows you to instantly see if any new issues have been introduced, and drill in to see full-page HTML and CSS snapshots showing only the new issues.
+
+See the video below for an example of using Branch Review in a Pull Request:
+
+<DocsVideo
+  src="https://www.youtube.com/embed/k3vq57O4P4M"
+  title="Accessibility branch review demo"
+/>
+
+## Use cases
+
+Comparing the results from different runs is useful in multiple scenarios.
+
+**Key use cases:**
+
+- **Pre-merge checks**: Know if any net-new issues are introduced by UI code changes.
+- **Monitoring changes**: Compare nightly monitoring runs and track down the introduction of new problems caused by underlying changes in the application.
+- **Detecting content issues**: Sometimes content editors can introduce accessibility issues unrelated to code changes. Seeing the example issues presented visually, in context, helps you quickly triage whether you are dealing with a recent code change issue, or a content authorship problem.
+- **Reviewing AI-generated code changes**: The increased use of AI to generate and/or review front-end code creates some increased risks of accessibility regressions making it to production. The increase or decrease of accessibility issues when reviewing a pull request helps you understand the impact of the change.
+- **Tracing the introduction of issues**: With dropdowns for each run, it's easy to rapidly compare different A and B runs to find the exact commit that introduced a problem.
+- **Demonstrating the resolution of issues**: Confirm the effect of your improvements, and share overview with your team to more quickly review code changes.
+
+## Content of the report
+
+<DocsImage
+  src="/img/accessibility/core-concepts/branch-review-intro.png"
+  alt="Cypress Accessibility Branch Review with arrows calling out the sections for new failed rules, resolved rules, and failed rules with changes. New failed rules are defined as rules that just started failing on the new branch. Resolved rules are defined as rules that got fully fixed in the new branch. Failed rules with changes are defined as rules that failed on both branches, but with different element counts or different related pages."
+  noBorder={true}
+/>
+
+The Branch Review report is prioritized into three 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.
+
+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.
+
+## How to compare runs
+
+The first step is to get to the Branch Review area of Cypress Cloud, which will let you compare one branch against another - or different runs on the same branch, if needed. We refer to be baseline fun for comparison as the `base` run, and the changes we are comparing with as the `changed` run.
+
+There are a number of ways to get to Branch Review depending on where you are looking at your Cypress results. In all cases, once you've picked a `changed` run, you can adjust the automatically-selected `base` run to any branch or run in the project.
+
+### From a Pull Request
+
+<DocsImage
+  src="/img/accessibility/core-concepts/branch-review-pull-request.png"
+  alt="A pull request comment from Cypress with an arrow pointing to the 'View all changes introduced in this branch' link. Test results and some accessibility score and violation information is also visible in the comment. The project has an 86.86% accessibility score, with  9 failed elements. Failed rule counts are 1 critical, 1 serious, 3 moderate, and 0 minor."
+/>
+
+Click the "View all changes introduced in this branch" link at the bottom of the Test Results table. You will enter branch review with the current PR's branch and latest run pre-selected as the "changed" run.
+
+### From the run list
+
+Click the branch name associated with the run. This will take you to Branch Review with that branch's newest run pre-selected as the `changed` run.
+
+<DocsImage
+  src="/img/accessibility/core-concepts/branch-review-run-card.png"
+  alt="A couple of cards showing various details about Cypress test runs, including pass/fail counts and metadata. An arrow points to the branch name."
+/>
+
+### From the project list
+
+<DocsImage
+  src="/img/accessibility/core-concepts/branch-review-project-card.png"
+  width="40%"
+  alt="A card showing the name of an example project and related branches to choose."
+/>
+
+The project card shows three active branches for the project. You can click through to any of these to enter Branch Review with the newest run on that branch pre-selected as the `changed` run.
+
+### From the main navigation
+
+<DocsImage
+  src="/img/accessibility/core-concepts/branch-review-side-nav.png"
+  width="40%"
+  alt="The main Cypress Cloud navigation showing Latest Runs, Branches, and Analytics menu items. An arrow points to Branches."
+/>
+
+When inside of a project, you can select "Branches" in the main navigation to see a full, filterable list of available branches and choose one to set as the `changed` run.
+
+## FAQ
+
+### How do I ensure a good comparison?
+
+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.
+
+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.
+
+### What is the purpose of the Beta label?
+
+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 hit the feedback button and let us know.
+
+### Why do I see some views (pages or components) changing from run-to-run?
+
+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.

docs/accessibility/core-concepts/how-it-works.mdx

@@ -2,7 +2,7 @@
 title: 'Cypress Accessibility | How it works'
 description: 'Accessibility checks are powered by Axe Core® from Deque Systems based on common accessibility standards.'
 sidebar_label: 'How it works'
-sidebar_position: 40
+sidebar_position: 50
 ---
 
 <ProductHeading product="accessibility" />
@@ -11,11 +11,11 @@ sidebar_position: 40
 
 Cypress Accessibility seamlessly integrates accessibility testing into your development pipeline. Below are the stages of the Cypress Accessibility process:
 
-1. **Recording and Uploading**: As your test run is recorded, specs are uploaded to Cypress Cloud. Accessibility checks begin based on incoming [Test Replay](/cloud/features/test-replay) data on Cypress Cloud servers.
+1. **Recording and uploading**: As your test run is recorded, specs are uploaded to Cypress Cloud. Accessibility checks begin based on incoming [Test Replay](/cloud/features/test-replay) data on Cypress Cloud servers.
 1. **Processing**: When your run completes, the final specs are processed for accessibility checks. Earlier specs have already entered processing and are likely completed by the end of the run.
 1. **Organizing Views**: Cypress Cloud groups Views (pages and components) rendered during the run, merging and deduplicating across tests. This ensures page-level results and live DOM snapshots are organized effectively.
-1. **Generating Reports**: A combined "rule-level" report is created, summarizing all detected accessibility violations.
-1. **Displaying Results**: Results are displayed in Cypress Cloud, flagged in integrations (e.g., Slack, GitHub/GitLab comments), and accessible via the Results API for optional CI pipeline actions (e.g., failing builds based on unmet standards).
+1. **Generating reports**: A combined "rule-level" report is created, summarizing all detected accessibility violations.
+1. **Displaying results**: Results are displayed in Cypress Cloud in the run details area as well as in [Branch Review](/accessibility/core-concepts/comparing-reports) for comparing runs. Accessibility is also flagged in integrations (e.g., Slack, GitHub/GitLab comments), and accessible via the [Results API](/accessibility/results-api) for optional CI pipeline actions (e.g., failing builds based on unmet standards).
 
 ## About Axe Core®
 
@@ -33,7 +33,7 @@ The value of this form of testing in Cypress Accessibility is to give you fast,
 
 Axe Core® is regularly updated, with Cypress following a controlled adoption process:
 
-- Update Policy: Cypress Cloud integrates new Axe Core® versions at least 30 days after their release. This provides teams time to review the Cypress Accessibility [changelog](https://github.com/dequelabs/axe-core/blob/develop/CHANGELOG.md) so you can make any necessary adjustments to your process in advance of Cypress Cloud bumping the version.
+- Update Policy: Cypress Cloud integrates new Axe Core® versions at least 30 days after their release. This provides teams time to review the Axe Core® [changelog](https://github.com/dequelabs/axe-core/blob/develop/CHANGELOG.md) so you can make any necessary adjustments to your process in advance of Cypress Cloud bumping the version.
 - Changelog Tracking: Updates are documented in the Cypress Accessibility [changelog](https://github.com/dequelabs/axe-core/blob/develop/CHANGELOG.md), starting December 1, 2024.
 - Critical Exceptions: In cases like critical security patches, updates may occur sooner, with notifications provided to affected customers.
 

docs/accessibility/core-concepts/inspecting-violation-details.mdx

@@ -1,7 +1,7 @@
 ---
 title: 'Inspecting accessibility violation details | Cypress Documentation'
 description: 'Learn how to inspect the details of an accessibility violation and its severity in Cypress.'
-sidebar_label: Inspecting violation details
+sidebar_label: Inspect violation details
 sidebar_position: 20
 ---
 

docs/accessibility/get-started/introduction.mdx

@@ -13,7 +13,7 @@ sidebar_custom_props: { 'new_label': true }
 Instantly visualize, triage, and fix accessibility violations without any additional code or configuration.
 Dive deep into each violation with live, fully-rendered DOM snapshots of your application as it appeared during your tests.
 Track your team's progress over time with historical scores to monitor improvements and identify regressions.
-Looking for a general guide for Accessibility testing in Cypress App? [Go here](/app/guides/accessibility-testing).
+Looking for a general guide for accessibility testing concepts in Cypress App? Go to the [accessibility testing guide](/app/guides/accessibility-testing).
 
 <Btn
   label="Request trial ➜"
@@ -152,18 +152,18 @@ From there, you can integrate with CI to set your own standards for handling the
   </li>
 </ul>
 
-## How it Works
+## What to expect
 
 Cypress Accessibility delivers detailed, actionable accessibility reports directly from your tests, powered by the industry-leading Axe Core® library by Deque Systems. These reports require no extra setup and are automatically generated for every unique state reached during your Cypress tests, whether in end-to-end or component testing.
 
-- **Effortless Setup**: Cypress Accessibility utilizes the same capture protocol as [Test Replay](/cloud/features/test-replay) (requires Cypress v13+), so no additional code or configuration is needed.
-- **Performance-Friendly**: Server-side execution ensures no impact on test performance or existing code.
-- **Comprehensive Reporting**: During test execution, unique states—defined by distinct DOM structures—are recorded for end-to-end views and components.
-- **DOM Snapshots**: Each detected violation is accompanied by a full-page, inspectable DOM snapshot, highlighting the exact location and context of the violation.
-- **Rule Compliance**: Violations are mapped directly to WCAG 2.1 criteria, making it easier to prioritize and remediate issues.
-- **Report Generation**: [Detailed reports](/accessibility/core-concepts/run-level-reports) are generated, offering sortable and filterable views by page, component, or the entire test run. Rule-based summaries for an aggregated view of accessibility outcomes for the entire run are also available.
-- **Selective Element Handling**: Elements marked as "ignored" in tests are excluded from scoring but remain visible for manual review, ensuring flexibility via [configuration](/accessibility/configuration/overview).
-- **Configurable CI Integration**: The [Results API](/accessibility/results-api) allows you to programmatically control your CI pipeline's behavior based on accessibility outcomes, enabling enforcement of accessibility policies.
+- **Effortless setup**: Cypress Accessibility utilizes the same capture protocol as [Test Replay](/cloud/features/test-replay) (requires Cypress v13+), so no additional code or configuration is needed.
+- **No test slowdown or flakiness**: Server-side execution ensures no impact on test performance or existing code.
+- **Comprehensive reporting**: During test execution, unique states—defined by distinct DOM structures—are recorded for end-to-end views and components.
+- **DOM snapshots**: Each detected violation is accompanied by a [full-page, inspectable DOM snapshot](/accessibility/core-concepts/inspecting-violation-details), highlighting the exact location and context of the violation.
+- **Report generation**: [Detailed reports](/accessibility/core-concepts/run-level-reports) are generated, offering sortable and filterable views by page, component, or the entire test run. Rule-based summaries for an aggregated view of accessibility outcomes for the entire run are also available.
+- **Run comparison**: Compare the results from two runs and see only the new issues. Know before you merge if a code change is going to cause new accessibility problems.
+- **Selective element handling**: Elements marked as "ignored" in tests are excluded from scoring but remain visible for manual review, ensuring flexibility via [configuration](/accessibility/configuration/overview).
+- **Flexible pipeline integration**: The [Results API](/accessibility/results-api) allows you to programmatically control your CI pipeline's behavior based on accessibility outcomes, enabling enforcement of accessibility policies.
 
 Learn more about [how it works](/accessibility/core-concepts/how-it-works).
 

docs/accessibility/guides/improve-accessibility.mdx

@@ -54,6 +54,10 @@ Since every violation in Cypress is linked to a Deque University page with detai
 
 Even if your first rule is not "Buttons must have discernible text", we suggest finding one with a similarly small amount of coordination or understanding needed to fix, so the team can experience success as quickly as possible.
 
+## Check your changes in Branch Review
+
+One of the most frustrating experiences in accessibility is fixing one issue, only to discover you introduced some other issue in the process. Especially if the feedback cycles are long, it can reduce everybody's confidence in the remediation process. Wen making changes to improve accessibility, you can use [Branch Review](/cloud/features/branch-review#Getting-Started) to see the effect of your solutions - including seeing any increase in issues that might be related to your code changes.
+
 ## Setting achievable goals
 
 Define a clear objective for each effort, such as fixing all violations of a specific rule within a defined scope. For example: