Using axe DevTools Linter Connector

axe DevTools Linter Connector is a command-line tool for Linux, macOS, and Windows. It provides a command-line interface to send files to axe DevTools Linter so that you can automate your accessibility checking. You can, for instance, use it for scripting and CI/CD (continuous integration and continuous delivery).

Example usage includes:

• You can use axe DevTools Linter Connector to check accessibility as part of Jenkins builds. For more information, see Using axe DevTools Linter with Jenkins.
• You can use the tool to scan your files and feed information about accessibility defects into SonarQube. See Using axe DevTools Linter with SonarQube for information on how to set this up.
• It's used in the example GitHub pre-commit script to block commits that contain accessibility errors. See Using a Git Pre-Commit Hook with axe DevTools Linter.
• It can provide a foundation for checking your code for accessibility defects for such services as:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Setup

For information on downloading axe DevTools Linter Connector, see Downloading the axe DevTools Linter Connector.

On Linux and macOS, the command file needs its execute flag set, as shown below:

chmod +x axe-linter-connector-linux
chmod +x axe-linter-connector-macos

When you download the executable on macOS, the quarantine attribute is set, which you need to delete before you can use the connector:

xattr -d com.apple.quarantine axe-linter-connector-macos

Rename the executable (to drop the operating system and hyphen from the end of the file name) and copy or link it into a directory on your path so it can be used with other tools (such as with a Git pre-commit hook, see Using a Git Pre-Commit Hook with axe DevTools Linter).

Environment Variables

The Connector recognizes two environment variables. They are:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT

The first environment variable sets the URL for your axe DevTools Linter instance. (You can also set the server URL with the -u or --url command-line options.) The second environment variable is the port the server is listening on and is typically port 3000.

See Setting up axe DevTools Linter for more information about setting up your server, and see URL Quick Reference for the URL for use with the SaaS version of axe DevTools Linter. (You do not need to specify a port when using the SaaS version of axe DevTools Linter.)

The following example shows setting environment variables for axe DevTools Linter running on the local machine on Linux or macOS (although neither environment variable is required here because these are the default values):

export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

Alternatively, on Linux and macOS, you can also set the environment variables on the same command line as the axe-linter-connector command. The example below shows this usage. (However, because these are the default values for the server and port, you do not need to set them.)

AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .

Command-Line Options

Required Command-Line Options

axe DevTools Linter Connector requires the following two options:

-s, --source directory-or-file
Indicates a file or the directory containing files to check for accessibility errors. Subdirectories are also searched. To exclude files from being linted, see the exclude option in the Configuration File section.

-d, --destination directory
Directory where Connector will write the accessibility report.

-u, --url URL
Specifies the server to use. The default is http://localhost. To use the SaaS server, specify --url https://axe-linter.deque.com/

Optional Command-Line Options

There are several options that might be required depending on which server you are connecting to and what other features or report formats you want to use.

--api-key api-key
Specifies the API key to use to connect to the SaaS axe DevTools Linter instance. See Obtaining an axe DevTools Linter SaaS API Key for more information.

--config filename
Specifies the name of a YAML file containing configuration information. You can also use this option without a filename, and axe DevTools Connector will follow the steps in Multiple Configuration Files to locate configuration files. For information about the configuration file, see Configuration File.

--filename filename
Specifies the name of SonarQube report, default: axe-linter-report.json

--issue-type type
Used to indicate the issue type for SonarQube, default: BUG, allowed values: VULNERABILITY, CODE_SMELL, or BUG

-R, --reporter reporter
Specifies the reporter to use, default: sonarqube

--severity level
Sets the severity level for SonarQube, default: MAJOR, allowed values: BLOCKER, CRITICAL, MAJOR, MINOR, or INFO

Configuration File

You can use a YAML configuration file with the --config option.

The following shows an example configuration file:

rules:
  image-alt: false

exclude:
  - meta-refresh.html

tags:
  - wcag2a

In the above example, the rule image-alt will be ignored and the file meta-refresh.html will not be linted. The rules in the wcag2a tag will be used, as specified in the tags section. (See Tags for more information.)

The exclude value allows glob values (*) and globstar (**), so the following is allowed:

exclude:
  - tmp/**/*.html

The above example would exclude any HTML files in the tmp directory or any of its subdirectories.

For more information about allowed configuration options, see Configuring axe DevTools Linter.

Example Usage

The following shows how to use Connector to check files in the current directory (and subdirectories) and write a report to the current directory:

axe-linter-connector -s . -d . --url https://axe-linter.deque.com/

The command produces a report, axe-linter-report.json, which describes any accessibility issues in the files that were submitted to the server.

To use Connector with the axe DevTools Linter SaaS server, you can use the api-key option as shown below:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d  --url https://axe-linter.deque.com/