Integrazione di Axe Developer Hub con piattaforme CI/CD

Richiede:

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

Panoramica

Axe Developer Hub fornisce un servizio web REST che puoi usare come base per l'integrazione nelle tue implementazioni CI/CD con servizi come GitLab e BitBucket. Se utilizzi GitHub, ti preghiamo di vedere Utilizzare l'Azione GitHub di Axe Developer Hub.

Il servizio REST si aspetta come input una chiave API di Axe Developer Hub, il tuo ID progetto e un SHA del commit Git. Nel blocco di risposta vedrai:

• Il numero di errori di accessibilità trovati durante l'ultima esecuzione del test
• Il numero di errori di accessibilità oltre il soglia a11y
• Un URL che rimanda ai risultati dettagliati su Axe Developer Hub

Recupera Informazioni sul Test

Il servizio web risponde a una richiesta GET e può recuperare informazioni su un particolare SHA del 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 query e due intestazioni.

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

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

Parametro di Query: Sostituisci '' con l'ID progetto univoco che appare nella pagina delle istruzioni dopo che hai creato un progetto. Per trovare questa informazione in qualsiasi momento dopo l'installazione, vai alle tue Progetti in Axe Developer Hub. Trova il tuo progetto, vai al suo 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: memorizzala in una variabile d'ambiente o nel secret store della tua piattaforma CI/CD anziché codificarla direttamente nelle tue 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 della risposta JSON restituita 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 di Errore

Endpoint REST Correlati

Axe Developer Hub fornisce endpoint REST aggiuntivi per recuperare i dati delle sessioni e i risultati in modo programmatico. Vedi Riferimento API per Sessioni e Risultati per l'endpoint delle Sessioni (elenca le sessioni per un progetto con filtri e paginazione a cursore) e l'endpoint dei Risultati (recupera il riepilogo o i 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 dall'Axe Developer Hub per lo SHA specificato (nella variabile d'ambiente GIT_SHA) e per l'ID progetto specificato. Se vengono scoperti nuovi errori di accessibilità, il conteggio viene registrato nella console. Altrimenti, viene registrato 'axe clean!' 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 restituisce 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.