Axe Developer HubをCI/CDプラットフォームに統合する
Axe Developer HubのRESTウェブサービスを様々なGitプラットフォームで利用する
必要条件:
- あなたの Web プロジェクトは Git データを使用しています
- Axe Developer Hub プロジェクト ID
- Deque API キーはあなたのプロジェクトタイプに対応しています
概要
Axe Developer Hub は、GitLab や BitBucket などのサービスと CI/CD を統合するための基盤として使用できる REST Web サービスを提供しています。GitHub を使用している場合は、Axe Developer Hub GitHub Actionの使用をご覧ください。
REST サービスは、入力として Axe Developer Hub API キー、プロジェクト ID、および Git コミット SHA を期待しています。レスポンスオブジェクトには以下の内容が含まれます:
- 最後のテスト実行中に見つかったアクセシビリティエラーの数
- a11y 閾値を超えたアクセシビリティエラーの数
- Axe Developer Hub で詳細な結果を指し示す URL
テスト実行情報の取得
Web サービスは GET リクエストに応答し、指定された Developer Hub プロジェクトの特定の Git コミット SHA に関する情報を取得できます。
GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/<:SHA>?project_id=<your-project-id>要件
リクエストには、1つのパスパラメータ、1つのクエリパラメータ、および2つのヘッダーが必要です。
- サーバー:
https://axe.deque.com - エンドポイント:
/api-pub/v1/axe-watcher/gh/<*:SHA*> - クエリパラメータ:
?project_id=<your-project-id> - リクエストメソッド: GET
パスパラメータ: :SHA パラメータは、調べたい Git コミット SHA に置き換える必要があります。
クエリパラメータ: プロジェクトを作成した後に、指示ページに表示されるユニークなプロジェクト ID に「
ヘッダー: 2つのヘッダーが必要です:
Accept: application/jsonX-API-Key:<your-personal-api-key>
API キーは秘密として扱い、環境変数やあなたの CI/CD プラットフォームの秘密ストアに保存し、リクエストにハードコーディングしないでください。
リクエストの例:
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 エンドポイント
Axe Developer Hub は、セッションデータや結果をプログラム的に取得するための追加 REST エンドポイントを提供しています。セッションエンドポイント(プロジェクトのフィルタリングおよびカーソルページネーション付きのセッション一覧)と、結果エンドポイント(特定のセッションのサマリーまたは完全なユニバーサル JSON 結果を取得)について「セッションと結果の API リファレンス」を参照してください。
使用例
以下の例は、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!」がコンソールにログされます。
この例では、無効な 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'ウェブサービスがサーバーエラーを返した場合、curl --failはコード 22 で終了し、レスポンスボディを抑制します。レスポンス JSON も標準出力の一部として返すには、--fail-with-bodyオプションを使用してください。
