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

Requisitos:

• Tu proyecto web utiliza datos de Git
• ID de Proyecto de Axe Developer Hub
• Clave API de Deque correspondiente a tu tipo de proyecto

Visión general

Axe Developer Hub proporciona un servicio web REST que puedes usar como base para la integración en tus implementaciones de CI/CD con servicios como GitLab y BitBucket. Si estás utilizando GitHub, por favor ve a Usando la acción de GitHub de Axe Developer Hub.

El servicio REST espera como entrada una clave API de Axe Developer Hub, tu ID de proyecto y un SHA de commit de Git. En el objeto de respuesta verás:

• El número de errores de accesibilidad encontrados durante la última ejecución de prueba
• El número de errores de accesibilidad por encima del umbral de a11y
• Una URL que dirige a los 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 de Developer Hub.

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

Requisitos

Tu solicitud requerirá un parámetro de ruta, un parámetro de consulta y dos cabeceras.

• 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 por el SHA de commit de Git que deseas examinar.

Parámetro de consulta: Reemplaza '' con el ID de proyecto único que aparece en la página de instrucciones después de crear un proyecto. Para encontrar esta información en cualquier momento después de la configuración, ve a tus Proyectos en Axe Developer Hub. Encuentra tu proyecto, ve a su Configuraciones, luego selecciona Configurar proyecto para abrir la página de instrucciones.

Cabeceras: Se requieren dos cabeceras:

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

Trata tu clave API como un secreto: guárdala en una variable de entorno o en el almacén de secretos de tu plataforma CI/CD en lugar de codificarla directamente en tus solicitudes.

Solicitud de ejemplo:

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

(Las cabeceras son requeridas pero no se muestran.)

Respuesta JSON

A continuación se 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

Endpoints REST relacionados

El Axe Developer Hub proporciona endpoints REST adicionales para recuperar datos de sesiones y resultados de manera programática. Consulte Referencia de la API de Sesiones y Resultados para el endpoint de Sesiones (listar sesiones de un proyecto con filtrado y paginación por cursor) y el endpoint de Resultados (recuperar un resumen o resultados completos en JSON Universal 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 del 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, el conteo se registra en la consola. De lo contrario, se registra '¡axe limpio!' 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.