Integrating axe Developer Hub with CI/CD platforms

Link to Integrating axe Developer Hub with CI/CD platforms copied to clipboard

Details about the REST service you can use to integrate axe Developer Hub into CI/CD services for various Git platforms such as GitLab or BitBucket.

Free Trial

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.

note

You must use the full 40 character Git commit SHA instead of a shortened version of it (such as a seven-character shortened SHA).

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:

Item Type Description
axe_url string The absolute path of these results on axe Developer Hub
difference_in_page_states number Numerical difference in page states compared to previous commit on the same branch
issues_over_a11y_threshold number Count of issues that exceed the a11y threshold
last_run_created_at string Data and time in ISO 8601 format, UTC timezone, millisecond granularity, of the test run
last_run_new_violation_count number Count of new accessibility errors
last_run_page_state_count number Count of page states
last_run_resolved_violation_count number Count of accessibility issues that were resolved since the previous commit on this branch
last_run_violation_count number Count of accessibility errors
project_name string The name of the project as shown in the project page

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:

Environment variable Description
API_KEY Your project's API key
GIT_SHA The Git commit SHA for which you'd like to obtain axe Developer Hub results

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.

note

The above sample does not test for errors such as an invalid API key or missing Git information.

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.dequelabs.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.