Using axe DevTools Linter with Jenkins

You can submit your code to axe DevTools Linter to be checked for accessibility problems as part of a Jenkins build. This guide shows how to set up a build step in Jenkins to invoke axe DevTools Linter Connector and report to Jenkins any accessibility errors found.

Requirements

To add axe DevTools Linter to Jenkins builds, you need to have the following software installed:

• Jenkins. See Installing Jenkins for instructions on setting up Jenkins.
• axe DevTools Linter and Connector. See Setting up the On-Premises Server and Using axe DevTools Linter Connector for setup instructions.
• The axe-linter-jenkins-sonarqube.sh build script. Instructions for installing this script are in the next section.

Installing the Jenkins Build Script

You should have a compressed tar file containing the sample Jenkins build script. The tar file should be called axeScripts.tar.gz. You can extract the script by typing the following:

tar xvfz axeScripts.tar.gz

There should be one file extracted from the archive, axe-linter-jenkins-sonarqube.sh. Edit the script to reflect the correct URL and port of your axe DevTools Linter instance (whether SaaS or on-premises). There are two environment variables in the script at lines 12 and 13 that you might need to change, as shown below:

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

Now create a directory in /opt with the admin account using the following command:

sudo mkdir /opt/axeScripts

Copy the script to /opt/axeScripts:

sudo cp axe-linter-jenkins-sonarqube.sh /opt/axeScripts

Set the script's execute flag:

sudo chmod +x /opt/axeScripts/axe-linter-jenkins-sonarqube.sh

Adding a Build Step

For this example, you will use an existing project and simply add a new build step.

Choose the job that you'd like to modify and choose Configure in the left panel. Then select the Build tab to scroll to the Build section, where you will choose the Add build step dropdown and select Execute shell.

In the new Execute shell build step, enter the following in the Command text box:

/opt/axeScripts/axe-linter-jenkins-sonarqube.sh

Select the Advanced... button on this build step to set the exit code that will indicate an error to Jenkins. Enter 1 in the Exit code to set build unstable text box. The script returns 1 if there are any accessibility errors.

Choose Save or Apply to accept your changes.

The Build Script

The axe-linter-jenkins-sonarqube.sh script runs axe DevTools Linter Connector over the files in the root directory of the Jenkins build and generates a report, axe-linter-report.json. The script then searches the report for any errors and reports the error by returning 1, which causes the build to be marked as unstable in Jenkins.

The source code for the build script is shown below:

#!/bin/bash
# axe-linter-jenkins-sonarqube.sh
# This script will setup the environment variables needed for axe-linter-connector
# and execute axe-linter-connector. The output file will be reviewed and call back with exit codes:
## 0 - No Accessibility Defects
## 1 - axe DevTools Linter Detected Accessibility Defects
## 2 - Execution problem, or axe DevTools Linter unavailable.

echo "axe DevTools Linter Jenkins SonarQube Starting $(date)"

# Setup variables for axe DevTools Linter
export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000

# Configure outfile: output in Generic Issue Import Format for SonarQube in execution directory.

OutFile="axe-linter-report.json"

# Remove previous results
rm $OutFile

# execute axe-linter-connector
axe-linter-connector -s . -d .

echo "Checking for Results $(date)"

if [ ! -f "$OutFile" ];
   then
     echo "$OutFile Does Not Exit"
     exit 2

   elif cat "$OutFile" | grep -q "BUG"; then
      echo "axe DevTools Linter Accessibility Defect Detected"
      exit 1
   else
     echo "No axe DevTools Linter Bugs Detected"
fi
exit 0

The result from this script is a simple pass/fail depending on whether there are any accessibility errors found by axe DevTools Linter. No other information is sent to Jenkins. The report generated, axe-linter-report.json does, however, contain more specific information about accessibility errors: filename, line number, and accessibility error information. One way to capture this information is to import the report into SonarQube. For more information, see Using axe DevTools Linter with SonarQube