Using axe DevTools Linter Connector

axe DevTools Linter Connector (also known as the Connector) is a command-line tool for Linux, macOS, and Windows. It provides a command-line interface to lint your files so that you can automate your accessibility checking. You can, for instance, use it for scripting and CI/CD (continuous integration and continuous delivery). The Connector needs to send your files to an instance of axe Linter Server (whether hosted by Deque or by your organization), or you can lint the files locally without sending your files' contents to a server using the --local option, see Local Linting below.

Use Cases for the Connector

The axe DevTools Connector can

• Check accessibility as part of Jenkins builds. For more information, see Using axe DevTools Linter with Jenkins.
• 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.
• Be used in a GitHub pre-commit script to block commits that contain accessibility errors. See Using a Git Pre-Commit Hook with axe DevTools Linter.
• Provide a foundation for checking your code for accessibility defects for such services as:
  • Bitbucket
  • CircleCI
  • GitLab
  • Azure DevOps Services

Local Linting

The Connector allows you to avoid sending your files to a server by using local linting with the --local command-line option.

• Advantages of Local Linting

  • Much faster than using the server.
  • Much less likely to encounter network problems or server load issues. It is especially efficient when linting large numbers of files.

• Disadvantages of Local Linting

  • Requires more local machine resources.
  • Updates to the axe DevTools Linter Connector require a new version to be downloaded from Agora and installed.
  • No usage tracking (if you use a license key instead of an API key).

License Keys Compared to API Keys

Local linting requires either an API key or a license key. You can manage your API keys as part of your axe Account (so they offer flexibility). However, you must request a license key from Deque's Help Desk. Using local linting with license keys doesn't track your users' usage (lines of code linted), but license keys also don't require remote authentication.

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 the following environment variables:

• AXE_LINTER_SERVER_URL
• AXE_LINTER_SERVER_PORT
• DEBUG

AXE_LINTER_SERVER_URL and AXE_LINTER_SERVER_PORT

AXE_LINTER_SERVER_URL sets the URL for your axe DevTools Linter server instance. (You can also set the server URL with the -u or --url command-line options.) AXE_LINTER_SERVER_PORT specifies the port the server listens on, 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 .

DEBUG

The DEBUG environment variable allows you to log detailed debugging information for diagnosing linting failures. Set the DEBUG environment variable to axe-devtools-linter:* to turn on debug logging, as shown below:

DEBUG=axe-devtools-linter:* 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

Several options 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 authorize linting with the SaaS axe DevTools Linter instance or to use local linting. 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

--license-key key
Specifies the license key to use for authentication. Contact the Deque Help Desk for more information about obtaining a license key. This option also requires the --local option.

--local
Turns on local linting, which uses the machine the axe DevTools Connector is running on to lint your files rather than sending files to a server. Requires an API key (--api-key) or a license key (--license-key). See Local Linting.

axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/

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

--retry-backoff-limit backoff-limit
Specifies the maximum time in milliseconds that the Connector will wait before retrying the server connection upon error. The default is 30,000 milliseconds (30 seconds).

--retry-count retries
Specifies the number of times to retry the server connection after encountering a connection error. The Connector will double the time between retries (starting at 500 milliseconds or 0.5 seconds) until it reaches the backoff-limit (specified with --retry-backoff-limit), where it will stay until it reaches the specified number of retries (and fails) or connects to the server without error.

--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

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/

To perform all linting locally on the computer running axe DevTools Connector, use the --local option:

axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/