Debug headless Chrome aXe errors

How it works

Here's a quick run-down of what's going on when you run npm run axe:

1. The config/run-axe.js script is using chrome-launcher to find either Canary or Chrome stable on your computer, and then runs it in headless mode, telling it to keep its remote debugging port open.

2. chrome-remote-interface talks to headless Chrome through that remote debugging interface and also starts a static file server that's serving files from the _site directory (which is where Jekyll puts all the generated site files).

   This means that you need to build the Jekyll site and any other static assets before running npm run axe. In other words, npm run axe is not responsible for generating the site itself.

3. config/run-axe.js visits all the pages listed in its PAGES constant (near the top of the file) and runs aXe on them to ensure that there's no accessibility regressions. If there are, it prints errors and exits with a non-zero exit code (which will cause CircleCI to fail).

   Furthermore, when visiting each page, this script makes sure that all network requests succeed, because if they don't, something is really amiss, and we can't trust aXe to give us a reliable idea of the page's accessibility (for example, if the CSS fails to load, we can't reliably tell whether the color contrast is ok or not). In this case, the script will also exit with a non-zero exit code.

Viewing and debugging aXe errors

If aXe finds any errors, it might be hard to read them in the test output, so you'll be better off installing the aXe Chrome extension, visiting the relevant page on your dev server, and inspecting errors that aXe brings up.

Note that there's a possibility your aXe Chrome extension might not show the same errors as npm run axe; if this is the case, it's because the versions of aXe are different--you'll want to upgrade your Chrome extension and/or run npm i --save axe-core@latest to upgrade the version used by the test suite.