Pa11y

Pa11y is a free, open-source automated accessibility testing tool designed for command-line use and CI/CD integration. Perfect for developers who want to catch accessibility issues early and continuously.

›

Tool Overview

Attribute Details
Developer Pa11y Team (Open source community)
Tool Type Command-line accessibility testing tool
Platforms Node.js (Windows, macOS, Linux)
Pricing Free and open source (MIT license)
Testing Engine HTML CodeSniffer (default), axe-core (optional)
Website pa11y.org
›

What is Pa11y?

Pa11y is a set of free, open-source tools that help find accessibility issues in web pages. The core Pa11y tool runs from the command line, making it ideal for integration into automated workflows and continuous integration pipelines.

Unlike browser-based tools, Pa11y is designed for developers and DevOps engineers who want to automate accessibility testing as part of their build process. It can test pages, take screenshots, and generate reports automatically.

The Pa11y ecosystem includes several tools: pa11y (command line), pa11y-ci (CI integration), pa11y-dashboard (web dashboard), and pa11y-webservice (API). Together, these provide a complete solution for automated accessibility monitoring.

›

Key Features & Capabilities

Pa11y Tools Ecosystem

  • pa11y: Core command-line tool for testing single pages
  • pa11y-ci: CI integration for testing multiple URLs
  • pa11y-dashboard: Web dashboard for tracking issues over time
  • pa11y-webservice: REST API for programmatic access

Testing Capabilities

  • Multiple Standards: WCAG 2.0 A, AA, AAA; WCAG 2.1 AA; Section 508
  • Testing Engines: HTML CodeSniffer (default) or axe-core
  • Actions: Click, type, wait, navigate before testing
  • Authentication: Test authenticated pages with actions
  • Screenshots: Capture page screenshots during tests
  • Reports: CLI, JSON, CSV, HTML output formats

CI/CD Integration

  • Exit codes for pass/fail in build pipelines
  • Configurable thresholds for errors and warnings
  • JSON output for integration with other tools
  • Works with GitHub Actions, GitLab CI, Jenkins, etc.
›

Installation & Setup

Basic Installation

# Install Pa11y globally
npm install -g pa11y

# Or install locally in a project
npm install pa11y --save-dev

# Install Pa11y CI for multiple URLs
npm install -g pa11y-ci

Basic Usage

# Test a single URL
pa11y https://example.com

# Test with WCAG 2.1 AA standard
pa11y --standard WCAG2AA https://example.com

# Output as JSON
pa11y --reporter json https://example.com

# Use axe-core instead of HTML CodeSniffer
pa11y --runner axe https://example.com

# Take a screenshot
pa11y --screen-capture ./screenshot.png https://example.com

Pa11y CI Configuration

Create a .pa11yci file in your project root:

{
  "defaults": {
    "standard": "WCAG2AA",
    "timeout": 30000,
    "wait": 1000
  },
  "urls": [
    "https://example.com/",
    "https://example.com/about",
    "https://example.com/contact",
    {
      "url": "https://example.com/login",
      "actions": [
        "set field #username to user@example.com",
        "set field #password to password123",
        "click element #submit",
        "wait for url to be https://example.com/dashboard"
      ]
    }
  ]
}

GitHub Actions Example

name: Accessibility Tests
on: [push, pull_request]

jobs:
  pa11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm start & npx wait-on http://localhost:3000
      - run: npx pa11y-ci
›

What Pa11y Tests For

Standard Description
WCAG2A WCAG 2.0 Level A (minimum accessibility)
WCAG2AA WCAG 2.0 Level AA (recommended, most common target)
WCAG2AAA WCAG 2.0 Level AAA (highest conformance)
WCAG21AA WCAG 2.1 Level AA (current standard)
Section508 U.S. Section 508 requirements

Testing Engines

HTML CodeSniffer: Default engine, comprehensive WCAG checks
axe-core: Zero false positives, industry-standard engine
Use --runner axe to switch engines.

›

Quick Facts

Best For: Automated testing in CI/CD pipelines

Skill Level: Intermediate (command line knowledge)

Time to Learn: 30-60 minutes

Output: CLI, JSON, CSV, HTML reports

›

Pricing

100% Free

  • Open source (MIT license)
  • All tools are free
  • No usage limits
  • Self-hosted dashboard
  • Active community support
›

Pros & Cons

Advantages

  • Free and open source
  • Excellent CI/CD integration
  • Multiple testing engines
  • Actions for complex flows
  • Configurable thresholds
  • Multiple report formats

Limitations

  • Requires command line knowledge
  • No browser extension
  • Limited visual feedback
  • Dashboard requires setup
›

Related Tools

View all testing tools ›
›

Best Practices for Using Pa11y

CI/CD Integration

  1. Start with Warnings: Allow builds to pass but report issues initially
  2. Set Baselines: Establish acceptable error counts and reduce over time
  3. Test Key Pages: Focus on critical user journeys first
  4. Use Thresholds: Configure --threshold to fail on specific issue counts

Advanced Usage

  1. Test Authenticated Pages: Use actions to log in before testing
  2. Test Dynamic Content: Use wait actions for async content
  3. Combine Engines: Run both HTML CodeSniffer and axe-core
  4. Ignore Known Issues: Use --ignore for issues you're addressing separately

Pro Tip

Use Pa11y alongside manual testing. Automated tools can only detect about 30-40% of accessibility issues. Pa11y is great for catching regressions, but should be part of a comprehensive testing strategy.

Need Help Setting Up Automated Testing?

Our experts can help you integrate accessibility testing into your development workflow.

Contact Us All Testing Tools