Skip to content
Agentic Experience Design Language Help Go to the portal

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.

For developers2 min read

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

  1. Create an access token with the designer role or above, one per pipeline.

  2. Store it in your pipeline's secrets as PFDL_TOKEN. It is never a flag, so it stays out of logs.

  3. 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=value keeps 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-report sends 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

If something goes wrong
What you seeWhat to do
Exit code 2 after --uploadThe portal refused the upload or couldn't be reached. The message names the role, plan, quota or size.
The upload is refused for its roleUse a token with the designer role or above.
Screenshots missing from the portalThe run was over 10 MB, so some were left out. Check fewer pages per run.
A pipeline written for pa11y misreads the resultpfdl a11y exits 1 for issues and 2 when it can't run: swap them.