Integração do Axe Developer Hub com plataformas CI/CD

Requisitos:

• Seu projeto web utiliza dados do Git
• ID do projeto no Axe Developer Hub
• Deque API Key corresponding to your project type

Visão geral

O Axe Developer Hub oferece um serviço web REST que você pode usar como base para integração em suas implementações de CI/CD com serviços como GitLab e BitBucket. Se você estiver usando GitHub, por favor veja Utilizando a Ação do GitHub do Axe Developer Hub.

O serviço REST espera como entrada uma chave API do Axe Developer Hub, seu ID de projeto e um SHA de commit do Git. No objeto de resposta, você verá:

• O número de erros de acessibilidade encontrados durante a última execução do teste
• O número de erros de acessibilidade acima do limite de a11y
• Um URL direcionando para resultados detalhados no Axe Developer Hub

Recuperar Informações da Execução do Teste

O serviço web responde a uma solicitação GET e pode recuperar informações sobre um determinado SHA de commit do Git para o projeto especificado do Developer Hub.

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

Requisitos

Sua solicitação exigirá um parâmetro de caminho, um parâmetro de consulta e dois cabeçalhos.

• Servidor: https://axe.deque.com
• Ponto de extremidade: /api-pub/v1/axe-watcher/gh/<*:SHA*>
• Parâmetro de consulta: ?project_id=<your-project-id>
• Método de solicitação: GET

Parâmetro de Caminho: O parâmetro :SHA deve ser substituído pelo SHA de commit do Git que você deseja examinar.

Parâmetro de Consulta: Substitua '' pelo ID único do projeto que aparece na página de instruções após você criar um projeto. Para encontrar esta informação a qualquer momento após a configuração, vá para seus Projetos no Axe Developer Hub. Encontre seu projeto, vá para seu Configurações, e então selecione Configurar projeto para abrir a página de instruções.

Cabeçalhos: Dois cabeçalhos são necessários:

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

Exemplo de Solicitação:

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

(Cabeçalhos são necessários, mas não são mostrados.)

JSON de Resposta

O seguinte é um exemplo de corpo de resposta JSON retornado pelo serviço:

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

A tabela a seguir fornece informações sobre os valores na resposta JSON:

Respostas de Erro

Exemplos de Uso

Os exemplos a seguir mostram como acessar o endpoint REST. Em cada exemplo, você precisa definir os parâmetros necessários como variáveis de ambiente:

JavaScript (Node.js)

Este exemplo solicita resultados do Axe Developer Hub para o SHA especificado (na variável de ambiente GIT_SHA) e o ID do projeto especificado. Se novos erros de acessibilidade forem descobertos, a contagem é registrada no console. Caso contrário, 'axe clean!' é registrado no 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

Este exemplo usa curl e jq para retornar o número de violações na saída padrão.

#!/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 o serviço web retornar um erro de servidor, curl --fail sai com o código 22 e suprime o corpo da resposta. Use a opção --fail-with-body para também retornar o JSON da resposta como parte da saída padrão.