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 tool 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 how to integrate this automated testing tool into the Verify phase. The Toolkit is a major part of the accessibility information and applications at ibm.com/able.

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, Jest, and Zombie
• 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 batch of local files
• cucumber-selenium: Using Cucumber with a Selenium-webdriver browser
• jest: Using a Jest test environment
• jest-selenium: Using a Jest test environment with a Selenium-webdriver browser
• mocha-selenium: Using a Mocha test environment with a Selenium-webdriver browser
• protractor: Using a Protractor test environment
• webdriverio: Using a Webdriverio test environment
• and others

Baselines

Baselines are a helpful feature of accessibility-checker that can also 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. This feature is useful for issues that have been determined to be the following:

• false positives
• issues scheduled to be fixed later
• capturing new regression issues

See the accessibility-checker/src/README for details. Review the examples of validating automated accessibility testing results against baseline files:

• jest baselines
• jest-selenium baselines
• and others

Building and running locally

Requirements

• Node Version 18

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