Using Axe DevTools Linter with SonarQube

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Not for use with personal data

You can integrate Axe DevTools Linter with SonarQube to monitor your code for accessibility issues. You can use the ideas here to integrate CI/CD systems with SonarQube. In the SonarQube documentation, see the Overview of CI integration for information about using GitLab CI/CD, GitHub Actions, Azure Pipelines, or Bitbucket Pipelines.

Overview of SonarQube Integration

The key element for integrating with SonarQube is the command-line tool, Axe DevTools Linter Connector. The tool scans your files and creates a report that is then uploaded to SonarQube via the SonarScanner CLI tool. The steps in detail include:

Scanning files in your local directories.
Sending the files to the Axe DevTools Linter Server for linting or linting the files locally.
Collecting the linting results as a JSON report compatible with SonarQube.
Running SonarScanner CLI over this report to send issues to SonarQube as external issues. The SonarScanner tool doesn't actually scan any of your files in this case. It simply reports the issues that Axe DevTools Linter found as external issues.

The first three steps are performed by Axe DevTools Connector, and the last step is performed by the SonarScanner CLI.

Your own custom CI/CD integration needs to perform these actions:

Launch Axe DevTools Linter Connector with the proper command-line arguments to scan your project's files and produce a SonarQube-compatible JSON report.
Start the SonarScanner CLI to send the linting results to SonarQube.

Requirements

Axe DevTools Linter Connector: See Using Axe DevTools Linter Connector for setup and usage instructions.
SonarQube: This integration has been tested with SonarQube Community Build 26.4. SonarQube changed its Generic Issue Import Format in version 10.3, and future versions may require the updated format. If you encounter import warnings or issues, check that your versions of Axe DevTools Linter Connector and SonarQube are compatible.
SonarScanner CLI: See SonarScanner CLI for more information about downloading this tool.

Set Up SonarQube

To set up SonarQube, create a profile, then delete redundant rules from the profile to disable them (some rules in newly created profiles in SonarQube overlap the rules checked by Axe DevTools Linter, resulting in duplicate errors). You can delete the overlapping rules in the SonarQube admin interface. The following sections describe how to do this.

Create a New Quality Profile

To change the rules, click on Quality Profiles at the top of the SonarQube admin website. Then click on the Filter profiles by: dropdown and select HTML. You should now see the built-in SonarQube HTML profile. You need to duplicate that profile by clicking on the gear dropdown on the right side of the profile and choosing Copy. SonarQube will prompt you to name the newly copied profile. Call the new profile Axe Linter and click on the Copy button.

You now have a new HTML quality profile called Axe Linter. Choose the gear dropdown for the Axe Linter profile and choose Set as Default so that this profile will be used for checking all HTML files.

Remove Redundant Rules

The next step is to remove redundant rules from the Axe Linter Quality profile you created. In the list of HTML rules, there should be two profiles. The Axe Linter profile and the Sonar way profile. Click on the Axe Linter profile to go to the profile configuration page. On the left part of the screen, you should see a list of different types of rules in the profile. Click on the number at the top right of Total and in the Active column to edit the active rules.

On the right side of the display is a list of rules enabled in the Axe Linter HTML profile. Disable the redundant rules indicated below:

<fieldset> tags should contain a <legend>
Links should not directly target images
Image, area, and button with image tags should have an "alt" attribute
<th> tags should have id or scope attributes
Table cells should reference their headers
<object> tags should provide alternative content
<strong> and <em> tags should be used
<table> tags should have a description
Videos should have subtitles
Server-side image maps (ismap attribute) should not be used
<html> element should have a language attribute
<frames> should have a title attribute
HTML <table> should not be used for layout purposes
Tables used for layout should not include semantic markup
aria-label or aria-labelledby attributes should be used to differentiate similar elements
Tables should have headers

These rules are mentioned in step 5 of this Deque Support article.

important

You will need a Deque account to access the support article that includes the redundant rules. See this article for more information about the Help Center and obtaining an account.

Create a SonarQube Configuration File

You need to create a configuration file for SonarQube's SonarScanner CLI. The following shows an example configuration file, sonar-project.properties.

sonar.projectKey=Test-Deque
sonar.externalIssuesReportPaths=axe-linter-report.json

The sonar.projectKey is the project name in SonarQube where you'd like SonarScanner to report results.

Generate a SonarQube Security Token

The SonarQube Scanner needs to be able to connect to SonarQube in order to report results. You can do this by creating a login token in the SonarQube admin web interface.

To create a login token, click on Administration at the top center of the screen in the SonarQube admin web interface. Then click on the Security dropdown near the top of the screen and choose Users. Choose a user for reporting results to SonarQube and click on the icon under Tokens to create a security token for that user. Under Generate Token in the popup window, type the name of the token and click Generate. Save this token's value (a 32-bit hex string) because there is no way of redisplaying it after you close the Token window. (You can, however, generate a new token at any time.)

The SonarScanner CLI uses this token to report the results to the server. It should be set in the SONAR_TOKEN environment variable.

Run the Integration

Once you have configured the SonarQube rules, created a configuration file, and generated a security token, you can run the integration. The process has two steps:

Run Axe DevTools Linter Connector to scan your project files and generate a SonarQube-compatible report.
Run SonarScanner CLI to upload the report to SonarQube.

Generate the Linter Report

Run Axe DevTools Linter Connector from the same directory as your sonar-project.properties file:

axe-linter-connector -s . -d .

This produces axe-linter-report.json in the current directory. See Using Axe DevTools Linter Connector for server, authentication, and other command-line options.

important

The Connector must be run from the SonarScanner project base directory so that the file paths in the report match the files SonarQube expects.

Upload the Report to SonarQube

Set the SONAR_TOKEN environment variable to the security token you generated, then run the SonarScanner CLI:

export SONAR_TOKEN=<your-sonarqube-token>
sonar-scanner -Dsonar.host.url=<sonarqube-server-url>

Replace <sonarqube-server-url> with the URL of your SonarQube server (for example, http://localhost:9000).

The SonarScanner CLI reads the sonar-project.properties file, finds the report specified in sonar.externalIssuesReportPaths, and uploads the issues to SonarQube as external issues.

View Results

Any issues found by Axe DevTools Linter will be shown when you click on Issues in the SonarQube web interface for your project. Axe DevTools Linter issues are identified by AXE-LINTER-MD for Markdown files and by AXE-LINTER-HTML for HTML files.

The Report

Axe DevTools Linter Connector generates a JSON report that follows the SonarQube Generic Issue Import Format.

You can change some of the options in the report by using Axe DevTools Linter Connector's command-line options. See Optional Command-Line Options for more information.