Automate Accessibility Testing with Pa11y

Facing Accessibility Issues? Automate Audits with Pa11y

You spent weeks on layout, but a client using a screen reader can't see the 'Buy' button. Or worse—received a complaint from a regulatory authority for WCAG 2.1 non-compliance. Manual checking of 500 pages means days of QA work. Pa11y solves this: it runs in CLI, reads sitemap.xml, and produces a report for all pages in one pass. We've been using Pa11y in CI/CD for over 5 years across 50+ projects—sharing our experience. Automating website accessibility testing with Pa11y reduces audit time by 70%, and maintenance costs drop due to early bug detection. See the savings: on a 2000-page project, we cut audit from 3 days to 2 hours and found 47 critical errors that QA missed, saving an estimated $5,000 in QA time.

Why Automate Accessibility Testing?

Without automation, you'll miss 30–50% of violations. Pa11y checks color contrast, alt texts, ARIA attributes, keyboard navigation. We configure it to never miss critical errors while ignoring false positives (e.g., contrast on disabled elements). Typical issues: missing image alt, incorrect ARIA roles, low text contrast. Pa11y automated accessibility testing for WCAG 2.1 compliance reduces audit costs and speeds up releases.

How to Integrate Pa11y into CI/CD?

Setup takes 1–2 days and includes five steps:

1. Analysis—gather URLs from sitemap.xml, define the standard (usually WCAG 2.1 AA).
2. Configuration—create .pa11yci.json with required parameters and exclusions.
3. Integration—add pa11y-ci command to your pipeline (GitLab CI, GitHub Actions, Jenkins).
4. Testing—run a trial audit, adjust false positives.
5. Documentation—document the workflow for the team.

Analysis and Configuration

The process starts with analyzing your site: collect URLs from sitemap.xml, etc. Define the standard (usually WCAG2AA), timeouts, exclusions. Output: .pa11yci.json:

// .pa11yci.json { "defaults": { "standard": "WCAG2AA", "timeout": 30000, "wait": 1000, "ignore": [ "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail" ], "chromeLaunchConfig": { "args": ["--no-sandbox", "--disable-setuid-sandbox"] } }, "urls": [ "https://example.com", "https://example.com/about", "https://example.com/contact", { "url": "https://example.com/login", "actions": [ "wait for element #login-form to be visible" ] } ] } 

Pipeline Integration

Add a step in CI: on GitLab—pa11y-ci --config .pa11yci.json --threshold 5, on GitHub Actions—similarly. The --threshold parameter sets the allowed number of errors. Strict mode (--threshold 0) means the pipeline fails on any error.

Reading from sitemap.xml

pa11y-ci --sitemap https://example.com/sitemap.xml \ --sitemap-find "https://example.com" \ --sitemap-replace "http://localhost:3000" \ --threshold 0 

How to Ignore False Positives?

Pa11y sometimes complains about contrast on disabled elements or ARIA roles set by the framework. We add an ignore list in the config—tailored to your UI kit. For example:

"ignore": [ "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail", "WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputSearch.Name" ] 

This eliminates up to 90% of false positives without losing critical checks.

Comparison: Pa11y vs axe-core

Pa11y wins when you need to scan the entire site. Axe is preferable in unit tests. We combine them: Pa11y for nightly audits, axe in pre-commit hooks. This gives full coverage without duplication. Compared to manual testing, Pa11y is 3 times faster and reduces cost by 70%.

// scripts/a11y-audit.js const pa11y = require('pa11y'); const fs = require('fs'); const PAGES = [ { url: 'http://localhost:3000', name: 'Home' }, { url: 'http://localhost:3000/catalog', name: 'Catalog' }, { url: 'http://localhost:3000/checkout', name: 'Checkout' }, ]; async function audit() { const results = []; for (const page of PAGES) { console.log(`Checking: ${page.name}`); const result = await pa11y(page.url, { standard: 'WCAG2AA', timeout: 20000, actions: page.actions || [], }); results.push({ name: page.name, url: page.url, issues: result.issues.length, critical: result.issues.filter(i => i.type === 'error').length, warnings: result.issues.filter(i => i.type === 'warning').length, violations: result.issues, }); } fs.writeFileSync('a11y-report.json', JSON.stringify(results, null, 2)); console.table(results.map(r => ({ Page: r.name, Errors: r.critical, Warnings: r.warnings, }))); if (results.some(r => r.critical > 0)) { process.exit(1); } } audit(); 

What You Get

After Pa11y setup, you receive:

• A working .pa11yci.json configuration file tailored to your project.
• CI/CD integration—automatic audit on every push.
• Custom ignore list for false positives.
• Documentation on interpreting reports and fixing common errors.
• Team training: how to read Pa11y reports and fix accessibility bugs.

Pa11y Setup Stages

Timelines and Cost

Basic setup takes 1–2 days. Extended setup with custom rules, screenshots, and training—up to 5 days. Cost is calculated individually based on site size; typical investment is $2,000–$5,000. Payback period is less than 3 months. We'll assess your project in 1 hour—contact us.

As per WCAG 2.1 guidelines, Pa11y launches a headless browser (Chrome), loads each page, and checks it against the selected WCAG standard. Results are grouped by error type: error (critical), warning (advisory), notice (informational). This allows quick identification of problem areas and prioritization of fixes.

How to Start?

Contact us for a consultation. Order an accessibility audit, and if you receive a fine for WCAG non-compliance after our audit, we'll recheck for free. This guarantee ensures peace of mind. Our team has over 5 years of experience and has helped 50+ companies achieve compliance. Investment in automation pays off within 2-3 months. Get your Pa11y configuration and eliminate manual checks forever.