Pa11y 5.0.0

Today we’re proud to announce the stable release of Pa11y 5! A lot of hard work’s gone into this release from the existing team as well as some new contributors.

We maintain a full migration guide to help you switch from Pa11y 4.x, but we’ll highlight some of the features we’re excited about here.

If you just want to get started, you can run the following:

npm install -g pa11y@latest

As always, thanks for continuing to support Pa11y :heart: we’re glad to have you with us as we work towards a more accessible web.

Headless Chrome

Pa11y 5 switches from PhantomJS to Headless Chrome. This allows us to use more modern JavaScript APIs and make Pa11y testing more stable.

Node.js Support

Pa11y 5 only supports Node.js v8.0.0 and higher, you’ll need to upgrade to be able to use the latest version. We’ll be supporting Pa11y 4.x for the next 6 months (or more if some community members are struggling to upgrade), and Node.js 6.x stops being maintained 6 months after that.

New Actions

We’ve added several new actions in Pa11y 5, which became a lot easier (or possible) to implement with the move to Headless Chrome.

Screen Capture

As well as being able to take a screen-grab of the page before Pa11y runs, you can now take multiple screen-grabs by using actions. For example:

    "actions": [
        "screen capture before-login.png",
        "set field #username to pa11y-fan-2k18",
        "set field #password to ilovepa11y",
        "click element #login",
        "wait for path to not be /login",
        "screen capture after-login.png"

You can now use an action to navigate around a site before running the Pa11y tests. This allows you to perform actions on other pages that you might need in order to fully test your original page. For example:

    "actions": [
        "navigate to",
        "navigate to"

Warnings and Notices

Pa11y 5 ignores warnings and notices by default, as these are not usually actionable or useful in automated testing.

You can force Pa11y to include warnings and notices again by using the --include-notices and --include-warnings command-line flags, or the includeNotices and includeWarnings options.


When you run Pa11y with the --debug flag, you can now see any console logs from the page you’re testing. This can help with debugging, to ensure that Pa11y is testing the page that you expect.


Pa11y is now completely Promise-based, and uses async/await internally. This means the API has changed significantly. This is best expressed in code:

pa11y('').then((results) => {
    // ...
const results = await pa11y('');