README.md

accessibility-checker NODE

Automated accessibility testing for Node-based test environments.

To get started using the deployed packages, download the Node accessibility-checker from NPM.

This package is a supporting component of the IBM Equal Access Toolkit. The Toolkit provides the tools and guidance to create experiences that are delightful for people of all abilities. The guidance is organized by phase, such as Plan, Design, Develop, and Verify, and explains the need to integrate automated testing into the Verify phase. The Toolkit is a major part of the accessibility information and applications at ibm.com/able.

See the Packages for test automation in the Wiki for an overview.

Features

• Scan single or multiple files, directories, or URLs
• Output scan results in JSON, CSV, HTML, or XLSX formats
• Automate accessibility testing within a continuous integration pipeline, such as Travis CI
• Integrate with Node-based test environments, such as Selenium, Puppeteer, Playwright, and Jest
• Validate test results against baselines
• Set a target rule archive
• Configure policies (rule sets) to scan
• Set violation levels that trigger test failures
• Set violation levels that should be reported

Command-line and multi-scan

This module provides some basic command-line utilities that will allow scanning files, directories, and URLs:

• Create a .txt file with path(s) to files, directories, or a list of URLs to be scanned
• Provide the npx achecker the full path of the .txt file to start the scan (e.g., npx achecker path/to/your/file.txt)
• Run npx achecker

Review the accessibility-checker/src/README for more information.

Boilerplates

Review the accessibility-checker/boilerplates/README and see examples for the following:

• batch-scan: scan a set of local files
• cucumber-selenium: Using Cucumber with Selenium-webdriver browser automation
• jest: Using a Jest test environment
• jest-customRS: Using a Jest test environment
• jest-puppeteer-ts: Using a Jest test environment with Puppeteer controlled browser
• jest-selenium: Using a Jest test environment with Selenium-webdriver browser automation
• mocha-puppeteer-ts: Using a Mocha test environment with a Puppeteer controlled browser, and Typescript
• mocha-selenium: Using a Mocha test environment with Selenium-webdriver browser automation
• protractor: Using a Protractor test environment for Angular and AngularJS applications
• webdriverio: Using a Webdriverio browser and mobile test automation framework
• and others

Baselines

Baselines are a helpful feature of accessibility-checker that can be used in the test environment. The concept involves capturing a scan result as a baseline so that future scans will pass if they match the baseline. If they differ, then the test will fail. Many boilerplate examples above include baselines. This feature is useful for issues that have been determined to be of the following:

• false positives determined to be ignored
• Needs review issues resolved
• issues scheduled to be fixed later
• new regression issues captured

See the Baseline basics in the Wiki for an overview.

Building and running locally

Requirements

• Node Version 22

Install

$ npm install

Build & Package

$ npm install
$ npm run build
$ npm run package:zip  or  npm run package:npm

Test

$ npm test

Known issues and workarounds

1. If you see TypeError: ace.Checker is not a constructor:

   • Try to run your tests serially using the configuration option in your framework. For example, use --runInBand in Jest framework.

2. If your site has a Content Security Policy, the engine script may be prevented from loading. In the browser console, you'll see something like:

   VM43:24 Refused to load the script ‘https://cdn.jsdelivr.net/npm/accessibility-checker-engine@3.1.42/ace.js’ because it violates the following Content Security Policy directive:

   If you would prefer not to add cdn.jsdelivr.net to the CSP, you can add able.ibm.com instead via your config file (e.g., ruleServer: "https://able.ibm.com/rules")

Feedback and reporting bugs

If you think you've found a bug, have questions or suggestions, open a GitHub Issue, tagged with node-accessibility-checker.

If you are an IBM employee, feel free to ask questions in the IBM internal Slack channel #accessibility-at-ibm.

License