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

Command	Description
ddev pa11y [env|url] [args]	Run pa11y against a single URL
ddev pa11y-ci [env|url] [args]	Run pa11y-ci against all configured URLs
ddev pa11y-ci-report [env|url] [args]	Run pa11y-ci and generate an HTML report in reports/pa11y/<timestamp>/

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.

Credits

• Contributed and maintained by @Metadrop