Integration von Axe Developer Hub mit CI/CD-Plattformen

Erforderlich:

• Ihr Webprojekt verwendet Git-Daten
• Axe Developer Hub Projekt-ID
• Deque-API-Schlüssel entsprechend Ihrem Projekttyp

Übersicht

Der Axe Developer Hub bietet einen REST-Webdienst, den Sie als Basis für die Integration in Ihre CI/CD-Implementierungen mit Diensten wie GitLab und BitBucket verwenden können. Wenn Sie GitHub verwenden, lesen Sie bitte Verwendung der Axe Developer Hub GitHub Action.

Der REST-Dienst erwartet als Eingabe einen Axe Developer Hub-API-Schlüssel, Ihre Projekt-ID und einen Git-Commit-SHA. Im Antwortobjekt sehen Sie:

• Die Anzahl der bei der letzten Testlauf gefundenen Barrierefreiheitsfehler
• Die Anzahl der Barrierefreiheitsfehler über dem a11y-Schwellenwert
• Eine URL, die zu detaillierten Ergebnissen im Axe Developer Hub führt

Testlauf-Informationen abrufen

Der Webdienst antwortet auf eine GET-Anfrage und kann Informationen über einen bestimmten Git-Commit-SHA für das angegebene Developer Hub-Projekt abrufen.

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

Anforderungen

Ihre Anfrage erfordert einen Pfadparameter, einen Abfrageparameter und zwei Header.

• Server: https://axe.deque.com
• Endpunkt: /api-pub/v1/axe-watcher/gh/<*:SHA*>
• Abfrageparameter: ?project_id=<your-project-id>
• Anfragemethode: GET

Pfadparameter: Der :SHA-Parameter sollte durch den Git-Commit-SHA ersetzt werden, den Sie untersuchen möchten.

Abfrageparameter: Ersetzen Sie '' durch die eindeutige Projekt-ID, die auf der Anleitungsseite erscheint, nachdem Sie ein Projekt erstellt haben. Um diese Informationen jederzeit nach der Einrichtung zu finden, gehen Sie zu Ihren Projekten im Axe Developer Hub. Suchen Sie Ihr Projekt, gehen Sie zu dessen Einstellungen, und wählen Sie dann Projekt konfigurieren, um die Anleitungsseite zu öffnen.

Header: Zwei Header sind erforderlich:

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

Behandeln Sie Ihren API-Schlüssel als Geheimnis: Speichern Sie ihn in einer Umgebungsvariable oder im Geheimnisspeicher Ihrer CI/CD-Plattform, anstatt ihn in Ihren Anfragen fest zu codieren.

Beispielanfrage:

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

(Header sind erforderlich, werden aber nicht angezeigt.)

Antwort-JSON

Das folgende Beispiel zeigt einen JSON-Antwortkörper, der vom Dienst zurückgegeben wird:

{
  "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 liefert Informationen über die Werte im JSON-Antwort:

Fehlerantworten

Zugehörige REST-Endpunkte

Das Axe Developer Hub bietet zusätzliche REST-Endpunkte, um Sitzungsdaten und Ergebnisse programmgesteuert abzurufen. Siehe Sessions- und Ergebnis-API-Referenz für den Sitzungsendpunkt (Liste der Sitzungen für ein Projekt mit Filterung und Cursor-Paginierung) und den Ergebnisendpunkt (Abruf der Zusammenfassung oder vollständige Universal JSON-Ergebnisse für eine bestimmte Sitzung).

Beispiele zur Nutzung

Die folgenden Beispiele zeigen, wie auf den REST-Endpunkt zugegriffen wird. In jedem Beispiel müssen Sie die erforderlichen Parameter als Umgebungsvariablen festlegen:

JavaScript (Node.js)

Dieses Beispiel fordert Ergebnisse aus dem Axe Developer Hub für den angegebenen SHA (in der Umgebungsvariable GIT_SHA) und die angegebene Projekt-ID an. Wenn neue Barrierefreiheitsfehler entdeckt werden, wird die Anzahl in der Konsole protokolliert. Andernfalls wird „axe sauber!“ in der Konsole protokolliert.

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

Dieses Beispiel verwendet curl und jq, um die Anzahl der Verstöße im Standardoutput zurückzugeben.

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

Wenn der Webdienst einen Serverfehler zurückgibt, beendet curl --fail sich mit Code 22 und unterdrückt den Antwortinhalt. Verwenden Sie die --fail-with-body Option, um auch das Antwort-JSON als Teil des Standardoutputs zurückzugeben.