Integratie van Axe Developer Hub met CI/CD-platforms

Vereist:

• Je webproject gebruikt Git-gegevens
• Axe Developer Hub Project-ID
• Deque API-sleutel die overeenkomt met je projecttype

Overzicht

Axe Developer Hub biedt een REST-webservice die je kunt gebruiken als basis voor integratie in je CI/CD-implementaties met diensten zoals GitLab en BitBucket. Als je GitHub gebruikt, zie dan De Axe Developer Hub GitHub-actie gebruiken.

De REST-service verwacht als invoer een Axe Developer Hub API-sleutel, je project-ID en een Git-commit SHA. In het responsobject zie je:

• Het aantal toegankelijkheidsfouten dat is gevonden tijdens de laatste testronde
• Het aantal toegankelijkheidsfouten boven de a11y-drempel
• Een URL die naar gedetailleerde resultaten op Axe Developer Hub verwijst

Test Run Informatie Opvragen

De webservice reageert op een GET-verzoek en kan informatie ophalen over een specifieke Git-commit SHA voor het opgegeven Developer Hub-project.

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

Vereisten

Je verzoek vereist één padparameter, een queryparameter en twee headers.

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

Padparameter: De :SHA-parameter moet worden vervangen door de Git-commit SHA die je wilt onderzoeken.

Queryparameter: Vervang '' door de unieke project-ID die op de instructiepagina verschijnt nadat je een project hebt aangemaakt. Om deze informatie op elk moment na het instellen te vinden, ga je naar je Projecten in Axe Developer Hub. Zoek je project, ga naar zijn Instellingen, en selecteer Project configureren om de instructiepagina te openen.

Headers: Twee headers zijn vereist:

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

Behandel je API-sleutel als een geheim: bewaar deze in een omgevingsvariabele of in de secret-opslag van je CI/CD-platform in plaats van deze hard te coderen in je verzoeken.

Voorbeeldverzoek:

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

(Headers zijn vereist maar niet getoond.)

Respons-JSON

Het volgende toont een voorbeeld van een JSON-antwoordtekst die door de service wordt teruggegeven:

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

De volgende tabel geeft informatie over de waarden in het JSON-antwoord:

Foutreacties

Gerelateerde REST-eindpunten

Axe Developer Hub biedt aanvullende REST-eindpunten voor het programmatisch ophalen van sessiegegevens en resultaten. Zie Sessie- en Resultaten-API-referentie voor het sessie-eindpunt (lijst sessies voor een project met filteren en cursorpaginering) en het resultaten-eindpunt (haal samenvattende of volledige Universele JSON-resultaten op voor een specifieke sessie).

Voorbeelden van Gebruik

De volgende voorbeelden laten zien hoe je toegang krijgt tot het REST-eindpunt. In elk voorbeeld moet je de vereiste parameters instellen als omgevingsvariabelen:

JavaScript (Node.js)

Dit voorbeeld vraagt Axe Developer Hub-resultaten op voor de opgegeven SHA (in de GIT_SHA omgevingsvariabele) en opgegeven project-ID. Als er nieuwe toegankelijkheidsfouten worden ontdekt, wordt het aantal in de console weergegeven. Anders wordt 'axe clean!' in de console weergegeven.

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

Dit voorbeeld gebruikt curl en jq om het aantal overtredingen naar standaarduitvoer terug te geven.

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

Als de webservice een serverfout retourneert, verlaat curl --fail met code 22 en onderdrukt het de antwoordinhoud. Gebruik de --fail-with-body optie om het antwoord-JSON ook als onderdeel van de standaarduitvoer weer te geven.