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などのサービスと連携して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に置き換える必要があります。

クエリパラメータ: '' をプロジェクト作成後に表示される指示ページに記載の一意のプロジェクト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閾値を超える問題の数 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'

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