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

Requisitos:

• Su proyecto web utiliza datos de Git
• ID del proyecto en Axe Developer Hub
• Clave de API de Deque correspondiente a su tipo de proyecto

Descripción general

Axe Developer Hub ofrece un servicio web REST que usted puede utilizar como base para la integración en sus implementaciones CI/CD con servicios como GitLab y BitBucket. Si está utilizando GitHub, por favor vea Usar el GitHub Action de Axe Developer Hub.

El servicio REST espera como entrada una clave API de Axe Developer Hub, su ID de proyecto y un SHA de commit de Git. Dentro del objeto de respuesta verá:

• El número de errores de accesibilidad encontrados durante la última ejecución de pruebas
• El número de errores de accesibilidad sobre el umbral de a11y
• Una URL que dirige a resultados detallados en Axe Developer Hub

Recuperar información de ejecución de pruebas

El servicio web responde a una solicitud GET y puede recuperar información sobre un SHA de commit de Git en particular para el proyecto especificado en Developer Hub.

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/<:SHA>?project_id=<your-project-id>

Requisitos

Su solicitud requerirá un parámetro de ruta, un parámetro de consulta y dos encabezados.

• Servidor: https://axe.deque.com
• Punto final: /api-pub/v1/axe-watcher/gh/<*:SHA*>
• Parámetro de consulta: ?project_id=<your-project-id>
• Método de solicitud: GET

Parámetro de ruta: El parámetro :SHA debe ser reemplazado con el SHA de commit de Git que desea examinar.

Parámetro de consulta: Reemplace '' con el ID único del proyecto que aparece en la página de instrucciones después de que crea un proyecto. Para encontrar esta información en cualquier momento después de la configuración, vaya a sus Proyectos en Axe Developer Hub. Encuentre su proyecto, vaya a su Configuraciones, luego seleccione Configurar proyecto para abrir la página de instrucciones.

Encabezados: Se requieren dos encabezados:

• Accept: application/json
• X-API-Key:<your-personal-api-key>

Trate su clave de API como un secreto: guárdela en una variable de entorno o en el almacén de secretos de su plataforma CI/CD en lugar de codificarla de forma explícita en sus solicitudes.

Ejemplo de solicitud:

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/9eabf5b536662000f79978c4d1b6e4eff5c8d785?project_id=268a7e7d-cb23-45a0-aa7d-6f35e3bed2c9

(Se requieren encabezados pero no se muestran.)

Respuesta JSON

Lo siguiente muestra un ejemplo del 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

Puntos Finales REST Relacionados

Axe Developer Hub proporciona puntos finales REST adicionales para recuperar datos de sesión y resultados programáticamente. Vea Referencia de la API de Sesiones y Resultados para el punto final de Sesiones (listar sesiones para un proyecto con filtrado y paginación con cursor) y el punto final de Resultados (recuperar resumen o resultados JSON universales completos para una sesión específica).

Ejemplos de Uso

Los siguientes ejemplos muestran cómo acceder al punto final REST. En cada ejemplo, necesitas establecer los parámetros requeridos como variables de entorno:

JavaScript (Node.js)

Este ejemplo solicita resultados de Axe Developer Hub para el SHA especificado (en la variable de entorno GIT_SHA) y el ID de proyecto especificado. Si se descubren nuevos errores de accesibilidad, la cuenta se registra en la consola. De lo contrario, '¡axe limpio!' se registra en la consola.

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

const { API_KEY, PROJECT_ID, GIT_SHA } = process.env
assert(API_KEY, 'API_KEY is required')
assert(PROJECT_ID, 'PROJECT_ID 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}?project_id=${PROJECT_ID}`,
      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()

Bash

Este ejemplo utiliza curl y jq para devolver el número de violaciones en la salida estándar.

#!/bin/bash

if [ -z $API_KEY ] || [ -z $PROJECT_ID ] || [ -z $GIT_SHA ]; then
  echo "Must set the API_KEY, PROJECT_ID, 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?project_id=$PROJECT_ID" | jq '.last_run_violation_count'

Si el servicio web devuelve un error del servidor, curl --fail sale con el código 22 y suprime el cuerpo de la respuesta. Usa la opción --fail-with-body para también devolver el JSON de la respuesta como parte de la salida estándar.