Axe Developer HubをCI/CDプラットフォームに統合する

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Axe Developer HubのRESTウェブサービスを様々なGitプラットフォームで利用する

Not for use with personal data

必要条件:

概要

Axe Developer Hubは、GitLabやBitBucketなどのサービスと統合するための基盤として使用できるRESTウェブサービスを提供します。GitHubを使用している場合は、Axe Developer Hub GitHub Actionを使用するをご覧ください。

RESTサービスは、入力としてAxe Developer Hub APIキー、プロジェクトID、およびGitコミットSHAを期待します。レスポンスオブジェクトには以下が表示されます:

  • 最後のテスト実行中に見つかったアクセシビリティエラーの数
  • a11yしきい値を超えるアクセシビリティエラーの数
  • Axe Developer Hubの詳細な結果へのURL

テスト実行情報を取得する

ウェブサービスはGETリクエストに応答し、指定されたDeveloper Hubプロジェクトの特定のGitコミットSHAに関する情報を取得できます。

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

要件

リクエストには1つのパスパラメータ、クエリパラメータ、2つのヘッダーが必要です。

  • サーバー: https://axe.deque.com
  • エンドポイント: /api-pub/v1/axe-watcher/gh/<*:SHA*>
  • クエリパラメータ: ?project_id=<your-project-id>
  • リクエストメソッド: GET

パスパラメータ: :SHAパラメータは、検査したいGitコミットSHAに置き換える必要があります。

クエリパラメータ: 『』を、プロジェクト作成後の指示ページに表示される一意のプロジェクトIDに置き換えます。セットアップ後の任意の時点でこの情報を確認するには、Axe Developer Hubのプロジェクトに移動します。プロジェクトを見つけてその設定に移動し、指示ページを開くためにプロジェクトを設定するを選択します。

ヘッダー: 2つのヘッダーが必要です:

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

リクエスト例:

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

(ヘッダーは必要ですが表示されません。)

レスポンスJSON

以下はサービスから返されるJSONレスポンスボディの例を示しています:

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

以下の表は、JSONレスポンス内の値に関する情報を提供しています:

項目 タイプ 説明
axe_url string Axe Developer Hubにおけるこれらの結果の絶対パス
difference_in_page_states number 同じブランチ内の前コミットと比較したページの状態の数値差
issues_over_a11y_threshold number a11yしきい値を超える問題の数
last_run_created_at string テスト実行の日時(ISO 8601形式、UTCタイムゾーン、ミリ秒精度)
last_run_new_violation_count number 新たなアクセシビリティエラーの数
last_run_page_state_count number ページ状態の数
last_run_resolved_violation_count number このブランチの前回のコミット以降に解決されたアクセシビリティ問題の数
last_run_violation_count number アクセシビリティエラーの数
project_name string Axe Developer Hubのプロジェクトページに表示されるプロジェクト名

エラーレスポンス

ステータス 原因 レスポンスボディ
404 Not Found SHAが見つからない、または関連付けられたテストランが存在しない { "error": "No Git information found" }
401 Unauthorized 無効なAPIキー { "error": "Invalid API key" }

使用例

以下の例はRESTエンドポイントにアクセスする方法を示しています。各例では、必要なパラメータを環境変数として設定する必要があります。

環境変数 説明
API_KEY プロジェクトタイプに対応する個人用APIキー (Axe アカウントページで確認)
PROJECT_ID あなたのユニークなプロジェクトID
GIT_SHA Axe Developer Hubの結果を取得したいGitのコミットSHA

JavaScript (Node.js)

この例では、指定されたSHA (GIT_SHA環境変数内) と指定されたプロジェクトIDのAxe Developer Hubの結果を要求します。新しいアクセシビリティエラーが見つかった場合、その数がコンソールに記録されます。そうでなければ、「axe clean!」がコンソールに記録されます。

note

この例では、ない無効なAPIキーやGit情報の不足などのエラーをテストしません。

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

この例では、curlおよびjqを使用して標準出力に違反の数を返します。

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

Webサービスがサーバーエラーを返した場合、curl --failはコード22で終了し、レスポンスボディを抑制します。--fail-with-bodyオプションを使用してレスポンスJSONを標準出力の一部としても返すことができます。