Integration des axe Developer Hub mit CI/CD-Plattformen

Einleitung

Axe Developer Hub stellt einen REST-Webdienst zur Verfügung, den Sie als Grundlage für die Integration von Axe Developer Hub in Ihre CI/CD-Implementierungen für Dienste wie GitLab und BitBucket verwenden können.

Der REST-Dienst erwartet als Eingabe einen API-Schlüssel von axe Developer Hub und einen Git-Commit-SHA. Sein Antwortobjekt enthält unter anderem Folgendes:

• Die Anzahl der beim letzten Testlauf gefundenen Barrierefreiheitsfehler
• Die Anzahl der Barrierefreiheitsfehler über dem a11y-Schwellenwert
• Eine URL, die detaillierte Ergebnisse zum Axe Developer Hub liefert

(Weitere Informationen zum gesamten Antwortobjekt finden Sie unter Response JSON .)

Dieses Dokument beschreibt den REST-Dienst und sein Antwortobjekt im Detail und bietet ein JavaScript-Beispiel, das seine Verwendung demonstriert.

Abrufen von Testlaufinformationen

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

Ruft axe Developer Hub-Informationen zum angegebenen Git-Commit-SHA (GET) ab.

Anfrage

Der Webdienst antwortet auf eine GET-Anfrage. Ihre Anfrage benötigt einen Pfadparameter und zwei Header.

• Server: https://axe.deque.com
• Endpunkt: /api-pub/v1/axe-watcher/gh/:SHA
• Anforderungsmethode: GET

Pfadparameter: Das :SHA Parameter sollte durch den Git-Commit-SHA ersetzt werden, an dem Sie interessiert sind.

Überschriften: Es werden zwei Überschriften benötigt:

• Accept: application/json
• X-API-Key: your-project-api-key

Beispielanfrage:

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

(Kopfzeilen sind erforderlich, werden aber nicht angezeigt.)

JSON-Antwort

Nachfolgend sehen Sie ein Beispiel für einen vom Dienst zurückgegebenen JSON-Antworttext:

{
  "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"
}

Die folgende Tabelle enthält Informationen zu den Werten in der JSON-Antwort:

Fehlerantworten

Wenn der Dienst den angegebenen SHA nicht finden kann oder wenn mit diesem SHA kein Testlauf verknüpft ist, gibt er den Antwortcode 404 nicht gefunden und einen JSON-Fehlertext zurück:

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

Wenn Ihr API-Schlüssel ungültig ist, erhalten Sie den Antwortcode 401 Nicht autorisiert und einen JSON-Fehlertext:

{
  "error": "Invalid API key"
}

Anwendungsbeispiele

Dieser Abschnitt enthält zwei Beispiele, die zeigen, wie in JavaScript und Bash (mit curl) auf den REST-Endpunkt zugegriffen wird. Um diese Beispiele zu verwenden, müssen Sie die erforderlichen Parameter als Umgebungsvariablen festlegen:

JavaScript-Beispiel

Dieses Node.js-JavaScript-Codebeispiel zeigt, wie Anfragen an den REST-Endpunkt des axe Developer Hub gestellt werden:

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()

Das Beispiel fordert die Ergebnisse des axe Developer Hub für den angegebenen SHA (in der Umgebungsvariable GIT_SHA) an und protokolliert die Anzahl in der Konsole, wenn neue Barrierefreiheitsfehler auftreten. Andernfalls protokolliert es „axe clean!“ in der Konsole.

Bash-Beispiel

Das folgende Bash-Beispiel verwendet curl und jq , um die Anzahl der Verstöße (den last_run_violation_count Wert) in der Standardausgabe zurückzugeben. Es verwendet die gleichen Umgebungsvariablen wie das JavaScript-Beispiel:

#!/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'

Wenn der Webdienst einen Serverfehler zurückgibt, wird curl mit dem Exit-Code 22 beendet (ohne Antwortausgabe) aufgrund der --fail Option. Sie können stattdessen die --fail-with-body option, um die JSON-Antwort bei einem Fehler auch in der Standardausgabe zurückzugeben. Weitere Informationen finden Sie unter Fehlerantworten .

Siehe auch

Verwenden Sie die GitHub-Aktion.