Intégrer Axe Developer Hub avec les plateformes CI/CD

Prérequis :

• Votre projet Web utilise les données Git
• ID de projet dans Axe Developer Hub
• Clé API Deque correspondant à votre type de projet

Aperçu

Axe Developer Hub fournit un service web REST que vous pouvez utiliser comme base pour l'intégration dans vos implémentations CI/CD avec des services tels que GitLab et BitBucket. Si vous utilisez GitHub, veuillez voir Utilisation de l'action GitHub d'Axe Developer Hub.

Le service REST prévoit en entrée une clé API d'Axe Developer Hub, votre ID de projet, et un SHA de commit Git. Dans l'objet de réponse, vous verrez :

• Le nombre d'erreurs d'accessibilité trouvées lors de la dernière exécution de test
• Le nombre d'erreurs d'accessibilité dépassant le seuil a11y
• Une URL menant aux résultats détaillés sur Axe Developer Hub

Récupérer les informations d'une exécution de test

Le service web répond à une requête GET et peut récupérer des informations sur un SHA de commit Git particulier pour le projet Developer Hub spécifié.

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

Exigences

Votre requête nécessitera un paramètre de chemin, un paramètre de requête et deux en-têtes.

• Serveur : https://axe.deque.com
• Point de terminaison : /api-pub/v1/axe-watcher/gh/<*:SHA*>
• Paramètre de requête : ?project_id=<your-project-id>
• Méthode de requête : GET

Paramètre de chemin : Le paramètre :SHA doit être remplacé par le SHA de commit Git que vous souhaitez examiner.

Paramètre de requête : Remplacez '' par l'ID de projet unique qui apparaît sur la page des instructions après avoir créé un projet. Pour retrouver cette information à tout moment après la configuration, rendez-vous dans vos projets sur Axe Developer Hub. Trouvez votre projet, allez à son Paramètres, puis sélectionnez Configurer le projet pour ouvrir la page des instructions.

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

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

Traitez votre clé API comme un secret : stockez-la dans une variable d'environnement ou dans le magasin de secrets de votre plateforme CI/CD plutôt que de la coder en dur dans vos requêtes.

Exemple de requête :

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

(Les en-têtes sont requis mais non affichés.)

Réponse JSON

Voici un exemple de corps de réponse JSON retourné 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 dans la réponse JSON :

Réponses d'erreur

Points d'extrémité REST associés

Le Hub Développeur Axe fournit des points d'extrémité REST supplémentaires pour récupérer les données de session et les résultats de manière programmatique. Voir Référence API des sessions et des résultats pour le point d'extrémité des Sessions (lister les sessions pour un projet avec filtrage et pagination par curseur) et le point d'extrémité des Résultats (récupérer le résumé ou les résultats JSON universels complets pour une session spécifique).

Exemples d'utilisation

Les exemples suivants montrent comment accéder au point d'extrémité REST. Dans chaque exemple, vous devez définir les paramètres requis comme variables d'environnement :

JavaScript (Node.js)

Cet exemple demande les résultats du Hub Développeur Axe pour le SHA spécifié (dans la variable d'environnement GIT_SHA) et l'identifiant de projet spécifié. Si de nouvelles erreurs d'accessibilité sont découvertes, le nombre est enregistré dans la console. Sinon, 'axe clean!' est enregistré dans la console.

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

Cet exemple utilise curl et jq pour retourner le nombre de violations sur la sortie standard.

#!/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 le service web renvoie une erreur serveur, curl --fail sort avec le code 22 et supprime le corps de la réponse. Utilisez l'option --fail-with-body pour également retourner le JSON de réponse dans la sortie standard.