pa11y - CLI scanner (htmlcs + axe engines)

Companion reference for axe-a11y. Consult when the project needs scriptable a11y scans without a full test framework (CI cron job, docs publication, static-site CI), or when a Node-stack project wants a single-command scanner instead of framework-integrated axe tests.

pa11y is "your automated accessibility testing pal" - a Node.js CLI that runs a11y tests on a page via the command line or a programmatic API (pa11y). It can use HTML CodeSniffer (htmlcs, default) or axe-core as the underlying engine. If the project already runs Playwright / Cypress with axe-core, prefer the direct axe integration in SKILL.md - pa11y adds a layer.

Install and run

npm install -g pa11y        # or --save-dev per-project
pa11y https://example.com

(Per pa11y.)

Key flags

pa11y's WCAG2AA standard is 2.0/2.1; WCAG 2.2 SCs (2.4.11, etc.) need --runner axe alongside htmlcs.

Multi-URL with pa11y-ci

pa11y-ci (https://github.com/pa11y/pa11y-ci) batches a URL set from a .pa11yci config and exits non-zero if any URL exceeds threshold - the canonical CI gate signal:

{
  "defaults": {
    "standard": "WCAG2AA",
    "runners": ["axe", "htmlcs"],
    "includeWarnings": true,
    "threshold": 0
  },
  "urls": [
    "https://staging.example.com/",
    "https://staging.example.com/dashboard",
    "https://staging.example.com/checkout"
  ]
}

Programmatic API and results structure

const pa11y = require('pa11y');

const results = await pa11y('https://example.com', {
  standard: 'WCAG2AA',
  runners: ['axe', 'htmlcs'],
  includeWarnings: true,
});

console.log(results.issues);

results.issues[] holds one object per finding with code, type (error / warning / notice), typeCode, selector, context, message, and runner. When both engines run, the same defect appears twice under different codes - WCAG-SC-coded from htmlcs (WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail), rule-coded from axe (color-contrast) - and a11y-violation-gate collapses the pair via its fingerprint field.

Worked example

pa11y --standard WCAG2AA \
      --runner htmlcs --runner axe \
      --include-warnings \
      --reporter json \
      --threshold 0 \
      https://staging.example.com/checkout > pa11y-results.json

The run exits non-zero (threshold 0 exceeded) and pa11y-results.json holds the issues[] array for the gate.

Anti-patterns

Limitations

• Selector reliability. htmlcs sometimes produces selectors that don't uniquely identify the failing element; axe is more precise.
• JS-rendered content. pa11y's default Chromium runner waits for the load event; SPAs may need --wait-for-selector before scanning.
• No native test-framework integration. For Playwright / Cypress, use the direct axe integration in SKILL.md.

References

• pa11y - https://github.com/pa11y/pa11y (install, CLI flags, runners, reporter formats).
• pa11y-ci - https://github.com/pa11y/pa11y-ci (multi-URL).
• HTML CodeSniffer (the htmlcs runner) - https://github.com/squizlabs/HTML_CodeSniffer