diff --git a/docs/accessibility/changelog.mdx b/docs/accessibility/changelog.mdx index cb88a85e4e..199416b3d4 100644 --- a/docs/accessibility/changelog.mdx +++ b/docs/accessibility/changelog.mdx @@ -9,6 +9,18 @@ sidebar_position: 200 # Changelog +## Week of 10/13/2025 + +- Individual rules, or set of rules, can now be ignored for specific elements using [a `data-a11y-ignore` attribute](/accessibility/configuration/ignoring-rules-per-element). + +## Week of 10/6/2025 + +- False positives in ["Interactive elements should be semantically correct"](/accessibility/core-concepts/cypress-rules#Interactive-elements-should-be-semantically-correct) related to elements using the `contenteditable` attribute have been addressed. + +## Week of 7/7/2025 + +- A new custom accessibility rule, ["Interactive elements should be semantically correct"](/accessibility/core-concepts/cypress-rules#Interactive-elements-should-be-semantically-correct), is now available. This rule is based on the interactions that take place during your test execution, and helps detect accessibility issues that are not a part of typical DOM-based accessibility scans. + ## Week of 7/7/2025 - A new custom accessibility rule, ["Interactive elements should be semantically correct"](/accessibility/core-concepts/cypress-rules#Interactive-elements-should-be-semantically-correct), is now available. This rule is based on the interactions that take place during your test execution, and helps detect accessibility issues that are not a part of typical DOM-based accessibility scans. diff --git a/docs/accessibility/configuration/axe-core-configuration.mdx b/docs/accessibility/configuration/axe-core-configuration.mdx index 98f86a7442..8134ecaf62 100644 --- a/docs/accessibility/configuration/axe-core-configuration.mdx +++ b/docs/accessibility/configuration/axe-core-configuration.mdx @@ -1,6 +1,6 @@ --- title: 'Axe Core® configuration | Cypress Accessibility' -description: 'Configuration for Axe-Core® rules can be configured.' +description: 'Configuration for Axe-Core® rules.' sidebar_label: 'Axe Core® configuration' --- diff --git a/docs/accessibility/configuration/ignoring-rules-per-element.mdx b/docs/accessibility/configuration/ignoring-rules-per-element.mdx new file mode 100644 index 0000000000..9ff1f11e8f --- /dev/null +++ b/docs/accessibility/configuration/ignoring-rules-per-element.mdx @@ -0,0 +1,44 @@ +--- +title: 'Ignoring rules for specific elements | Cypress Accessibility' +description: 'Elements can avoid failing certain rules using a data-a11y-ignore attribute' +sidebar_label: 'Ignore rules for specific elements' +sidebar_position: 70 +--- + + + +# Ignore rules for specific elements + +Cypress Accessibility configuration allows you to exclude [elements](/accessibility/configuration/elementfilters) or whole [pages](/accessibility/configuration/viewfilters) from the accessibility report, but sometimes there are situations where you may want to keep an element in your accessibility report, but ignore some accessibility rules for that element. + +This can be accomplished in your application code using the `data-a11y-ignore` attribute, like this: + +```html + +``` + +This would mean that if a color contrast violation was detected on this button, it would be tracked and flagged as an ignored violation in your accessibility report, instead of being listed as a failure. Any other violations detected would be flagged as normal failures. + +## Ignore multiple rules + +Multiple rules can be ignored by using commas to separate a list of rule IDs: + +```html + +``` + +## Where to find rule IDs + +The "Learn more" link in your accessibility reports will display the ID for each rule. They can also be looked up in the [Axe-Core® rule documentation](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md) directly. + +## When to use this + +### Handle false positives + +This is most useful when there is a known false positive failure for a specific rule and you want to remove it from your report without losing all other insights about an element. + +The `data-a11y-ignore` attribute pattern is used in some libraries like Adobe's React Spectrum, so those UI elements automatically have the defined rules ignored correctly in Cypress Accessibility. + +### Avoid blocking a code change + +A secondary use case is to avoid certain known issues becoming blocking for a pull request. `data-a11y-ignore` allows for a minimal scope of what to ignore, and creates a paper trail through version control which means these changes are obvious at code review, and comments can be added nearby to explain the reason for ignoring the rule. diff --git a/docs/accessibility/core-concepts/run-level-reports.mdx b/docs/accessibility/core-concepts/run-level-reports.mdx index fb2e1b6440..8be03ada3f 100644 --- a/docs/accessibility/core-concepts/run-level-reports.mdx +++ b/docs/accessibility/core-concepts/run-level-reports.mdx @@ -55,7 +55,9 @@ The count of elements in a View categorized as: - **Failed:** Elements violating at least one rule. These affect your accessibility score. - **Inconclusive:** Elements had at least one check marked "incomplete" by Axe Core® during the run. These represent checks that couldn't be completed for technical reasons, or items that need manual review to confirm if there is an accessibility issue. These do not affect your accessibility score. -- **Ignored:** Elements with failed or incomplete checks that were excluded via CSS selectors in your [configuration](/accessibility/configuration/elementfilters) but still processed. They do not affect your accessibility score. +- **Ignored:** Elements with failed or incomplete checks that were excluded via CSS selectors in your [configuration](/accessibility/configuration/elementfilters), or through the `data-a11y-ignore` attribute. These elements are still processed in order to support your understanding of what is ignored. They do not affect your accessibility score. + +Each of these numbers can be clicked to navigate to a report filtered to just that set of findings. ### Failed rules diff --git a/docs/accessibility/results-api.mdx b/docs/accessibility/results-api.mdx index a55f6ffac5..c230ac672c 100644 --- a/docs/accessibility/results-api.mdx +++ b/docs/accessibility/results-api.mdx @@ -493,4 +493,9 @@ steps: ``` + +## Required CI environment variables + + + ``` diff --git a/docs/partials/_results-api-env-vars.mdx b/docs/partials/_results-api-env-vars.mdx new file mode 100644 index 0000000000..70dcaf1045 --- /dev/null +++ b/docs/partials/_results-api-env-vars.mdx @@ -0,0 +1,163 @@ +The `@cypress/extract-cloud-results` helper cross-references some environment variables from where it is executed with ones that were present when a Cypress Cloud run was recorded. This allows for automatically detecting the correct Cloud run when the Results API is invoked from the same CI context as a given run (as is the case in the above examples). + +For more complex setups, or for local iteration on your Results API handler code, it can be useful to know what variables Cypress is looking for so that you can make sure they are passed through where they are needed. + +Likewise, if you want to use the Results API locally to pull the data for a specific run (within the last 7 days), you can set these variables locally to match what was present in CI. + +## Local development example + +If you executed a run in GitHub Actions and it was recorded to Cypress Cloud, you would set these 4 environment variables to replicate the context of that run locally and execute your local handler script. This is a great way to iterate on your script and verify everything is working as expected, without having to integrate anything in CI. It's also useful for debugging. + +``` +CYPRESS_PROJECT_ID=AAA +CYPRESS_RECORD_KEY=BBB +GITHUB_ACTIONS=true +GITHUB_RUN_ID=111 +GITHUB_RUN_ATTEMPT=0 +node verifyAccessibilityResults.js +``` + +The Results API will then look for the Cypress Cloud run that matches this run ID. If there is more than one Cypress Cloud run found for that GitHub Actions Run, you can pass run tags to narrow down to one run's report. + +## Supported CI Provider Overview + +Each CI provider has a unique combination of components, patterns, and environment variables that must be interpreted by this module. + +### GitHub Actions + +Reference: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions + +#### Essential environment variables + +- `GITHUB_ACTIONS` - Presence identifies the environment as a GitHub Actions environment. +- `GITHUB_RUN_ID` - Value uniquely identifies a GitHub Actions workflow instance. Value does not change as jobs in the workflow are re-executed. +- `GITHUB_RUN_ATTEMPT` - Value identifies the workflow instance's attempt index. Value is incremented each time jobs are re-executed. + +Full environment variable reference: https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same workflow. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by either: + 1. Executing the module script in a separate job that is dependent upon the job that records the run (using the `needs: [job-name]` option in the config), or + 2. Executing the module script in serial with the cypress recording in the same job. + +### GitLab Pipelines + +Reference: https://docs.gitlab.com/ee/ci/pipelines/ + +#### Essential environment variables + +- `GITLAB_CI` - Presence identifies the environment as a GitLab CI environment +- `CI_PIPELINE_ID` - Value uniquely identifies a GitLab pipeline workflow. This value does not change as jobs in the pipeline are retried. +- `CI_JOB_NAME` - Value uniquely identifies a single job name within a pipeline. Ex. `run-e2e` +- `CI_JOB_ID` - Value uniquely identifies an execution instance of a job. This value will change each time a job is executed/re-executed. + +Full environment variable reference: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same pipeline. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by: + 1. Executing the module script in a separate job that is dependent upon the job that records the run (using the `needs: [job-name]` option in the config), or + 2. Executing the module script in a separate job that is executed in a lower stage than the job that records the Cypress run, or + 3. Executing the module script in serial with the cypress recording in the same job. + +### Jenkins + +Reference: https://www.jenkins.io/doc/ + +Jenkins is heavily customizable through the usage of plugins, which limits the amount of assumptions we can make about available environment variables and overall behavior. + +We have implemented Jenkins support within this module using the broadest set of available default values. For the purposes of this documentation, though, we will discuss terms related to Jenkins Pipeline support: https://www.jenkins.io/doc/book/pipeline/getting-started/ + +#### Essential terms + +#### Essential environment variables + +- `JENKINS_HOME` - Presence identifies the environment as a Jenkins environment +- `BUILD_URL` - Value uniquely identifies a Jenkins job execution, including name and id characteristics. + +Full environment variable reference: https://www.jenkins.io/doc/book/pipeline/jenkinsfile/#using-environment-variables + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same job. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by executing the module script in serial with the cypress recording in the same job. + +### Azure + +Reference: https://learn.microsoft.com/en-us/azure/devops/pipelines/get-started/key-pipelines-concepts?view=azure-devops + +> Note: Cypress v13.13.1 is the earliest Cypress release that records the environment variables necessary for this module to identify runs in an Azure environment. Previous Cypress versions are not supported in Azure pipelines. + +#### Essential environment variables + +- `TF_BUILD` and `AZURE_HTTP_USER_AGENT` - Combined presence identifies the environment as a Azure pipeline environment. +- `SYSTEM_PLANID` - Value uniquely identifies a pipeline run. Value does not change as jobs within the pipeline are retried from failure. +- `SYSTEM_JOBID` - Value uniquely identifies a job execution. Value changes each time a job is retried from failure, in conjunction with the `SYSTEM_JOBATTEMPT` being incremented. +- `SYSTEM_JOBATTEMPT` - Value identifies the pipelines shared attempt index. Value is incremented when jobs are retried from failure. + +Full environment variable reference: https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same pipeline run (i.e. they share a `SYSTEM_PLANID` value). +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by either: + 1. Executing the module script in a separate job that is dependent upon the job that records the run (using the `dependsOn: [job-name]` option in the config), or + 2. Executing the module script in serial with the Cypress recording in the same job. + +### CircleCI + +Reference: https://circleci.com/docs/about-circleci/ + +> Note: Cypress v13.13.1 is the earliest Cypress release that records the environment variables necessary for this module to identify runs in an CircleCI environment. Previous Cypress versions are not supported in CircleCI pipelines. + +#### Essential environment variables + +- `CIRCLECI` - Presence identifies the environment as a CircleCI environment +- `CIRCLE_PIPELINE_ID` - Value uniquely identifies a CircleCI pipeline, created on push or manually triggered through the UI. This value does not change as workflows within the pipeline are re-executed. +- `CIRCLE_WORKFLOW_ID` - Value uniquely identifies an instance of a workflow's execution within a pipeline. This value will be updated upon each workflow execution; in other words, retrying a workflow from failure from the Circle UI will create a new workflow with a new `CIRCLE_WORKFLOW_ID` value available to the jobs executed within it. +- `CIRCLE_WORKFLOW_JOB_ID` - Value uniquely identifies an execution instance of a named job within a workflow instance. + +Full environment variable reference: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same pipeline **and** workflow. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by: + 1. Executing the module script in a separate job that is dependent upon the job that records the run (using the `requires: [job-name]` option in the config), or + 2. Executing the module script in serial with the cypress recording in the same job. + +### AWS CodeBuild + +Reference: https://docs.aws.amazon.com/codebuild/ + +#### Essential environment variables + +- `CODEBUILD_BUILD_ID` - Presence identifies the environment as an AWS CodeBuild environment. Value uniquely identifies a build. + +Full environment variable reference: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html + +Prerequisites + +1. The run to validate and this module's validation script are being executed within the same build. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by executing the module script in serial with the cypress recording in the same build. + +### Drone + +Reference: https://docs.drone.io/pipeline/overview/ + +#### Essential environment variables + +- `DRONE` - Presence identifies the environment as an Drone environment. +- `DRONE_BUILD_NUMBER` - Value uniquely identifies a Drone build. + +Full environment variable reference: https://docs.drone.io/pipeline/environment/reference/ + +#### Prerequisites + +1. The run to validate and this module's validation script are being executed within the same build. +2. The module script is always executed _after_ the run to validate has been created. This can be achieved by executing the module script in serial with the cypress recording in the same build. + +In order to iterate on your verification script and see everything working without putting code into your CI environment, it can be useful to simulate the CI context for a specific Cypress run locally. This can save a lot of time when getting started. diff --git a/docs/partials/_viewfilters.mdx b/docs/partials/_viewfilters.mdx index 409f9beb10..d677361e85 100644 --- a/docs/partials/_viewfilters.mdx +++ b/docs/partials/_viewfilters.mdx @@ -1,7 +1,5 @@ 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. @@ -17,6 +15,11 @@ Nesting this property under an `accessibility` or `uiCoverage` key is supported, if you need to split them up. ::: +## Note on product-specific behavior + +- 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. +- In Cypress Accessibility, excluding a URL excludes all application snapshots from that URL from the reports, but has no other effects. + ## Syntax ```json diff --git a/docs/ui-coverage/results-api.mdx b/docs/ui-coverage/results-api.mdx index 8165212bdf..a789bc177c 100644 --- a/docs/ui-coverage/results-api.mdx +++ b/docs/ui-coverage/results-api.mdx @@ -388,4 +388,8 @@ steps: ``` + +## Required CI environment variables + + ``` diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 20a4edcb49..9620dad1a4 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -44,6 +44,7 @@ import CloudFreePlan from "@site/docs/partials/_cloud_free_plan.mdx"; import CiProviderCloudSteps from "@site/docs/partials/_ci_provider_cloud_steps.mdx"; import UrlAllowList from "@site/docs/partials/_url_allowlist.mdx"; import UICovPremiumNote from "@site/docs/partials/_ui-coverage-premium-note.mdx"; +import ResultsApiEnvVars from "@site/docs/partials/_results-api-env-vars.mdx"; // Font Awesome import { library } from '@fortawesome/fontawesome-svg-core' @@ -208,4 +209,5 @@ export default { CiProviderCloudSteps, UrlAllowList, UICovPremiumNote, + ResultsApiEnvVars, }