Axe Developer HubをCI/CDプラットフォームに統合する
Axe Developer HubのRESTウェブサービスを様々なGitプラットフォームで利用する
必要条件:
- ウェブプロジェクトがGitデータを使用していること
- Axe Developer Hub プロジェクトID
- プロジェクトタイプに対応するDeque APIキー
概要
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に置き換える必要があります。
クエリパラメータ: 『
ヘッダー: 2つのヘッダーが必要です:
Accept: application/jsonX-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!」がコンソールに記録されます。
この例では、ない無効な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を標準出力の一部としても返すことができます。
