Integrazione di Axe Developer Hub con piattaforme CI/CD

Richiede:

• Il tuo progetto web utilizza dati Git
• ID Progetto di Axe Developer Hub
• Chiave API di Deque corrispondente al tipo di progetto

Panoramica

Axe Developer Hub fornisce un servizio web REST che puoi utilizzare come base per l'integrazione nelle tue implementazioni CI/CD con servizi come GitLab e BitBucket. Se utilizzi GitHub, consulta Utilizzo dell'Axe Developer Hub GitHub Action.

Il servizio REST richiede come input una chiave API di Axe Developer Hub, il tuo ID progetto e un SHA di commit Git. All'interno dell'oggetto di risposta vedrai:

• Il numero di errori di accessibilità riscontrati durante l'ultima esecuzione del test
• Il numero di errori di accessibilità sopra la soglia a11y
• Un URL che indirizza ai risultati dettagliati su Axe Developer Hub

Recupera informazioni sull'esecuzione del test

Il servizio web risponde a una richiesta GET e può recuperare informazioni su un particolare SHA di commit Git per il progetto specificato su Developer Hub.

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

Requisiti

La tua richiesta richiederà un parametro di percorso, un parametro di query e due intestazioni.

• Server: https://axe.deque.com
• Endpoint: /api-pub/v1/axe-watcher/gh/<*:SHA*>
• Parametro di query: ?project_id=<your-project-id>
• Metodo della richiesta: GET

Parametro di percorso: Il parametro :SHA dovrebbe essere sostituito con lo SHA del commit Git che vuoi esaminare.

Parametro di query: Sostituisci '' con l'ID univoco del progetto che appare sulla pagina delle istruzioni dopo aver creato un progetto. Per trovare queste informazioni in qualsiasi momento dopo la configurazione, vai su Progetti in Axe Developer Hub. Trova il tuo progetto, vai alla sua Impostazioni, quindi seleziona Configura progetto per aprire la pagina delle istruzioni.

Intestazioni: Sono richieste due intestazioni:

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

Tratta la tua chiave API come un segreto: conservala in una variabile d'ambiente o nel deposito segreto della tua piattaforma CI/CD anziché inserirla direttamente nei tuoi richieste.

Esempio di richiesta:

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

(Le intestazioni sono richieste ma non mostrate.)

Risposta JSON

Di seguito viene mostrato un esempio di corpo JSON di risposta 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 seguente tabella fornisce informazioni sui valori nella risposta JSON:

Risposte agli Errori

Endpoint REST correlati

Il centro per sviluppatori di Axe offre ulteriori endpoint REST per recuperare i dati delle sessioni e i risultati in modo programmatico. Vedi Riferimento API per Sessioni e Risultati per l'endpoint delle sessioni (elenco delle sessioni per un progetto con filtraggio e paginazione a cursore) e l'endpoint dei risultati (recupero del riassunto o dei risultati JSON universali completi per una sessione specifica).

Esempi di Utilizzo

I seguenti esempi mostrano come accedere all'endpoint REST. In ogni esempio, è necessario impostare i parametri richiesti come variabili d'ambiente:

JavaScript (Node.js)

Questo esempio richiede i risultati dell'Axe Developer Hub per lo SHA specificato (nella variabile d'ambiente GIT_SHA) e l'ID progetto specificato. Se vengono scoperti nuovi errori di accessibilità, il conteggio viene registrato nella console. Altrimenti, 'axe clean!' viene registrato nella 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

Questo esempio utilizza curl e jq per restituire il numero di violazioni nell'output 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'

Se il servizio web ritorna un errore del server, curl --fail esce con codice 22 e sopprime il corpo della risposta. Usa l'opzione --fail-with-body per restituire anche il JSON della risposta come parte dell'output standard.