gitlab-org--gitlab-foss/doc/ci/testing/accessibility_testing.md

3.3 KiB

stage group info
Verify Pipeline Insights To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Accessibility testing (FREE)

Introduced in GitLab 12.8.

If your application offers a web interface, you can use GitLab CI/CD to determine the accessibility impact of pending code changes.

Pa11y is a free and open source tool for measuring the accessibility of web sites. GitLab integrates Pa11y into a CI job template. The a11y job analyzes a defined set of web pages and reports accessibility violations, warnings, and notices in a file named accessibility.

As of GitLab 14.5, Pa11y uses WCAG 2.1 rules.

Accessibility merge request widget

GitLab displays an Accessibility Report in the merge request widget area:

Accessibility merge request widget

Configure accessibility testing

You can run Pa11y with GitLab CI/CD using the GitLab Accessibility Docker image.

To define the a11y job for GitLab 12.9 and later:

  1. Include the Accessibility.gitlab-ci.yml template from your GitLab installation.

  2. Add the following configuration to your .gitlab-ci.yml file.

    stages:
      - accessibility
    
    variables:
      a11y_urls: "https://about.gitlab.com https://gitlab.com/users/sign_in"
    
    include:
      - template: "Verify/Accessibility.gitlab-ci.yml"
    
  3. Customize the a11y_urls variable to list the URLs of the web pages to test with Pa11y.

The a11y job in your CI/CD pipeline generates these files:

  • 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.

You can view job artifacts in your browser.

NOTE: For GitLab versions earlier than 12.9, use include:remote and link to the current template in the default branch

NOTE: The job definition provided by the template does not support Kubernetes.

You cannot pass configurations into Pa11y via CI configuration. To change the configuration, edit a copy of the template in your CI file.