Using the axe-linter Connector

The axe-linter Connector is a command-line tool available for Linux, macOS, and Windows. It allows you to check files for accessibility issues.

Setup

For information on downloading the axe-linter Connector, see Downloading the axe-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-linter).

Environment Variables

You need to set two environment variables to use the Connector. They are:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT

The first environment variable is the URL for your axe-linter Server. The second environment variable is the port the server is listening on and is typically port 3000.

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

The following example shows how to set up a typical environment for the axe-linter Server running on the local machine on Linux or macOS:

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

On Linux and macOS, you can also set the environment variables when running the connector command, as shown below:

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

Command-Line Options

Required Command-Line Options

The axe-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 the Connector will write the accessibility report.

Optional Command-Line Options

There are several options that are not required and are primarily used to change the report format for SonarQube.

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

--config filename
Specifies the name of a YAML file containing configuration information. 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 the configuration options, see The Config Object, which gives example JSON configurations. (You will need to convert these to YAML.)

Example Usage

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

axe-linter-connector -s . -d .

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 the Connector with the axe-linter SaaS server, you can use the api-key option as shown below:

axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd288c0a4d