Run accessibility checks in CI
Add pfdl a11y to your pipeline, keep its results on the portal, and fail only on new issues with a baseline.
Run the same check as on your machine in every pipeline, so new accessibility problems fail the build. The portal's Connect page has an Accessibility check in CI card with your portal's address filled in.
Add the step
Start your app earlier in the job and wait until it answers. Then:
npm i --no-save playwright-core@1.64.1
curl -fsSO https://portal.example.com/downloads/pfdl.mjs
node pfdl.mjs a11y "$APP_URL" --out a11y-report
GitHub's and Azure's hosted runners have Chrome. On GitLab, use Playwright's image and add --browser chromium.
Keep a11y-report/ even when the step fails: it holds report.html for people and junit.xml for your pipeline's
test results.
Keep results on the portal
Add --upload and your organisation's designers can read each run under Accessibility checks, with what's new
and what was fixed since the last run (see Read check results).
Create an access token with the designer role or above, one per pipeline.
Store it in your pipeline's secrets as
PFDL_TOKEN. It is never a flag, so it stays out of logs.Run the check with
--upload:node pfdl.mjs a11y "$APP_URL" --out a11y-report --upload --portal https://portal.example.com
The portal and token are checked before the run starts, so a wrong setup stops at once. The run's link on the portal is printed at the end.
--site <name>names the runs this one is compared with. Without it, runs are grouped by repository and address.--meta key=valuekeeps extra details with the run. Commit, branch and pull request are added on GitHub Actions, GitLab CI and Azure Pipelines.node pfdl.mjs a11y upload a11y-reportsends a folder written earlier, as a separate step that runs even when the check failed.
Uploads need a portal with accounts, and your organisation's plan must include accessibility checks.
Fail only on new issues
An app that was never checked usually has many issues. Accept them as known, then fix them over time:
node pfdl.mjs a11y http://localhost:5173/ --update-baseline
This writes pfdl-a11y-baseline.json. Commit it. From then on only new issues fail the run; known ones are still
reported. When you fix issues, --prune-baseline removes their entries, and --strict-baseline fails the run until
they're removed.
Something meant to stay is an exception, not a baseline entry: add it under a11y.exceptions in pfdl.config.json,
each with a why.
If something goes wrong
| What you see | What to do |
|---|---|
Exit code 2 after --upload | The portal refused the upload or couldn't be reached. The message names the role, plan, quota or size. |
| The upload is refused for its role | Use a token with the designer role or above. |
| Screenshots missing from the portal | The run was over 10 MB, so some were left out. Check fewer pages per run. |
| A pipeline written for pa11y misreads the result | pfdl a11y exits 1 for issues and 2 when it can't run: swap them. |