Axe Developer HubをCI/CDプラットフォームと統合する
Axe Developer HubのRESTウェブサービスを使用して、さまざまなGitプラットフォームと連携する
必要条件:
- ウェブプロジェクトはGitデータを使用する
- Axe Developer Hub プロジェクトID
- Deque APIキー プロジェクトタイプに対応する
概要
Axe Developer Hubは、GitLabやBitBucketなどのサービスと連携してCI/CD実装に統合するための基盤として使用できるRESTウェブサービスを提供します。GitHubを使用している場合は、次を参照してください Axe Developer Hub GitHub Actionの使用。
RESTサービスは入力として、Axe Developer HubのAPIキー、プロジェクトID、およびGitコミットSHAを必要とします。レスポンスオブジェクト内には、次の項目が含まれます:
- 最後のテスト実行中に検出されたアクセシビリティエラーの数
- a11yしきい値を超えているアクセシビリティエラーの数 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つのパスパラメータ、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閾値を超える問題の数 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'ウェブサービスがサーバーエラーを返した場合、 curl --fail コード22で終了し、レスポンスボディを抑制します。オプションを使用して、標準出力の一部としてレスポンスJSONも返します。 --fail-with-body オプションを使用して、標準出力の一部としてレスポンスJSONも返します。
