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

Exigences :

• Votre projet web utilise des données Git
• ID de projet 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 consulter Utiliser l'action GitHub d'Axe Developer Hub.

Le service REST attend comme entrée une clé API 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 du test
• Le nombre d'erreurs d'accessibilité au-delà du seuil a11y
• Une URL menant à des résultats détaillés sur Axe Developer Hub

Récupérer les informations de l'exécution du 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 d'instructions après avoir créé un projet. Pour trouver cette information à tout moment après la configuration, accédez à vos Projets dans Axe Developer Hub. Trouvez votre projet, allez à son Paramètres, puis sélectionnez Configurer le projet pour ouvrir la page d'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 stockage 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

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

Points de terminaison REST associés

Axe Developer Hub fournit des points de terminaison REST supplémentaires pour récupérer les données de session et les résultats par programmation. Voir Référence API des sessions et des résultats pour le point de terminaison des sessions (lister les sessions pour un projet avec filtrage et pagination par curseur) et le point de terminaison des résultats (récupérer les résultats Universal JSON sommaires ou complets pour une session spécifique).

Exemples d'utilisation

Les exemples suivants montrent comment accéder au point de terminaison REST. Dans chaque exemple, vous devez définir les paramètres requis en tant que variables d'environnement :

JavaScript (Node.js)

Cet exemple demande les résultats d'Axe Developer Hub 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 de serveur, curl --fail se termine avec le code 22 et supprime le corps de la réponse. Utilisez l'option --fail-with-body pour retourner également le JSON de la réponse dans la sortie standard.