Axe開発者ハブGitHubアクションの使用

必要条件:

• Axe Watcherの統合を含むウェブプロジェクト
• Axe Developer HubプロジェクトID
• Axe Developer Hub APIキー
• Axe Developer Hubのセットアップ指示に従って修正したテストスイート
• 誰かがリポジトリにコミットするたびにテストスイートを実行するGitHubワークフロー

概要

Axe Developer Hub GitHub Actionを利用すると、アクセシビリティエラーを含むコミットやプルリクエストをブロックするためのGitHubワークフローをAxe Watcherを統合したウェブプロジェクトに設定できます。

修正されたテストスイートが実行されると、アクセシビリティの結果がGitコミットSHAと関連付き、その情報がDequeのサーバーに送信されます。GitHubアクションは後にテストスイートが実行された際に実行され、現在のブランチの最新のコミットSHAに関連付けられたアクセシビリティ結果をDequeのサーバーに問い合わせます。

アクションが報告する新しいおよび解決された問題の件数は、デフォルトブランチではなく、同じブランチに対してスキャンを行った前回のコミットのベースラインを使用します。テストスイートが実際に実行されたコミットのみがスキャンされるため、そのベースラインコミットは数コミット前のものかもしれません。そのコミットが異なるセットのテストを実行した場合、件数は実際の変化ではなくカバレッジの違いを反映します。正確な比較のためのベストプラクティスを参照してください。

セットアップ

1. プロジェクトIDの環境変数を作成 - プロジェクトIDを環境変数か他のGitHub変数として保存することをお勧めします。この例では、プロジェクトIDをPROJECT_IDという環境変数として保存します。

2. APIキーのシークレットを作成 - この例では、シークレットはAXE_DEV_HUB_API_KEYと名付けられており、個人のAPIキーがその値です。しかし、シークレット名は何でも良いです。ワークフロージョブで同じ名前で参照される必要があります。APIキーは資格情報なので、常にGitHub Actionsのシークレットとして保存し、ワークフローファイルにハードコードしないでください。

3. テストスイートにアクセシビリティチェックを追加 - プロジェクトセットアップでの手順を完了し、(Axe Watcher) CI/CDパイプラインで使用されるテストスイートにアクセシビリティチェックを統合してください。

4. 現在のワークフローを修正 - .github/workflowsにある現在のテストランナーワークフローを修正し、テストスイートを実行するジョブに後にGitHubアクションを追加する必要があります。

例のジョブ

テストスイートアクションに続くジョブはAxe Developer Hub GitHubアクションを実行すべきです。次の例を参照してください。

jobs:

# ...
# your-CI-test
# ...

# Add the following new job:
# Be sure to replace <choose_latest_tag> with the appropriate version tag
  axe-dev-hub:
    runs-on: ubuntu-latest
    needs: your-CI-test
    steps:
      - uses: actions/checkout@v5
      - uses: dequelabs/axe-devhub-action@<choose_latest_tag>
        with:
          api_key: ${{ secrets.axe_DEV_HUB_API_KEY }}
          project_id: ${{ env.PROJECT_ID }}

例のaxe-dev-hubジョブは、needs: your-CI-test行で指定されたあなたのテストスイートを実行するジョブに依存しています。この行を更新して、あなたのテストスイートを実行するジョブの名前に一致させてください。

GitHubアクションには複数の入力パラメーターを使用できます。例えば、a11yしきい値をenable_a11y_threshold: trueを使用して有効にできます。入力パラメーターの完全なリストはAxe Developer Hub GitHubアクションREADMEにあります。

結果

GitHubアクションは、検出されたアクセシビリティ問題の件数、解決された問題の件数、およびa11yしきい値を超えた問題の件数を含む複数の出力パラメーターを設定します。

a11yしきい値を有効にしていない場合、アクセシビリティエラーがゼロを超えるとGitHubアクションは失敗します。有効になっている場合、a11yしきい値を超えた違反のみがGitHubアクションの失敗を引き起こします。a11yしきい値の使用について詳しく知る で組織が優先したいものに合わせてAxe Developer Hubをカスタマイズできます。

GitHubアクションが失敗すると、以下に似たコメントがあなたのプルリクエストに添付され、マージをブロックする可能性があります。

プルリクエストコメントのリンクをクリックして、そのコミットのアクセシビリティ欠陥情報をAxe Developer Hubで確認してください。

トラブルシューティング

次のようなエラーを受け取るかもしれません:

Error: Resource not accessible by integration

アクションにコメントをプルリクエストに追加するために、設定ページで必要な権限を確認してください。アクションがコメントを追加できるようにするには、読み取りおよび書き込み権限が必要です。より細かく制御したい場合は、GitHubアクション用に別のGITHUB_TOKENを使用することを選択できます。この値をgithub_token入力パラメーターに追加してください。

例のワークフロー

すでにテストスイートを実行するワークフローがない場合は、例のワークフローを使用して、独自のテストランナーを作成するための出発点にすることができます。

この例のワークフローは テスト (tests.yml) と呼び、コミットやプルリクエストで実行されます。変更されたテストスイートを実行するジョブ cypress は、Cypress テストスイートの実行方法を示します。例の次のジョブ axe-dev-hub は、Axe Developer Hub GitHub アクションの呼び出しです。

あなたのテストスイートのジョブは、常に Axe Developer Hub GitHub アクションの前に実行を行うべきです。

参考文献

• Axe Developer Hub GitHub Actionのメインリポジトリ
  • READMEには、入力および出力パラメーターに関する情報が含まれています。
  • GitHub アクションのメタデータは、action.ymlで見つけることができます。
  • 最新のジョブ設定については、GitHub アクションレポのexample invocationを定期的に確認してください。
• このページのトピックに関する詳細情報は、GitHub のドキュメントで見つけることができます。
  • 情報を変数に格納する
  • 環境のための設定変数を作成する
  • GITHUB_TOKEN の権限を変更する