Integración de Axe Developer Hub con plataformas CI/CD

Introducción

Axe Developer Hub proporciona un servicio web REST que puede usar como base para integrar Axe Developer Hub en sus implementaciones de CI/CD para servicios como GitLab y BitBucket.

El servicio REST espera como entrada una clave API de axe Developer Hub y un SHA de commit de Git, y su objeto de respuesta contiene, entre otros datos, lo siguiente:

• La cantidad de errores de accesibilidad encontrados durante la última ejecución de prueba
• El número de errores de accesibilidad por encima del umbral a11y
• Una URL que proporciona resultados detallados sobre axe Developer Hub

(Consulte Respuesta JSON para obtener más información sobre todo el objeto de respuesta).

Este documento describe el servicio REST y su objeto de respuesta en detalle y proporciona un ejemplo de JavaScript que demuestra su uso.

Recuperar información de Ejecución de Test

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

Recupera información de Axe Developer Hub sobre el commit SHA de Git especificado (GET).

Solicitud

El servicio web responde a una solicitud GET. Su solicitud necesita un parámetro de ruta y dos encabezados.

• Servidor: https://axe.deque.com
• Endpoint: /api-pub/v1/axe-watcher/gh/:SHA
• Método de petición: GET

Parámetro de ruta: El parámetro :SHA debe reemplazarse con el SHA de confirmación de Git que le interesa.

Encabezados: Se requieren dos encabezados:

• Accept: application/json
• X-API-Key: clave API de su proyecto

Ejemplo de solicitud:

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

(Los encabezados son obligatorios pero no se muestran).

Respuesta JSON

A continuación se muestra un ejemplo de cuerpo de respuesta JSON devuelto por el servicio:

{
  "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"
}

La siguiente tabla proporciona información sobre los valores en la respuesta JSON:

Respuestas de error

Si el servicio no puede encontrar el SHA especificado o si no hay una ejecución de prueba asociada con ese SHA, devuelve un código de respuesta 404 no encontrado y un cuerpo JSON de error:

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

Si su clave API no es válida, recibirá un ** código de respuesta 401 no autorizado** y un cuerpo JSON de error:

{
  "error": "Invalid API key"
}

Ejemplos de uso

Esta sección contiene dos ejemplos que muestran cómo acceder al punto final REST en JavaScript y Bash (con curl). Para utilizar estos ejemplos, debe establecer los parámetros necesarios como variables de entorno:

Ejemplo de JavaScript

Este ejemplo de código JavaScript de Node.js muestra cómo realizar solicitudes al punto final REST de axe Developer Hub:

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()

La muestra solicita los resultados de axe Developer Hub para el SHA especificado (en la variable de entorno GIT_SHA) y, si hay nuevos errores de accesibilidad, registra el recuento en la consola. De lo contrario, registra en el log "¡axe limpio!" en la consola.

Ejemplo de bash

El siguiente ejemplo de Bash usa curl y jq para devolver el número de violaciones (el valor last_run_violation_count ) en la salida estándar. Utiliza las mismas variables de entorno que el ejemplo de JavaScript:

#!/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'

Si el servicio web devuelve un error de servidor, curl saldrá con un código de salida de 22 (sin salida de respuesta) debido a la --fail opción. En su lugar, puedes utilizar el --fallar-con-cuerpo Opción para devolver también la respuesta JSON en la salida estándar en caso de falla. Consulte Respuestas de error para obtener más información.

Consulte también

Utilice la acción de GitHub.