Using axe DevTools Linter with SonarQube
You can integrate axe DevTools Linter with SonarQube and monitor your code for accessibility issues.
You'll need to set up several pieces of software to use axe DevTools Linter with SonarQube as listed below:
- Jenkins. See Using axe DevTools Linter with Jenkins for more information. You need to set up Jenkins to generate a report using axe DevTools Linter Connector as part of the build process and then submit the report to SonarQube for analysis.
- axe DevTools Linter and Connector. See Setting up the On-Premises Server and Using axe DevTools Linter Connector for setup instructions.
- SonarQube. See Try Out SonarQube for more information. For detailed installation instructions, see Install the Server.
- The SonarQube plugin for Jenkins, SonarScanner for Jenkins.
Setting Up Rules in SonarQube
The first step to set up SonarQube is to disable redundant rules (rules that overlap rules checked by axe DevTools Linter). You can turn off the overlapping rules in the SonarQube admin interface.
Creating a New Quality Profile in SonarQube
To change the rules, click on Quality Profiles at the top of the SonarQube admin website. Then on the Filter profiles by: dropdown, 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 new copied profile. Call the new profile axe-linter and click on the Copy button.
You should 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 the axe-linter profile will be used for checking all HTML files.
Remove Redundant Rules
The next step is to remove redundant rules in the axe-linter Quality profile that you just 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 in the axe-linter profile.
On the right side of the display is a list of rules that are enabled in the axe-linter HTML profile. Disable the following rules:
- "<html>" element should have a language attribute. This problem is already detected by axe DevTools Linter.
- Image, area and button with image tags should have an "alt" attribute. Already detected by axe DevTools Linter.
- "<object>" tag should provide an alternative content. This check is already performed by axe DevTools Linter.
- "<th>" tags should have "id" or "scope" attributes. Taxe DevTools Linter doesn't check for id or scope because they're not always needed, but it does check for correct usage if those attributes are used.
Add a SonarQube Build Step to Jenkins
There are two build steps that you need to add to Jenkins to import axe DevTools Linter accessibility errors to SonarQube. The first build step occurs when Jenkins starts axe DevTools Linter Connector and generates a report containing the accessibility errors detected by axe DevTools Linter. Adding this build step is covered in Using axe DevTools Linter with Jenkins. Once the first step creates the report, Jenkins then invokes the SonarQube Scanner to import the report into SonarQube.
The following steps show how to set up Jenkins to invoke the SonarQube Scanner and import the accessibility report created by axe DevTools Linter Connector and axe DevTools Linter.
Install the SonarQube Plugin in Jenkins
You now need to install the SonarQube Scanner plugin in Jenkins. At the Dashboard in Jenkins, click on Manage Jenkins on the left side of the screen. Then choose Manage Plugins. Then choose the Available tab toward the top of the screen, and type sonarqube in the filter textbox. Choose Install for the SonarQube Scanner for Jenkins.
Add a SonarQube Scanner Build Step
For the project that you would like to check, select the project from the Dashboard. Over on the left site of the Jenkins web interface, choose Configure. Now click on the Build tab to scroll to the Build section of the configuration.
After the Execute shell build step that you already added from Using axe DevTools Linter with Jenkins, choose Execute SonarQube Scanner from the Add build step dropdown.
Create a SonarQube Configuration File
You need to create a configuration file for SonarQube's SonarScanner. The following shows an example configuration file, sonar-project.properties.
The sonar.projectKey is the name of the project in SonarQube where you you'd like Jenkins and the SonarScanner to report results. When Jenkins runs the SoarQube Scanner build step, it'll use this project key.
Add this configuration file's name to the Path to project properties textbox in the Execute SonarQube Scanner build step you just created. If you placed the sonar-project.properties at the root of your project, you only need to add sonar-project.properties (with no path) to this textbox.
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 that Jenkins can use for reporting results to SonicQube 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.)
Add the Login Token to Jenkins
Now in the Jenkins web interface, choose the build you'd like to configure for SonarQube. On the left side of the screen, click on Configure and click on Build toward the top of the screen. Scroll down to the Execute SonarQube Scanner build step and enter the following for your security token in the Analysis properties text box:
sonar.login=YOUR SECURITY TOKEN
Save or Apply to save your login token. Now Jenkins can report scanner results for this project to SonarQube.
Choose Build Now in Jenkins to test the build with SonarQube.
Any issues found by axe DevTools Linter will be shown by clicking on Issues in the SonarCube web interface for your project. axe DevTools Linter issues are identified by AXE-LINTER-MD for markdown files, and AXE-LINTER-HTML for html files.
axe DevTools Linter Connector generates a JSON report that follows the SonarQube Generic Report format. For more information on the report format, see SonarQube Generic Report 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.