Intégration d'axe Developer Hub avec les plateformes CI/CD

Introduction

Axe Developer Hub fournit un service Web REST que vous pouvez utiliser comme base pour intégrer axe Developer Hub dans vos implémentations CI/CD pour des services tels que GitLab et BitBucket.

Le service REST attend en entrée une clé API axe Developer Hub et un SHA de validation Git, et son objet de réponse contient, entre autres données, les éléments suivants :

• Le nombre d'erreurs d'accessibilité détectées lors du dernier test
• Le nombre d'erreurs d'accessibilité dépassant le seuil a11y
• Une URL qui fournit des résultats détaillés sur axe Developer Hub

(Voir JSON de réponse pour plus d'informations sur l'objet de réponse complet.)

Ce document décrit en détail le service REST et son objet de réponse et fournit un exemple JavaScript démontrant son utilisation.

Récupérer les informations sur l'exécution du test

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

Récupère les informations du Hub de développement axe sur le commit Git SHA (GET) spécifié.

Requête

Le service Web répond à une requête GET. Votre demande nécessite un paramètre de chemin et deux en-têtes.

• Serveur: https://axe.deque.com
• Endpoint : /api-pub/v1/axe-watcher/gh/* : SHA*
• Méthode de requête : GET

Paramètre de chemin : Le paramètre SHA doit être remplacé par le SHA de validation Git qui vous intéresse.

En-têtes : Deux en-têtes sont obligatoires :

• Accept: application/json
• X-API-Key: clé API de votre projet

Exemple de demande :

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

(Les en-têtes sont obligatoires mais ne sont pas affichés.)

Réponse JSON

Ce qui suit montre un exemple de corps de réponse JSON renvoyé par le 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"
}

Le tableau suivant fournit des informations sur les valeurs de la réponse JSON :

Réponses d'erreur

Si le service ne parvient pas à trouver le SHA spécifié ou s'il n'existe aucun test associé à ce SHA, il renvoie un code de réponse 404 not found et un corps JSON d'erreur :

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

Si votre clé API n'est pas valide, vous recevrez un code de réponse 401 non autorisé et un corps JSON d'erreur :

{
  "error": "Invalid API key"
}

Exemples d'utilisation

Cette section contient deux exemples montrant comment accéder au point de terminaison REST en JavaScript et Bash (avec curl). Pour utiliser ces exemples, vous devez définir les paramètres requis en tant que variables d'environnement :

Exemple JavaScript

Cet exemple de code JavaScript Node.js montre comment effectuer des requêtes vers le point de terminaison 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()

L'exemple demande les résultats de axe Developer Hub pour le SHA spécifié (dans la variable d'environnement GIT_SHA) et, s'il y a de nouvelles erreurs d'accessibilité, enregistre le nombre dans la console. Sinon, il enregistre « axe clean ! » dans la console.

Exemple de Bash

L'exemple Bash suivant utilise curl et jq pour renvoyer sur la sortie standard le nombre de violations (la valeur last_run_violation_count ). Il utilise les mêmes variables d'environnement que l'exemple 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 le service Web renvoie une erreur de serveur, curl se terminera avec un code de sortie de 22 (sans sortie de réponse) en raison de --fail option. Vous pouvez plutôt utiliser --échec-avec-corps-de-réponse Option permettant également de renvoyer la réponse JSON sur la sortie standard en cas d'échec. Voir Réponses d'erreur pour plus d'informations.

Voir aussi

Utilisez l'action GitHub.