Automated Accessibility Testing with Puppeteer

As digital products become essential to daily life, accessibility is more critical than ever. Accessibility testing ensures that websites and applications are usable by everyone, including people with vision, hearing, motor, or cognitive impairments. While manual accessibility reviews are important, relying solely on them is inefficient for modern development cycles. This is where automated accessibility testing comes in empowering teams to detect and fix accessibility issues early and consistently. In this blog, we’ll explore automated accessibility testing and how you can leverage Puppeteer a browser automation tool to perform smart, customized accessibility checks.

What is Automated Accessibility Testing?

Automated accessibility testing uses software tools to evaluate websites and applications against standards like WCAG 2.1/2.2, ADA Title III, and Section 508. These tools quickly identify missing alt texts, ARIA role issues, keyboard traps, and more, allowing teams to fix issues before they escalate.

Note: While automation catches many technical issues, real-world usability testing still requires human intervention.

Why Automated Accessibility Testing Matters

• Early Defect Detection: Catch issues during development.
• Compliance Assurance: Stay legally compliant.
• Faster Development: Avoid late-stage fixes.
• Cost Efficiency: Reduces remediation costs.
• Wider Audience Reach: Serve all users better.

Understanding Accessibility Testing Foundations

Accessibility testing analyzes the Accessibility Tree generated by the browser, which depends on:

• Semantic HTML elements
• ARIA roles and attributes
• Keyboard focus management
• Visibility of content (CSS/JavaScript)

Key Automated Accessibility Testing Tools

• axe-core: Leading open-source rules engine.
• Pa11y: CLI tool for automated scans.
• Google Lighthouse: Built into Chrome DevTools.
• Tenon, WAVE API: Online accessibility scanners.
• Screen Reader Simulation Tools: Simulate screen reader-like navigation.

Automated vs. Manual Screen Reader Testing

Automated Accessibility Testing with Puppeteer

Puppeteer is a Node.js library developed by the Chrome team. It provides a high-level API to control Chrome or Chromium through the DevTools Protocol, enabling you to script browser interactions with ease.

Puppeteer allows you to:

• Open web pages programmatically
• Perform actions like clicks, form submissions, scrolling
• Capture screenshots, PDFs
• Monitor network activities
• Emulate devices or user behaviors
• Perform accessibility audits

It supports both:

• Headless Mode (invisible browser, faster, ideal for CI/CD)
• Headful Mode (visible browser, great for debugging)

Because Puppeteer interacts with a real browser instance, it is highly suited for dynamic, JavaScript-heavy websites — making it perfect for accessibility automation.

Why Puppeteer + axe-core for Accessibility?

• Real Browser Context: Tests fully rendered pages.
• Customizable Audits: Configure scans and exclusions.
• Integration Friendly: Easy CI/CD integration.
• Enhanced Accuracy: Captures real-world behavior better than static analyzers.

Setting Up Puppeteer Accessibility Testing

Step 1: Initialize the Project

mkdir a11y-testing-puppeteer
cd a11y-testing-puppeteer
npm init -y

Step 2: Install Dependencies

npm install puppeteer axe-core
npm install --save-dev @types/puppeteer @types/node typescript

Step 3: Example package.json

{
  "name": "accessibility_puppeteer",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "node accessibility-checker.js"
  },
  "dependencies": {
    "axe-core": "^4.10.3",
    "puppeteer": "^24.7.2"
  },
  "devDependencies": {
    "@types/node": "^22.15.2",
    "@types/puppeteer": "^5.4.7",
    "typescript": "^5.8.3"
  }
}

Step 4: Create accessibility-checker.js

const axe = require('axe-core');
const puppeteer = require('puppeteer');

async function runAccessibilityCheckExcludeSpecificClass(url) {
  const browser = await puppeteer.launch({
    headless: false,
    args: ['--start-maximized']
  });

  console.log('Browser Open..');
  const page = await browser.newPage();
  await page.setViewport({ width: 1920, height: 1080 });

  try {
    await page.goto(url, { waitUntil: 'networkidle2' });
    console.log('Waiting 13 seconds...');
    await new Promise(resolve => setTimeout(resolve, 13000));

    await page.setBypassCSP(true);
    await page.evaluate(axe.source);

    const results = await page.evaluate(() => {
      const globalExclude = [
        '[class*="hide"]',
        '[class*="hidden"]',
        '.sc-4abb68ca-0.itgEAh.hide-when-no-script'
      ];

      const options = axe.getRules().reduce((config, rule) => {
        config.rules[rule.ruleId] = {
          enabled: true,
          exclude: globalExclude
        };
        return config;
      }, { rules: {} });

      options.runOnly = {
        type: 'rules',
        values: axe.getRules().map(rule => rule.ruleId)
      };

      return axe.run(options);
    });

    console.log('Accessibility Violations:', results.violations.length);
    results.violations.forEach(violation => {
      console.log(`Help: ${violation.help} - (${violation.id})`);
      console.log('Impact:', violation.impact);
      console.log('Help URL:', violation.helpUrl);
      console.log('Tags:', violation.tags);
      console.log('Affected Nodes:', violation.nodes.length);
      violation.nodes.forEach(node => {
        console.log('HTML Node:', node.html);
      });
    });

    return results;

  } finally {
    await browser.close();
  }
}

// Usage
runAccessibilityCheckExcludeSpecificClass('https://www.bbc.com')
  .catch(err => console.error('Error:', err));

Expected Output

When you run the above script, you’ll see a console output similar to this:

Browser Open..
Waiting 13 seconds...
Accessibility Violations: 4

Help: Landmarks should have a unique role or role/label/title (i.e. accessible name) combination (landmark-unique)
Impact: moderate
Help URL: https://dequeuniversity.com/rules/axe/4.10/landmark-unique?application-axeAPI
Tags: ['cat.semantics', 'best-practice']
Affected Nodes: 1
HTML Nodes: <nav data-testid-"level1-navigation-container" id="main-navigation-container" class="sc-2f092172-9 brnBHYZ">

Help: Elements must have sufficient color contrast (color-contrast)
Impact: serious
Help URL: https://dequeuniversity.com/rules/axe/4.1/color-contrast
Tags: [ 'wcag2aa', 'wcag143' ]
Affected Nodes: 2
HTML Node: <a href="/news" class="menu-link">News</a>

Help: Form elements must have labels (label)
Impact: serious
Help URL: https://dequeuniversity.com/rules/axe/4.1/label
Tags: [ 'wcag2a', 'wcag412' ]
Affected Nodes: 1
HTML Node: <input type="text" id="search" />

...

Browser closed.

Each violation includes:

• Rule description (with ID)
• Impact level (minor, moderate, serious, critical)
• Helpful links for remediation
• Affected HTML snippets

This actionable report helps prioritize fixes and maintain accessibility standards efficiently.

Best Practices for Puppeteer Accessibility Automation

• Use headful mode during development, headless mode for automation.
• Always wait for full page load (networkidle2).
• Exclude hidden elements globally to avoid noise.
• Capture and log outputs properly for CI integration.

Conclusion

Automated accessibility testing empowers developers to build more inclusive, legally compliant, and user-friendly websites and applications. Puppeteer combined with axe-core enables fast, scalable accessibility audits during development. Adopting accessibility automation early leads to better products, happier users, and fewer legal risks. Start today — make accessibility a core part of your development workflow!

Frequently Asked Questions