Axe DevTools Linter Connectorの使用
Axe DevTools Linter Connectorのコマンドラインオプション、環境変数、セットアップ情報、設定ファイル情報
Axe DevTools Linter Connector（別名 コネクター）は、Linux、macOS、およびWindows用のコマンドラインツールです。このツールは、ファイルの構文チェックを行うコマンドラインインターフェースを提供し、アクセシビリティチェックを自動化できます。例えば、スクリプトやCI/CD（継続的インテグレーションと継続的デリバリー）で使用できます。コネクターは、Dequeがホストするインスタンス（SaaS）または組織がホストするインスタンス（オンプレミス または オンプレミス）にファイルを送信する必要があります。または、 --local オプションを使用して ローカルLinting を参照してください）、ファイルの内容をサーバーに送信することなく、ローカルでファイルをリントすることもできます。
コネクターの使用例
Axe DevTools Connectorは以下の用途に使用できます：
- Jenkinsのビルドの一環としてアクセシビリティをチェックする。詳細は、 JenkinsでのAxe DevTools Linterの使用を参照してください。
- ファイルをスキャンして、アクセシビリティの欠陥に関する情報をSonarQubeにフィードバックする。設定方法については、 SonarQubeでのAxe DevTools Linterの使用 を参照してください。
- GitHubの事前コミットスクリプトで使用して、アクセシビリティエラーを含むコミットをブロックする。詳細は、 Gitの事前コミットフックでのAxe DevTools Linterの使用を参照してください。
- 以下のサービスにおけるアクセシビリティ欠陥の検出基盤を提供する：
- Bitbucket
- CircleCI
- GitLab
- Azure DevOps Services
ローカルLinting
コネクターは、 ローカルLinting を使用して --local コマンドラインオプションでファイルをサーバーに送信しないようにします。
ローカルLintingは、APIキー（ --api-key オプション）を使用する場合、以下の目的でリモートサーバーに連絡します：
- 認証のため
- 利用情報を取得するため
デフォルト以外のサーバーを使用してAPIキーを認証するには、 AXE_SERVICE_URL 環境変数 を指定して利用できます。
ライセンスキー（ --license-key オプション）を使用すれば、ネットワーク活動が避けられます。
-
ローカルLintingの利点
- サーバーを使用するよりもはるかに高速です。
- ネットワークの問題やサーバーの負荷の問題を抱える可能性が低く、大量のファイルをリントする場合に特に効率的です。
-
ローカルLintingの欠点
- より多くのローカルマシンリソースを必要とします。
- Axe DevTools Linter Connectorの更新には、Agoraから新しいバージョンをダウンロードしてインストールする必要があります。
- 使用追跡なし（ライセンスキーを使用する場合、APIキーの代わりに）。
使用するマシンに少なくとも2GBのメモリがある場合、Dequeは **強く推奨します** この --local オプションを使用することを。この方法により、大量のファイルをLintする際にLintの速度が大幅に向上します。
ライセンスキーとAPIキーの比較
ローカルLintにはAPIキーまたはライセンスキーのいずれかが必要です。Axeアカウントの一部として APIキーを管理できます （したがってフレキシビリティを提供します）。ただし、ライセンスキーは Dequeのヘルプデスクからリクエストする必要があります。ライセンスキーを使用したローカルLintはユーザーの使用状況（Lintされたコード行数）を追跡しませんが、ライセンスキーはリモート認証を必要としません。
インストールオプション
Axe DevTools Linter Connectorをインストールする方法は2つあります：
- Agora npmレジストリを設定し、NodeJSとnpmが提供するインフラを使用して、Connectorをインストール、実行、更新します。詳しくは Axe DevTools Linter Connectorをnpmパッケージとしてインストール を参照してください。
- もう一つの方法は、コンピュータのアーキテクチャに適したConnectorのバイナリを手動でダウンロードし、実行ビットを設定する（LinuxとmacOS）および拡張隔離属性を削除する（macOS）ことによって使用できるように準備します。詳しくは ダウンロードページを参照してください。
環境変数
Connectorは次の環境変数を認識します：
AXE_LINTER_SERVER_URL と AXE_LINTER_SERVER_PORT
AXE_LINTER_SERVER_URL はAxe DevTools LinterサーバーインスタンスのURLを設定します。（サーバーのURLは -u や --url コマンドラインオプションでも設定できます。） AXE_LINTER_SERVER_PORT は、サーバーがリッスンするポートを指定します。通常はポート3000です。
環境変数が設定されていない場合、Connectorはデフォルトで http://localhost をポート3000で使用します（http://localhost:3000）。
ポートをデフォルト値の3000から変更する必要はほとんどありません。DequeがホストするAxe DevTools LinterのSaaSバージョンを使用している場合は、 *設定しないでください* ポートを。
詳しくは Axe DevTools Linterを設定する についての詳細情報を参照し、 URLクイックリファレンス を参照して、Axe DevTools LinterのSaaSバージョンで使用するURLを確認してください。（SaaSバージョンのAxe DevTools Linterを使用する際にはポートを指定する必要はありません。）
以下の例は、LinuxまたはmacOSでローカルマシン上でAxe DevTools Linterを実行するための環境変数の設定を示しています（これらの環境変数はデフォルト値なのでここでの設定は必要ありませんが）：
export AXE_LINTER_SERVER_URL=http://localhost
export AXE_LINTER_SERVER_PORT=3000または、LinuxとmacOSでは、環境変数を次のように同じコマンドラインで設定することもできます。この使用法は以下の例で示されています。（ただし、これらはサーバーとポートのデフォルト値なので設定する必要はありません。） axe-linter-connector
AXE_LINTER_SERVER_PORT=3000 AXE_LINTER_SERVER_URL=http://localhost axe-linter-connector -s . -d .AXE_SERVICE_URL
環境変数は、APIキーの検証を行うための代替サーバーを指定することができます。この環境変数は、APIキーの検証にプライベートサーバーインスタンスを使用する組織に役立ちます。デフォルト値は AXE_SERVICE_URL https://axe.deque.com
APIキー検証のための代替サーバーを使用する詳細については、 Dequeのヘルプデスクへお問い合わせください。
この環境変数は、 --local オプション（ローカルLint）。
DEBUG
この DEBUG 環境変数を設定することで、リンティングの失敗を診断するための詳細なデバッグ情報をログに記録することができます。この DEBUG 環境変数を axe-devtools-linter:* に設定してデバッグログを有効にします。例は以下の通りです：
DEBUG=axe-devtools-linter:* axe-linter-connector -s . -d .コマンドラインオプション
必須のコマンドラインオプション
Axe DevTools Linter コネクタには、以下の2つのオプションが必要です：
-s、 --source ディレクトリまたはファイル
アクセシビリティエラーを検出するためのファイルまたはディレクトリを示します。サブディレクトリも検索されます。リンティングから除外したいファイルについては、 exclude オプションを 設定ファイル セクションを参照してください。
-d、 --destination ディレクトリ
コネクタがアクセシビリティレポートを書き込むディレクトリです。
-u、 --url URL
使用するサーバーを指定します。デフォルトは http://localhostです。SaaSサーバーを使用する場合は --url https://axe-linter.deque.com/
オプションのコマンドラインオプション
接続するサーバーや使用したいその他の機能やレポート形式に応じて、いくつかのオプションが必要です。
--additional-properties プロパティ
カスタムマッピングされたコンポーネントで発見された違反について、アクセシビリティレポートに追加プロパティを追加します。 カスタムマッピングされたコンポーネント。現在サポートされている唯一の値は customNameです。指定された場合、カスタムマッピングされたコンポーネントを含む各問題は、違反を引き起こしたカスタムコンポーネントのタグ名を値とする customName プロパティがレポートに追加されます。カスタムマッピングの一部ではないコンポーネントからの問題には customName プロパティは含まれません。
axe-linter-connector -s . -d . --additional-properties customName例として、 <MyButton> がカスタムマッピングされたコンポーネントであり、 button-name 違反を引き起こした場合、レポートの問題は次のようになります：
{
"engineId": "axe-linter-jsx",
"ruleId": "button-name (https://dequeuniversity.com/rules/axe/4.11/button-name?application=axe-linter)",
"customName": "MyButton",
"severity": "MAJOR",
"type": "BUG",
"primaryLocation": {
"filePath": "/path/to/app.jsx",
"message": "Buttons must have discernible text",
"textRange": {
"startLine": 7,
"endLine": 7,
"startColumn": 12,
"endColumn": 20
}
}
}--api-key APIキー
SaaS Axe DevTools Linter インスタンスでのリンティングを認可するため、またはローカルリンティングを使用するためのAPIキーを指定します。詳細については Axe DevTools Linter SaaS APIキーの取得 を参照してください。
--config ファイル名
設定情報を含むYAMLファイルの名前を指定します。このオプションをファイル名なしで使用することもでき、その場合Axe DevTools Connectorは 複数の設定ファイル に従って設定ファイルを探します。設定ファイルの詳細については、 設定ファイルを参照してください。
--filename ファイル名
SonarQubeレポートの名前を指定します。デフォルト： axe-linter-report.json
--issue-type タイプ
SonarQubeの問題のタイプを示すために使用されます。デフォルト： BUG、許可されている値： VULNERABILITY、 CODE_SMELLまたは BUG
--license-key キー
認証に使用するライセンスキーを指定します。ライセンスキーを取得する方法については、 Deque ヘルプデスク にお問い合わせください。このオプションには --local オプションも必要です。
--local
ローカルリンティングをオンにし、Axe DevTools Connector が実行されているマシンを使用してファイルをリンティングするため、ファイルをサーバーに送信する必要はありません。APIキー (--api-key) またはライセンスキー (--license-key) が必要です。詳細は ローカルリンティングをご覧ください。
次の --api-key オプション (推奨オプション) を使用する場合は、 --local、以下のようにサーバーを指定する必要があります：
axe-linter-connector -s . -d . --api-key 1234 --local --url https://axe-linter.deque.com/-R、 --reporter レポーター
使用するレポーターを指定します。デフォルトは： sonarqube
--retry-backoff-limit バックオフ制限
コネクタがエラー時にサーバー接続を再試行する前に待機する最大時間（ミリ秒単位）を指定します。デフォルトは30,000ミリ秒（30秒）です。 maximum time in milliseconds that the Connector will wait before retrying the server connection upon error. The default is 30,000 milliseconds (30 seconds).
--retry-count 再試行
接続エラーが発生した後にサーバー接続を再試行する回数を指定します。コネクタは再試行間の時間を（初期値500ミリ秒または0.5秒から始め）倍増させ、 バックオフ制限 ( --retry-backoff-limitで指定されます) に達するまでに再試行します。この制限に達すると、指定された回数の再試行を達成するまで（失敗するまで）またはエラーなしでサーバーに接続できるまでその状態を維持します。
--severity レベル
SonarQubeの重大度レベルを設定します。デフォルトは： MAJOR、許可される値は： BLOCKER、 CRITICAL、 MAJOR、 MINOR、または INFO。
設定ファイル
YAML設定ファイルを次の --config オプションと共に使用できます。
以下に設定ファイルの例を示します：
rules:
image-alt: false
exclude:
- meta-refresh.html
tags:
- wcag2a上記の例では、ルール image-alt が無視され、ファイル meta-refresh.html はリンティングされません。 wcag2a タグ内のルールが tags セクションで指定されているように使用されます。（詳細は タグ をご覧ください。）
exclude の値は glob 値 (*) および globstar (**) を許可しているため、次のことが可能です：
exclude:
- tmp/**/*.html上記の例では、 tmp ディレクトリおよびそのサブディレクトリ。
許可されている設定オプションの詳細については、 Axe DevTools Linter の設定をご覧ください。
使用例
Connector を Axe DevTools Linter SaaS サーバーで使用するには、以下に示すように --api-key オプションを使用してください:
axe-linter-connector -s . -d . --api-key 83cc5831-a35b-4a2d-9c2b-84fd2eec0a4d --url https://axe-linter.deque.com/Axe DevTools Connector を実行しているコンピュータで全てのリンティングをローカルで行うには、 --local オプションを使用します:
axe-linter-connector -s . -d . --api-key b5a34bba-7b0f-4ccb-9eb2-195ac6c56aee --local --url https://axe-linter.deque.com/ローカルのリンティングではサーバーにファイル内容を送信しませんが、使用状況の追跡と認証のためにサーバーと連携する必要があるため、 --url オプションをサーバーで指定する必要があります。