axe-watcher-results を用いて Axe Watcher の結果を取得する

axe-watcher-results は Axe Developer Hub から完了した Axe Watcher スキャンの結果を取得し、それを CI パイプラインの合否信号に変換します。

前提条件

axe-watcher-results を実行する前に、以下が必要です:

• Axe Developer Hub API キー（UUID）。
• スキャンが送信された Axe Developer Hub プロジェクトのプロジェクト ID（UUID）。
• 確認したいコミットに対する完了した Axe Watcher スキャン。

インストール

axe-watcher-results は Linux、macOS、Windows 用の自己完結型バイナリとして配布されています。あなたのプラットフォームに適したバイナリをダウンロードページからダウンロードし（アクセスには axe DevTools for Web の資格が必要です）、その後ダウンロード後のバイナリの準備に従って実行可能にし、macOS では隔離属性をクリアしてください。

バイナリをPATHに置く（またはパスで参照する）ことで、axe-watcher-resultsとして実行できるようにします。

認証

axe-watcher-results は Axe Developer Hub API キーを環境変数AXE_DEVHUB_API_KEYから読み込みます。最初の操作の前に一度設定してください。ローカル使用の場合はシェルに、パイプライン用には CI システムのシークレットストアに設定します。

export AXE_DEVHUB_API_KEY=<your-api-key>

以下の例は、この変数が設定されていることを前提としています。

コミットの結果を検索する (CI ゲート)

プロジェクト ID と Git コミット SHA を使ってaxe-watcher-results sessions getを実行します:

axe-watcher-results sessions get <project-id> <commit-sha>

• <project-id>: プロジェクトの UUID。
• <commit-sha>: 完了した Axe Watcher スキャンがすでにある 7-40 文字の Git コミット SHA。

これはビルドをゲートする検索です: 実行の問題の数がプロジェクトの a11y しきい値を超えた場合、axe-watcher-resultsはコード10で終了します（終了コードを参照）。例えば、--format=jsonの場合:

{
  "project": "your-project-name",
  "project-id": "7347af86-ff4e-4e14-8957-8fc2255ed4ec",
  "commit-sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
  "run-url": "https://axe.deque.com/axe-watcher/projects/7347af86-ff4e-4e14-8957-8fc2255ed4ec/branches/main/compare/0d4a85a2-9e6f-44ef-b814-fee8412abeb0/0d4a85a2-9e6f-44ef-b814-fee8412abeb0?settings_hash=0757ca72c5e10951ddbb2ede4edab06e&issues_over_a11y_threshold=2",
  "issues": 17,
  "new-issues": 17,
  "resolved-issues": 0,
  "issues-over-a11y-threshold": 2,
  "page-states": 2,
  "difference-in-page-states": 0,
  "created-at": "2026-07-07T18:13:00.641Z",
  "message": "Run exceeded the a11y threshold by 2."
}

スクリプトで出力を解析する場合は、--format=jsonを使用してください: 上記のフィールド名は安定しています。デフォルトの--format=text出力はビルドログを読む人間向けであり、解析には適していません。

セッションの結果を検索する

コミット SHA の代わりにセッション ID で特定のスキャンを検索することもできます:

axe-watcher-results sessions get <project-id> <session-id>

<session-id> はセッションの UUID です。axe-watcher-results はセッション ID をコミット SHA と形（UUID 対 7-40 文字の16進文字列）で区別するため、同じ位置に渡します。セッション検索はプロジェクトをセッションと API キーから解決するため、<project-id> 引数もなお必要であり、検証もされます。

--detail=summary（デフォルト）を使用して重大度とルールごとの問題数を取得したり、--detail=fullを使用して結果ドキュメント全体を生の JSON で取得することができます（この場合--formatは無視されます）。

--format=json --detail=summary はこのように見えます:

{
  "report_id": "14c16b50-a6ce-46ab-9974-0ad3b94eafde",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "4.0.0"
  },
  "test_details": {
    "test_id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
    "start_date": "2026-07-07T18:13:00.641Z",
    "end_date": "2026-07-07T18:13:05.472Z"
  },
  "commit": {
    "sha": "e220798b6558cdfc7c3e592378be67e1e78e7377",
    "author": "Jane Doe",
    "author_email": "jane@example.com",
    "message": "fix: correct login form labels",
    "branch_name": "main",
    "tag": "",
    "repository_url": "https://github.com/your-org/your-repo"
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.11/color-contrast?application=axeAPI",
        "count": 2
      }
    ]
  }
}

スキャンがまだ処理中の場合、axe-watcher-resultsはサーバーをポーリングし（最大5分）、進行状況をstderrに書き込みます。スキャンが時間内に処理を完了しない場合、コード11で終了します。

プロジェクトのセッション一覧

sessions listサブコマンドは、プロジェクトの記録されたスキャンセッションをリスト表示し、調べるセッションIDを見つけるのに役立ちます:

axe-watcher-results sessions list <project-id>

結果を--git-branch、--commit-sha、--git-url、--created-after/--created-before（ISO-8601タイムスタンプ）、--created-by-user-email、--is-canonical-sourceでフィルタリングします。--page-size（1-100）と--afterを使用して結果をページングします。sessions listは、--format、--network-timeout-seconds、--verbose/-vも受け入れ、sessions getと同じように動作します。

オプション

これらのオプションは、sessions getコマンド（コミットSHAとセッションIDのルックアップ）に適用されます:

--version（ルートaxe-watcher-resultsコマンドで）でaxe-watcher-resultsバージョンを表示して終了します。--helpはすべてのコマンドで利用可能です。

出力はクリーンテキストまたはJSONとしてstdoutに送られ、進行状況とエラーメッセージはstderrに送られます。そのため、ビルドログのために追加の解析をせずにstdoutをキャプチャできます。

CIゲーティングの例

スキャン完了後にaxe-watcher-resultsをステップとして実行し、コミットSHAを使用して終了コードがアクセシビリティの閾値を反映するようにします:

# AXE_DEVHUB_API_KEY is provided by your CI system's secret store
axe-watcher-results sessions get --format=json "$PROJECT_ID" "$GIT_COMMIT_SHA"

ゼロ以外の終了コードは呼び出しステップが失敗する。各コードの意味と対応方法については、終了コードを参照してください。

終了コード

12番目の終了からの復旧

12番目の終了は、そのコミットにスキャン結果があり、Axe Developer Hubに比較するものがないことを示しています。Axe Developer Hubは次の順でベースラインを選択します。

1. 同じコミットSHAでの以前のセッション。
2. 同じブランチの異なるSHAでの最新のセッション。
3. 現在のセッション自体。ただし、そのセッションが正準である場合のみ (継続的インテグレーション (CI) 環境でAxe Watcherを使用するを参照)。

これらのどれも利用できず、セッションが正準でない場合、Axe Developer Hubは404を返し、axe-watcher-resultsはコード12で終了します。復旧するには：

• CI=trueを設定してAxe Watcherスキャンを再実行し、セッションを正準にし、完全なスタートで自己比較させます。
• このコミットまたは同じブランチの以前のコミットに対して追加のスキャンを実行し、ベースラインを種まきします。