Accessibility Developer Tools (ADT)

raw JSON →
2.12.0 verified Sun Apr 19 auth: no javascript

The Accessibility Developer Tools (ADT) library provides a suite of accessibility-related testing and utility code primarily for web browsers. Its core functionality includes an accessibility audit API, offering a collection of rules to check for common accessibility problems within an HTML page. Beyond auditing, it offers utilities such as contrast ratio calculation, ARIA attribute validation, and accessible name computation following WAI-ARIA specifications. The current stable version is 2.12.0, with a release cadence that appears somewhat irregular, often driven by bug fixes, performance enhancements, and new audit rules. Key differentiators include its focus on practical, rule-based audits for web content and its integration capabilities with testing frameworks like Selenium and headless browsers like PhantomJS. It's often used in CI/CD pipelines to automate accessibility checks.

error ReferenceError: axs is not defined
cause The `accessibility-developer-tools` library was not loaded or initialized correctly in the execution environment (e.g., browser or Node.js with JSDOM).
fix
Ensure the axs_testing.js script is included in your HTML page before any calls to axs, or if in Node.js, ensure require('accessibility-developer-tools') is executed and assigns axs to a global or local variable.
error Error: Command failed: java -jar ... closure-compiler.jar
cause The Closure Compiler, used during the build process, encountered an error. This is often due to an improperly configured Java Development Kit (JDK) or issues within the compiler itself.
fix
Verify that a compatible JDK version is installed and accessible via your system's PATH variable. Check the specific error message from Closure Compiler for more details on the cause, which might indicate a bug in the source code being compiled.
error Cannot read property 'run' of undefined (reading 'Audit')
cause The `axs.Audit` object is undefined, meaning the core audit functionality was not exposed or initialized when the `axs` global object was created.
fix
This typically means the library loaded partially or an incorrect version. Ensure you are loading axs_testing.js (or the equivalent module export) and that it completes execution without errors. This can happen if dependencies for the library itself fail to load.
breaking The `axs.AuditRule.run()` method signature changed in v0.0.4. It now accepts an options object instead of previous arguments.
fix Update calls to `axs.AuditRule.run()` to pass an options object as its single argument. Refer to the method documentation for the specific structure of the options object.
gotcha Building the project (e.g., from source) requires a Java Development Kit (JDK) to run Closure Compiler, which is used in the build process.
fix Ensure a recent version of JDK is installed and configured in your system's PATH. If encountering build errors related to Java or Closure Compiler, verify JDK installation.
gotcha Prior to v2.11.0, properly `require`ing the accessibility developer tools in Node.js environments was problematic or not officially supported, primarily designed for browser global usage.
fix For Node.js projects, upgrade to v2.11.0 or newer to ensure reliable CommonJS `require` support. If using older versions, consider loading the script directly into a JSDOM or similar browser-like environment.
gotcha The audit configuration options were enhanced in v2.9.0 to support specifying options through an object when initializing audits.
fix For fine-grained control over audit behavior, upgrade to v2.9.0 or later and utilize the object-based configuration options as described in the documentation for `axs.Audit` initialization.
deprecated Direct DOM manipulation and global scope reliance in accessibility tools can be less robust in modern component-based frameworks. While effective, integrating with Shadow DOM or isolated web components may require specific patterns or workarounds.
fix When using with frameworks that employ Shadow DOM, ensure the auditing tool can properly traverse shadow roots. The library's ability to descend into iframes (v2.8.0) is a positive sign, but Shadow DOM behavior might differ. Manual element selection or additional context might be necessary for elements within closed shadow roots.
npm install accessibility-developer-tools
yarn add accessibility-developer-tools
pnpm add accessibility-developer-tools

This quickstart demonstrates how to use `accessibility-developer-tools` within a Node.js environment using Puppeteer to audit a web page. It injects the library into a headless browser, runs a full accessibility audit, and logs the results including failing elements.

import puppeteer from 'puppeteer';

async function runAccessibilityAudit(url) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto(url, { waitUntil: 'networkidle0' });

  // Inject accessibility-developer-tools library
  // This assumes the library is installed and available in node_modules
  // or fetched from a CDN directly.
  // For simplicity, we'll use a direct CDN path here for the browser-global version.
  await page.addScriptTag({
    url: 'https://raw.githubusercontent.com/GoogleChrome/accessibility-developer-tools/stable/dist/js/axs_testing.js'
  });

  // Run the audit and get results
  const results = await page.evaluate(() => {
    if (typeof axs === 'undefined' || !axs.Audit || !axs.Audit.run) {
      return { error: 'accessibility-developer-tools not loaded or initialized.' };
    }
    const auditResults = axs.Audit.run();
    return auditResults.map(result => ({
      ruleName: result.rule.name,
      result: result.result,
      elements: result.elements ? result.elements.map(el => el.outerHTML) : []
    }));
  });

  console.log(`Accessibility audit for ${url}:`);
  results.forEach(item => {
    console.log(`  Rule: ${item.ruleName} - Result: ${item.result}`);
    if (item.elements && item.elements.length > 0) {
      console.log('    Failing elements:', item.elements.slice(0, 3).join(' ')); // Log first 3 elements
    }
  });

  await browser.close();
}

// Example usage: You'd typically run this against a local or staging URL
runAccessibilityAudit('https://www.google.com');