DDEV Pa11y add-on

• What is DDEV Pa11y add-on?
• Getting started
• Available commands
• Configuration
  • Single environment
  • Multiple environments
• Advanced config options
• Reports
• Credits

What is DDEV Pa11y add-on?

This repository provides a DDEV add-on for the Pa11y service. Pa11y is an automated accessibility testing tool that helps developers make their web applications more accessible.

Supports single and multi-environment setups and works in any DDEV project.

Getting started

1. Install the add-on:

   For DDEV v1.23.5 or above:

    ddev add-on get Metadrop/ddev-pa11y
   

   For earlier versions:

    ddev get Metadrop/ddev-pa11y
   

2. Start the DDEV project with ddev start or ddev restart if already running.

Available commands

The first argument can be an environment name or a URL. If omitted, local is used by default (configurable via PA11Y_DEFAULT_ENV). If the first argument does not match a known environment, it is passed directly to pa11y-ci.

Configuration

After installation, the following files and folders are created:

tests/pa11y/
  local/
    config.json       # pa11y config for the local environment
    pa11yci.json      # pa11y-ci config for the local environment
reports/pa11y/        # HTML reports output directory

There are two ways to manage configuration depending on whether you need multiple environments.

Single environment

If you only need one configuration, edit the files in tests/pa11y/local/ and run the commands without arguments:

ddev pa11y-ci
ddev pa11y-ci-report

The pa11yci.json file lists the URLs to test and default options:

{
  "defaults": {
    "chromeLaunchConfig": {
      "args": ["--no-sandbox", "--ignore-certificate-errors"]
    },
    "ignoreHTTPSErrors": true,
    "hideElements": ".skip-pa11y",
    "ignore": []
  },
  "urls": ["https://web"]
}

Multiple environments

For projects with multiple environments (local, staging, production…), create a folder per environment inside tests/pa11y/. Each folder must contain its own pa11yci.json (and optionally config.json):

tests/pa11y/
  local/
    config.json
    pa11yci.json
  staging/
    pa11yci.json
  production/
    pa11yci.json

Run against a specific environment by passing its folder name:

ddev pa11y-ci local
ddev pa11y-ci staging
ddev pa11y-ci-report production

Each pa11yci.json defines the URLs and options for that environment:

{
  "defaults": {
    "ignoreHTTPSErrors": true,
    "hideElements": ".skip-pa11y",
    "ignore": []
  },
  "urls": [
    "https://staging.example.com",
    "https://staging.example.com/contact"
  ]
}

Advanced config options

The config.json (used by ddev pa11y) supports additional pa11y options:

{
  "chromeLaunchConfig": {
    "args": ["--no-sandbox"]
  },
  "ignoreHTTPSErrors": true,
  "hideElements": ".skip-pa11y",
  "ignore": [
    "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
  ],
  "screenCapture": "config/pa11y.png",
  "reporter": "cli",
  "runner": ["axe", "htmlcs"]
}

See the pa11y documentation and pa11y-ci documentation for all available options.

Reports

HTML reports generated by ddev pa11y-ci-report are saved to reports/pa11y/<timestamp>/ and served automatically at https://<project>.ddev.site:9203.

Image version

This addon uses a Docker image from docker-aljibe-tools with a combined tag that encodes both the Pa11y version and the base image version:

ghcr.io/metadrop/aljibe-tools/pa11y:9.1.1-base1.0.0

The default version is set in docker-compose.pa11y.yaml. To use a different version, add the following to .ddev/.env:

PA11Y_VERSION=9.1.1-base1.0.0

To update to a newer version, reinstall the addon with ddev add-on get Metadrop/ddev-pa11y or update PA11Y_VERSION in .ddev/.env and run ddev restart.

Available versions are listed in the docker-aljibe-tools packages.

Credits

• Contributed and maintained by @Metadrop