Using the axe-linter Server with Jenkins
You can submit your code to the axe-linter Server 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 the Using the axe-linter Connector and report to Jenkins any accessibility errors found.
To add the axe-linter Server to Jenkins builds, you need to have the following software installed:
- Jenkins. See Installing Jenkins for instructions on setting up Jenkins.
- The axe-linter Server and Connector. See Setting up the On-Premises Server and Using the axe-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-linter Server. 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:
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 the axe-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 teh axe-linter-connector # and execute the axe-linter-connector. The output file will be reviewed and call back with exit codes: ## 0 - No Accessibility Defects ## 1 - axe-linter Detected Accessibility Defects ## 2 - Execution problem, or Axe-Linter Server unavailable. echo "axe-linter Jenkins SonarQube Starting $(date)" # Setup variables for axe-linter Server 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-linter Accessibility Defect Detected" exit 1 else echo "No axe-linter Connector 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 the axe-linter Server. 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-linter Server with SonarQube