Integration von Axe Developer Hub mit CI/CD-Plattformen

Erforderlich:

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

Übersicht

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

Der REST-Service erwartet als Eingabe einen Axe Developer Hub API-Schlüssel, Ihre Projekt-ID und einen Git-Commit-SHA. Innerhalb des Antwortobjekts sehen Sie:

• Die Anzahl der Barrierefreiheitsfehler, die während des letzten Testruns gefunden wurden
• Die Anzahl der Barrierefreiheitsfehler über dem a11y-Schwellenwert
• Eine URL mit detaillierten Ergebnissen auf Axe Developer Hub

Testlauf-Informationen abrufen

Der Webservice 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 benötigt 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 nach der Erstellung eines Projekts erscheint. Um diese Informationen zu einem späteren Zeitpunkt zu finden, gehen Sie zu Ihren Projekten in Axe Developer Hub. Finden Sie Ihr Projekt, gehen Sie zu dessen Einstellungen, und wählen Sie 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 Umgebungsvariablen 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, aber nicht angezeigt.)

Antwort-JSON

Das Folgende zeigt einen Beispiel-JSON-Antworttext, der vom Service 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 gibt Informationen über die Werte im JSON-Antworttext:

Fehlerantworten

Verwandte REST-Endpunkte

Der Axe Developer Hub bietet zusätzliche REST-Endpunkte zum programmgesteuerten Abrufen von Sitzungsdaten und Ergebnissen. Siehe API-Referenz für Sitzungen und Ergebnisse für den Sitzungsendpunkt (Sitzungen für ein Projekt mit Filterung und Cursor-Paginierung auflisten) und den Ergebnisendpunkt (Zusammenfassung oder vollständige Universal JSON-Ergebnisse für eine bestimmte Sitzung abrufen).

Verwendungsbeispiele

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

JavaScript (Node.js)

Dieses Beispiel fordert die Ergebnisse des Axe Developer Hub für die angegebene SHA (in der Umgebungsvariablen GIT_SHA) und die angegebene Projekt-ID an. Wenn neue Barrierefreiheitsfehler entdeckt werden, wird die Anzahl im Konsolenprotokoll ausgegeben. Andernfalls wird 'axe clean!' im Konsolenprotokoll ausgegeben.

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 in der Standardausgabe 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 sich curl --fail mit Code 22 und unterdrückt den Antwortinhalt. Verwenden Sie die --fail-with-body-Option, um das Antwort-JSON ebenfalls als Teil der Standardausgabe zurückzugeben.