Integrazione di axe Developer Hub con piattaforme CI/CD

Introduzione

Axe Developer Hub fornisce un servizio Web REST che puoi utilizzare come base per integrare axe Developer Hub nelle tue implementazioni CI/CD per servizi quali GitLab e BitBucket.

Il servizio REST si aspetta come input una chiave API di axe Developer Hub e un SHA di commit Git, e il suo oggetto di risposta contiene, tra gli altri dati, quanto segue:

• Il numero di errori di accessibilità rilevati durante l'ultimo test eseguito
• Il numero di errori di accessibilità oltre la soglia a11y
• Un'URL che fornisce risultati dettagliati su axe Developer Hub

(Vedere Response JSON per maggiori informazioni sull'intero oggetto risposta.)

Questo documento descrive in dettaglio il servizio REST e il suo oggetto di risposta e fornisce un esempio JavaScript che ne dimostra l'utilizzo.

Recupera informazioni sull'esecuzione del test

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

Recupera informazioni dell'axe Developer Hub sul Git commit SHA (GET) specificato.

Richiesta

Il servizio web risponde a una richiesta GET. La tua richiesta necessita di un parametro di percorso e due header.

• Server: https://axe.deque.com
• Endpoint: /api-pub/v1/axe-watcher/gh/:SHA
• Metodo di richiesta: GET

Path Parameter: Il parametro :SHA dovrebbe essere sostituito con l'SHA del commit Git a cui sei interessato.

Intestazioni: sono necessarie due intestazioni:

• Accept: application/json
• X-API-Key: chiave-API-del-tuo-progetto

Esempio di richiesta:

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

(Le intestazioni sono obbligatorie ma non vengono visualizzate.)

Risposta JSON

Di seguito è riportato un esempio del corpo della risposta JSON restituito dal servizio:

{
  "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 tabella seguente fornisce informazioni sui valori nella risposta JSON:

Risposte di errore

Se il servizio non riesce a trovare l'SHA specificato o se non è presente alcuna esecuzione di test associata a tale SHA, restituisce un codice di risposta 404 not found e un corpo JSON di errore:

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

Se la tua chiave API non è valida, riceverai un codice di risposta 401 unauthorized e un corpo JSON di errore:

{
  "error": "Invalid API key"
}

Esempi di utilizzo

Questa sezione contiene due esempi che mostrano come accedere all'endpoint REST in JavaScript e Bash (con curl). Per utilizzare questi esempi, è necessario impostare i parametri richiesti come variabili di ambiente:

Esempio di JavaScript

Questo esempio di codice JavaScript Node.js mostra come effettuare richieste all'endpoint REST di 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'esempio richiede i risultati di axe Developer Hub per l'SHA specificato (nella variabile di ambiente GIT_SHA) e, se si verificano nuovi errori di accessibilità, registra il numero nella console. Altrimenti, registra "axe clean!" sulla console.

Esempio di Bash

Il seguente esempio Bash utilizza curl e jq per restituire il numero di violazioni (il valore last_run_violation_count ) sull'output standard. Utilizza le stesse variabili di ambiente dell'esempio 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'

Se il servizio Web restituisce un errore del server, curl uscirà con un codice di uscita pari a 22 (senza output di risposta) a causa del --fail opzione. Puoi invece usare il --errore con corpo Opzione per restituire anche la risposta JSON sull'output standard in caso di errore. Per ulteriori informazioni, vedere Risposte di errore .

Vedere anche

Utilizza l'azione GitHub.