よくある質問
Axe Developer Hub の使用に関するよくある質問への回答
コンセプト
Git プロジェクトと Gitless プロジェクトの違いは何ですか？
Developer Hub は、テストが Git を使用しているかどうかに応じて結果を異なる方法で整理します。
- Git プロジェクト はアクセシビリティの結果をブランチやコミットと関連付け、特定のコード変更まで問題を追跡できるようにします。
- Gitless プロジェクト は結果をタイムスタンプ順に並べられたテスト実行のシリーズとして整理し、Gitデータは一切含みません。
- Git データは Axe Watcher、Axe CLI またはウェブ API 用の Axe DevTools （CLI 経由で結果をアップロード）を使用する場合に利用可能です。モバイルプロジェクトは常に Gitless です。
プロジェクトは、最初に成功したセッションが確立したもののいずれかに固定され、Git プロジェクトの場合はそのセッションのリポジトリに固定されます。それ以降の実行が一致しない場合、プロジェクトのデータの形状を切り替える代わりに拒否されます。
詳細については、結果を理解するおよびGit、Gitless、プロジェクトロックの用語集のエントリを参照してください。
2つのリポジトリから1つのプロジェクトへ結果を送ることができますか？
いいえ。Git プロジェクトは、最初の成功したセッションで単一のリポジトリに固定されます。それぞれのリポジトリの結果を自分のプロジェクトに送信してください。
なぜ私の実行が拒否されたのですか？
Developer Hub は、プロジェクトがロックされたものに一致しない実行を拒否します。プロジェクトが既に固定されたものとは異なるリポジトリ、Gitがない状態でGit情報を持たないプロジェクト、またはGitが固定されたプロジェクトにGit情報がない場合です。拒否メッセージは、プロジェクトが予想したもの、実行が送信したもの、およびそれについてどうするかを示します。実行が拒否されました: データの形状またはリポジトリがプロジェクトに一致しませんを参照してください。
なぜ私のGitプロジェクトが突然Gitレスの実行を報告するのですか？
そうではありません。プロジェクトが一度Gitにロックされると、Git情報がない実行は取り込み時に拒否され、Gitレスセッションとして保存されることはありません。以前にGitプロジェクトで時折Gitレスに見えるセッションがあった場合、その動作はもはや発生しません。代わりに拒否された実行をチェックしてください。浅いクローン、分離されたHEAD状態、またはCIでoriginリモートが欠けていると、Git実行からGit情報が削除され、この拒否が引き起こされる可能性があります。
A11y 閾値とは何で、それをどのように設定しますか？
A11y 閾値は組織のアクセシビリティ問題に対する許容度を反映し、CI/CD パイプラインで何が失敗と見なされるかを決定します。
- これは、すべての問題をカウントするか新しい問題のみをカウントするか、含める影響レベル（「重大度」は常に含まれます）の2つの基準から計算されます。
- プロジェクト管理者のみが閾値を設定できます。
詳細はA11y 閾値を変更するを参照してください。
影響レベル（重大度、深刻、 中程度、軽微）は何を意味しますか？
すべてのアクセシビリティ違反には、最も深刻なものから最も軽いものまでの4つの影響レベルのいずれかが割り当てられます。
- 重大度: 障害を持つユーザーが機能にアクセスしたり操作したりすることが完全にブロックされています。
- 深刻: 障害を持つユーザーがサイトを操作する際に大きな障壁に直面します。
- 中程度: 障壁はあるものの、基本的なコンテンツにはまだアクセス可能です。
- 軽微: それでも解決が必要な軽微な問題。
詳細な定義については用語集をご覧ください。
なぜ同じ問題が新たに報告され続けるのか？
問題が新しいかどうかを判断するために、Developer Hubは各結果をルール、要素セレクタ、およびURLごとに前回の実行と比較します。詳細は重複の用語集をご覧ください。同じ要素に関する同じ問題が毎回新たに報告される場合、実行間でそれらのいずれかが変わっていることを示しています。これには2つの一般的な原因があります。
実行間でURLが変わる。 URLは完全に比較されるため、セッションID、タイムスタンプ、キャッシュバスティングパラメータ、またはクエリ文字列内の動的な値があると、各実行が異なるページに見え、それまで見たことのないURL上のすべての問題が新たに報告されます。比較前にURLを正規化する設定はないため、テストが訪れるURLを決定的にするのが修正方法です。つまり、テスト設定で不安定なパラメータを削除または固定して、同じページが毎回同じURLを生成するようにします。
要素のIDやクラスが実行間で変わる。 #component-a1b2c3d4 や .form-field-xyz789 のような識別子を各レンダーで生成するフレームワークは、要素のセレクタを変更するため、以前に記録された要素に一致しなくなります。ancestry 実行オプションを true に設定するとこれが修正されます。なぜなら、祖先セレクタはDOMツリー内の位置で要素を説明し、IDやクラスを含まないからです：
axe: {
runOptions: {
ancestry: true
}
}動的セレクタの使用 を参照して、Javaの設定や ancestry を有効にすることのトレードオフを含む完全な説明をご覧ください。
比較
Developer Hubでの「新しい問題」や「解決された問題」のカウントは、現在のスキャンとベースラインスキャンとの比較から得られます。どのスキャンがベースラインとしてカウントされるかは、お使いの場所によって異なります：
- クロスブランチ比較 はブランチビューに表示されます。これらは、デフォルトブランチの最新のパイプライン実行とあなたのブランチの最新のスキャンを比較します。パイプライン実行とは、開発者のマシンからのローカル実行とは対照的に、CI/CDパイプラインによってトリガーされるスキャンです。Developer Hubはこれらを個別にフラグ付けするため、デフォルトブランチのどのスキャンが権威あるものか常に把握しています。これにより、「今すぐマージしたら何が変わるのか？」という疑問に答えます。
- ブランチ内比較 はコミットビューに表示されます。これらは、同じブランチで結果を持つ前回のコミットのスキャンと、特定のコミットのスキャンを比較します。これは決してGit履歴の文字通りの前回のコミットではありません：スキャンのないコミットは飛ばされます。これにより、「この特定のコミットが何を導入したり修正したりしたのか？」という疑問に答えます。
GitHubアクション は3番目の比較タイプではありません。プルリクエストに投稿されるカウントは現在のコミット内のブランチ内比較であり、デフォルトブランチとの比較ではありません。これは、PRチェックがマージされるブランチとの比較をしばしば期待されるため、混乱の一般的な原因です。
全体像を見るには結果を理解するをご覧ください。
リリースごとの変化点をどのように把握すればよいですか？
Git プロジェクトのブランチビューでは、クロスブランチ比較を使用してリリース間のアクセシビリティの変化を追跡できます。
- 各ブランチの最新スキャンされたコミットは、デフォルトブランチの最新パイプライン実行と比較されます。
- 比較では、問題の総数、新たに導入された問題、解決された問題、およびスキャンされたページの状態数の変化が表示されます。
ブランチ内の個別コミットでの変更を確認するには、ブランチ内でコミット間で何が変更されたかを確認するにはどうすればよいですか？をご覧ください。
プルリクエストの影響をどのように判断できますか？
プルリクエストブランチでテストスイートを実行し、結果をAxe Developer Hubに表示させてください。
- ブランチビューでは、各非デフォルトブランチがデフォルトブランチとのクロスブランチ比較を表示し、新たに導入された問題、解決された問題、総差分が示されます。
- GitHubアクションを使用すると、PRに要約と完全な結果へのリンクを自動でコメントとして追加できます。
ブランチの各コミットがどのように変更されたかを詳しく見るには、ブランチ内でコミット間で何が変更されたかを確認するにはどうすればよいですか？をご覧ください。
ブランチ内でコミット間で何が変更されたかを確認するにはどうすればよいですか？
ブランチビューから、任意のブランチのコミットを見るをクリックしてその個別スキャン済みコミットを表示します。ブランチビューのクロスブランチ比較とは異なり、コミットビューではブランチ内の比較を使用します：
- 各コミットは、そのブランチの前回スキャンされたコミットと比較され、新しい問題、解決された問題、ページ状態の変化が示されます。
- テストスイートが実行されたコミットのみが表示されます。
ブランチ全体がデフォルトブランチとどのように比較されるかを見るには、最新のCI/CD実行でデフォルトブランチとブランチを比較するにはどうすればよいですか？をご覧ください。
最新のCI/CD実行でデフォルトブランチとブランチを比較するにはどうすればよいですか？
ブランチビューは、各非デフォルトブランチに対してデフォルトブランチの最新パイプライン実行と自動的にクロスブランチ比較を行います。
- これには、プロジェクト管理者がデフォルトブランチでAxe Watcherをパイプラインとして実行するように設定する必要があります。
- 比較には、総問題数、新しい問題、解決された問題、およびページ状態の差が示されます。
そのブランチ内の個別コミットで何が変更されたかを見るには、ブランチ内でコミット間で何が変更されたかを確認するにはどうすればよいですか？をご覧ください。
プルリクエストを作成する前に正確な比較結果を得るにはどうすればよいですか？
マージ前に正確なクロスブランチ比較を行うために、機能ブランチをデフォルトブランチと同期させ続けてください。
- テストスイートを実行する前に、デフォルトブランチをフィーチャーブランチ（例：
git merge main）にマージします。 - マージコミットをプッシュして、Axe Developer Hubで更新されたブランチをスキャンできるようにしてください。
- その後、ブランチビューではデフォルトブランチの最新パイプライン実行とあなたのブランチを比較し、実際にあなたのブランチが導入したアクセシビリティ変更のみを示します。
あなたの機能ブランチがデフォルトブランチより遅れている場合、デフォルトブランチで既に修正された問題が機能ブランチにまだマージされていないときには、その比較で問題が表面化することがあります。デフォルトブランチを先にマージすることで、これらの誤検知を排除し、プルリクエストをマージしたときの驚きを減少させます。
なぜ異なるテストセットが実行されたときに、新しいまたは解決されたと報告される問題を見るのか？
比較が意味を持つのは、両側で同じテストセットが実行された場合のみです：
- 実行がベースライン実行で訪問していなかったページを訪問した場合、そのページ上のすべての問題が新たに報告されます。何も比較できるものがないからです。
- 実行がベースラインがカバーしていたページをスキップした場合、それらのページの問題は、誰も何も修正していないのに解決済みとして表示されます。それは単にテストされなかったためです。
- 本質的に異なるテストスイートをカバーする2つの実行は、そもそも比較されるべきではありません。結果は何も有用な情報を伝えないでしょう。
これは設定で修正できるものではありません。比較を意味のあるものに保つためにテストスイートを設定する方法については正確な比較のためのベストプラクティスをご覧ください。
正確な比較のためのベストプラクティス
- 1つのテストセットごとに1つのプロジェクトを使用する。 プロジェクトは1つのテストスイートに対応する必要があります。複数のスイートを1つのプロジェクトに向けると、各実行が異なるテストセットによって生成されたベースラインと比較され、新規および解決済みのカウントが何も意味しなくなります。
- 毎回同じテストセットを実行する。 スイートがカバーする内容を変更すると、比較がどのように表示されるかが変わります。スイートが正当に拡充された場合、その追加されたカバレッジで新しい問題が一度だけ急増することを期待してください。
- デフォルトブランチにパイプライン実行を設定する。 クロスブランチ比較は、デフォルトブランチの最新のパイプライン実行とブランチを比較します。これがなければ、ベースラインがまったく存在しないため、すべての問題が新しいとして報告され、これはこの症状の最も混乱させるバージョンです。これを設定することはプロジェクト管理者のタスクです。パイプライン情報をご覧ください。
CI/CD
コードに新たなアクセシビリティの問題がマージされないようにするにはどうすればよいですか？
Axe Developer HubをCI/CDパイプラインに統合して、各コミットやプルリクエストで自動的にアクセシビリティチェックを実行させます：
- GitHubを使用している場合、Axe Developer Hub GitHubアクションでアクセシビリティエラーを引き起こすPRをブロックできます。
- GitLabやBitbucketなどの他のプラットフォーム向けには、コミットステータスAPIを使用して結果をクエリし、問題が検出された場合にパイプラインを失敗させます。
- a11yしきい値を設定することで、不具合と見なす内容を微調整できます。
GitHubを使用していない場合、Axe Developer HubをCI/CDパイプラインに統合するにはどうすればよいですか？
コミットステータスAPIを使って、任意のCI/CDプラットフォームと統合できます。
- コミットステータスAPIを使うことで、テストスイートの実行後にAxe Developer Hubから結果をクエリできます。
- APIは、問題数、新しい違反、解決された違反、およびDeveloper Hubでの完全な結果へのリンクを返します。
- このレスポンスを利用して、GitLab、Bitbucket、Jenkins、その他のプラットフォームでパイプラインを合格または失格にすることができます。
プロジェクト管理
プロジェクトで他のメンバーのアクセシビリティスキャンを確認するにはどうすればよいですか？
プロジェクトのメンバー全員が追加されると、共有プロジェクト内のすべての結果を表示できます：
- メンバー設定ページからメンバーを追加します。
- Gitプロジェクトでは、ブランチビューがAPIキーごとにグループ化された結果を表示するため、誰が各スキャンを実行したかが分かります。
役割と権限の詳細についてはマルチユーザープロジェクトのセットアップを参照してください。
アクセシビリティの結果をどのようにエクスポートするのですか？
デベロッパーハブはデータをエクスポートするいくつかの方法を提供しています：
- 問題の概要ビューから、問題をエクスポートボタンをクリックして結果をCSVまたはJSONでダウンロードします。
- プログラムによるアクセスには、セッションと結果APIを使用してセッションの完全な結果を取得するか、コミットステータスAPIを使用してコミットの問題数を取得します。
すべてのAPIの概要については、Axe Developer Hub APIをご覧ください。