Commit a2441a94 authored by Amy Qualls's avatar Amy Qualls

Merge branch 'accessibility_testing_style' into 'master'

Style for accessibility testing docs

See merge request gitlab-org/gitlab!77282
parents 507613fd 6fc77381
......@@ -9,71 +9,69 @@ type: reference, howto
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8.
If your application offers a web interface and you are using
[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility
If your application offers a web interface, you can use
[GitLab CI/CD](../../../ci/index.md) to determine the accessibility
impact of pending code changes.
## Overview
GitLab uses [pa11y](https://pa11y.org/), a free and open source tool for
measuring the accessibility of web sites, and has built a simple
[Pa11y](https://pa11y.org/) is a free and open source tool for
measuring the accessibility of web sites. GitLab integrates Pa11y into a
[CI job template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml).
This job outputs accessibility violations, warnings, and notices for each page
analyzed to a file called `accessibility`.
The `a11y` job analyzes a defined set of web pages and reports
accessibility violations, warnings, and notices in a file named
`accessibility`.
From [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), the version of `pa11y` uses
[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1), which may report more issues.
As of [GitLab 14.5](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/73309), Pa11y uses
[WCAG 2.1 rules](https://www.w3.org/TR/WCAG21/#new-features-in-wcag-2-1).
## Accessibility merge request widget
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39425) in GitLab 13.0 behind the disabled [feature flag](../../../administration/feature_flags.md) `:accessibility_report_view`.
> - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/217372) in GitLab 13.1.
In addition to the report artifact that is created, GitLab will also show the
Accessibility Report in the merge request widget area:
GitLab displays an **Accessibility Report** in the merge request widget area:
![Accessibility merge request widget](img/accessibility_mr_widget_v13_0.png)
## Configure Accessibility Testing
This example shows how to run [pa11y](https://pa11y.org/)
on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility).
## Configure accessibility testing
For GitLab 12.9 and later, to define the `a11y` job, you must
[include](../../../ci/yaml/index.md#includetemplate) the
[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml)
included with your GitLab installation, as shown below.
You can run Pa11y with GitLab CI/CD using the
[GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility).
Add the following to your `.gitlab-ci.yml` file:
To define the `a11y` job for GitLab 12.9 and later:
```yaml
stages:
- accessibility
1. [Include](../../../ci/yaml/index.md#includetemplate) the
[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml)
from your GitLab installation.
1. Add the following configuration to your `.gitlab-ci.yml` file.
variables:
a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in"
```yaml
stages:
- accessibility
variables:
a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in"
include:
- template: "Verify/Accessibility.gitlab-ci.yml"
```
include:
- template: "Verify/Accessibility.gitlab-ci.yml"
```
1. Customize the `a11y_urls` variable to list the URLs of the web pages to test with Pa11y.
creates an `a11y` job in your CI/CD pipeline, runs
Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each.
The `a11y` job in your CI/CD pipeline generates these files:
The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
- One HTML report per URL listed in the `a11y_urls` variable.
- One file containing the collected report data. In GitLab versions 12.11 and later, this
file is named `gl-accessibility.json`. In GitLab versions 12.10 and earlier, this file
is named [`accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9).
A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports.
It includes report data for all URLs scanned.
NOTE:
For GitLab 12.10 and earlier, the [artifact generated is named `accessibility.json`](https://gitlab.com/gitlab-org/ci-cd/accessibility/-/merge_requests/9).
You can [view job artifacts in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts).
NOTE:
For GitLab versions earlier than 12.9, you can use `include:remote` and use a
For GitLab versions earlier than 12.9, use `include:remote` and
link to the [current template in the default branch](https://gitlab.com/gitlab-org/gitlab/-/raw/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml)
NOTE:
The job definition provided by the template does not support Kubernetes yet.
The job definition provided by the template does not support Kubernetes.
It is not yet possible to pass configurations into Pa11y via CI configuration. To change anything,
copy the template to your CI file and make the desired edits.
You cannot pass configurations into Pa11y via CI configuration.
To change the configuration, edit a copy of the template in your CI file.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment