Integrating axe Developer Hub with CI/CD platforms

Introduction

Axe Developer Hub provides a REST web service that you can use as a basis for integrating axe Developer Hub into your CI/CD implementations for services such as GitLab and BitBucket.

The REST service expects as input an axe Developer Hub API key and Git commit SHA, and its response object contains, among other data, the following:

• The number of accessibility errors found during the last test run
• The number of accessibility errors over the a11y threshold
• A URL that provides detailed results on axe Developer Hub

(See Response JSON for more information about the entire response object.)

This document describes the REST service and its response object in detail and provides a JavaScript example demonstrating its use.

Retrieve Test Run Information

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/:SHA

Retrieves axe Developer Hub information about the specified Git commit SHA (GET).

Request

The web service responds to a GET request. Your request needs one path parameter and two headers.

• Server: https://axe.deque.com
• Endpoint: /api-pub/v1/axe-watcher/gh/:SHA
• Request method: GET

Path Parameter: The :SHA parameter should be replaced with the Git commit SHA you're interested in.

Headers: Two headers are required:

• Accept: application/json
• X-API-Key: your-project-api-key

Example Request:

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/9eabf5b536662000f79978c4d1b6e4eff5c8d785

(Headers are required but not shown.)

Response JSON

The following shows an example JSON response body returned from the service:

{
  "project_name": "Main test suite",
  "issues_over_a11y_threshold": 2,
  "last_run_created_at": "2024-01-21T17:16:39.267Z",
  "last_run_violation_count": 2,
  "last_run_new_violation_count": 2,
  "last_run_resolved_violation_count": 0,
  "last_run_page_state_count": 2,
  "difference_in_page_states": 0,
  "axe_url": "/axe-watcher/projects/19f12525-bcbe-4b4f-9b12-76de4f375d9b/branches/test-updates/compare/353ec943-b957-4abc-8d3a-5deed182a304/9288e977-b81f-49d7-83de-010255baede4?settings_hash=bc8334022f94bb2d9f69447946df487f&issues_over_a11y_threshold=2"
}

The following table provides information about the values in the JSON response:

Error Responses

If the service cannot find the specified SHA or if there is no test run associated with that SHA, it returns a 404 not found response code and an error JSON body:

{
  "error": "No Git information found"
}

If your API key is invalid, you'll receive a 401 unauthorized response code and an error JSON body:

{
  "error": "Invalid API key"
}

Usage Examples

This section contains two examples showing how to access the REST endpoint in JavaScript and Bash (with curl). To use these examples, you need to set the required parameters as environment variables:

JavaScript Example

This Node.js JavaScript code example shows how to make requests to the axe Developer Hub REST endpoint:

const https = require('https')
const assert = require('assert')

const { API_KEY, GIT_SHA } = process.env
assert(API_KEY, 'API_KEY is required')
assert(GIT_SHA, 'GIT_SHA is required')

const request = () =>
  new Promise((resolve, reject) => {
    /** @type {import('http').RequestOptions} */
    const options = {
      hostname: 'axe.deque.com',
      port: 443,
      path: `/api-pub/v1/axe-watcher/gh/${GIT_SHA}`,
      method: 'GET',
      headers: {
        'X-API-Key': API_KEY,
        Accept: 'application/json'
      }
    }

    let data = ''

    const req = https.request(options, res => {
      res.on('error', reject)

      res.on('data', d => {
        data += d
      })

      res.on('end', () => {
        const json = JSON.parse(data)
        resolve(json)
      })
    })
    req.end()
  })

const main = async () => {
  let json = null
  for (let tries = 0; tries < 10; tries++) {
    try {
      json = await request()
      break
    } catch (err) {
      console.warn(err.message)
    }
  }

  assert(json, 'Unable to fetch data from axe.deque.com')

  const { last_run_violation_count, axe_url, project_name, issues_over_a11y_threshold } = json

  if (last_run_violation_count) {
    console.log(
      `There are ${last_run_violation_count} violations in ${project_name}!`
    )
    console.log(`See ${axe_url} for more information`)
  } else {
    console.log('axe clean!')
  }
}

main()

The sample requests axe Developer Hub results for the specified SHA (in the GIT_SHA environment variable) and, if there are new accessibility errors, logs the count to the console. Otherwise, it logs "axe clean!" to the console.

Bash Example

The following Bash example uses curl and jq to return the number of violations (the last_run_violation_count value) on standard output. It uses the same environment variables as the JavaScript example:

#!/bin/bash

if [ -z $API_KEY ] || [ -z $GIT_SHA ]; then
  echo "Must set both API_KEY and GIT_SHA environment variables."
  exit 1
fi

curl --fail -H "Accept: application/json" -H "X-API-Key: $API_KEY" "https://axe.deque.com/api-pub/v1/axe-watcher/gh/$GIT_SHA" | jq '.last_run_violation_count'

If the web service returns a server error, curl will exit with an exit code of 22 (with no response output) due to the --fail option. You can instead use the --fail-with-body option to also return the response JSON on standard output upon failure. See Error Responses for more information.

See Also

Use the GitHub Action.