Accessibility Developer Tools (ADT)

2.12.0 · active · verified Sun Apr 19

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.

Common errors

```
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: 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.
```
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.

Warnings

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.

Install

npm install accessibility-developer-tools npm
yarn add accessibility-developer-tools yarn
pnpm add accessibility-developer-tools pnpm

Imports

axs
wrong:
```
import { axs } from 'accessibility-developer-tools';
```
correct:
```
import 'accessibility-developer-tools'; // Exposes global 'axs'
// Or for CJS:
const axs = require('accessibility-developer-tools');
```
The library primarily exposes a global `axs` object when included in a browser. For Node.js environments, starting from v2.11.0, it can be `require`d, which typically assigns the `axs` object as the module's default export. Named imports are not commonly supported as `axs` is the primary namespace.
axs.Audit.run
wrong:
```
import { Audit } from 'accessibility-developer-tools';
Audit.run();
```
correct:
```
// After importing or including the library:
axs.Audit.run();
```
Access to audit functionality is via methods on the global `axs.Audit` object. Direct imports for `Audit` are not standard.
axs.constants.AuditResult
wrong:
```
import { AuditResult } from 'accessibility-developer-tools/constants';
```
correct:
```
// After importing or including the library:
const resultType = axs.constants.AuditResult.PASS;
```
Constants like `AuditResult` are nested under `axs.constants` and accessed directly after the library is loaded, not via separate named imports.

Quickstart

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');

view raw JSON →