Axe DevTools Linter Connectorの使用
Axe DevTools Linter Connectorのコマンドラインオプション、環境変数、セットアップ情報、設定ファイル情報
Axe DevTools Linter Connector（別名：コネクター）は、Linux、macOS、Windows用のコマンドラインツールです。これは、ファイルをリントするためのコマンドラインインターフェースを提供し、アクセシビリティチェックを自動化できます。たとえば、スクリプトやCI/CD（継続的インテグレーションと継続的デリバリー）のために使用できます。このコネクタは、Deque（SaaS）がホストするか、あなたの組織（オンプレミスまたはオンプレミス）がホストするAxe Linterサーバーのインスタンスにファイルを送信する必要があります。または、ファイルの内容をサーバーに送信せずに--localオプションを利用してローカルでファイルをリントすることもできます（詳細は以下のローカルリンティングを参照）。
コネクターの使用例
Axe DevTools Connectorは以下の用途に使用できます：
- Jenkinsのビルドの一部としてアクセシビリティをチェックします。詳細については、JenkinsでのAxe DevTools Linterの使用を参照してください。
- ファイルをスキャンし、アクセシビリティの欠陥情報をSonarQubeに供給します。設定方法については、SonarQubeでのAxe DevTools Linterの使用を参照してください。
- アクセシビリティエラーを含むコミットをブロックするために、GitHubのプリコミットスクリプトで使用します。Gitの事前コミットフックでのAxe DevTools Linterの使用を参照してください。
- 以下のサービスにおけるアクセシビリティ欠陥の検出基盤を提供する：
- Bitbucket
- CircleCI
- GitLab
- Azure DevOps Services
ローカルリンティング
The Connector allows you to avoid sending your files to a server by using ローカルLint with the --local command-line option.
ローカルリントは、APIキー（--api-keyオプション）を使用する場合、および以下の目的でリモートサーバーに接続します:
- 認証のため
- 利用情報を取得するため
AXE_SERVICE_URL環境変数を使用して、APIキーを認証するためのデフォルト以外のサーバーを指定できます。
ライセンスキー（--license-keyオプション）を使用すると、すべてのネットワーク活動を回避できます。
-
ローカルLintingの利点
- サーバーを使用するよりもはるかに高速です。
- ネットワークの問題やサーバーの負荷の問題を抱える可能性が低く、大量のファイルをリントする場合に特に効率的です。
-
ローカルLintingの欠点
- より多くのローカルマシンリソースを必要とします。
- Axe DevTools Linter Connectorの更新には、Agoraから新しいバージョンをダウンロードしてインストールする必要があります。
- 使用追跡なし（ライセンスキーを使用する場合、APIキーの代わりに）。
使用するマシンが少なくとも2 GBのメモリを持っている場合、Deque **強く推奨します**を--localオプションを使用して行います。これにより、特に大量のファイルリント時に、リントが大幅に高速化されます。
ライセンスキーとAPIキーの比較
ローカルリントにはAPIキーまたはライセンスキーが必要です。APIキーを管理できますことができます（これにより柔軟性が提供されます）。ただし、Dequeのヘルプデスクからライセンスキーをリクエストしなければなりません。ライセンスキーを使用してのローカルリントはユーザーの使用状況（リントしたコードの行数）をトラッキングしませんが、ライセンスキーはリモート認証も不要です。
インストールオプション
Axe DevTools Linter Connectorをインストールする方法は2つあります：
- Agora npmレジストリをセットアップし、NodeJSおよびnpmが提供するインフラストラクチャを使用してコネクタをインストール、実行、更新します。詳細はAxe DevTools Linter Connectorをnpmパッケージとしてインストールを参照してください。
- 他のオプションとしては、コンピュータのアーキテクチャに適したコネクタバイナリを手動でダウンロードし、使用するために実行権限を設定する（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です。
環境変数が設定されていない場合、コネクタはデフォルトでポート3000（http://localhost:3000）のhttp://localhostサーバーURLを使用します。
ポートをデフォルトの3000から変更する必要はほとんどありません。DequeがホストするAxe DevTools LinterのSaaSバージョンを使用している場合、*設定しないでください*ポートを設定する必要はありません。
サーバーの設定についての詳細はAxe DevTools Linterを設定するを、Axe DevTools LinterのSaaSバージョンで利用するURLについてはURLクイックリファレンスを参照してください。なお、Axe DevTools LinterのSaaSバージョンを使用する場合、ポートを指定する必要はありません。
以下の例は、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
AXE_SERVICE_URL環境変数を使用すると、APIキーを検証するための代替サーバーを指定できます。デフォルト値はhttps://axe.deque.comです。
プライベートクラウド顧客には、顧客固有のURLで認証サーバーが専用に配置されています。ローカルリントで使用するためには、コネクタを実行する前にAXE_SERVICE_URLをプライベートクラウドのインスタンスURLに設定してください。
export AXE_SERVICE_URL=https://your-org-axedevtools.dequecloud.com
axe-linter-connector -s . -d . --api-key <your-api-key> --localプライベートクラウドインスタンスのURLは、プライベートクラウドインスタンスの設定時に提供されました。持っていない場合は、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 プロパティ
Adds extra properties to issues in the accessibility report for violations found on カスタムマッピングされたコンポーネント. The only currently supported value is customName. When specified, each issue involving a custom-mapped component gains a customName property in the report whose value is the tag name of the custom component that triggered the violation. Issues from components that are not part of a custom mapping will not have a customName property.
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キー
Axe DevTools LinterのSaaSインスタンスでのリントの承認またはローカルリントを使用するための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 バックオフ制限
Specifies the 最大 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です。
設定ファイル
--configオプションでYAML構成ファイルを使用できます。
以下に設定ファイルの例を示します：
rules:
image-alt: false
exclude:
- meta-refresh.html
tags:
- wcag2a上記の例では、ルールimage-altが無視され、ファイルmeta-refresh.htmlがリントされません。wcag2aタグ内のルールがtagsセクションで指定された通りに使用されます。詳細はタグを参照してください。
exclude値はグロブ値（*）およびグロブスター（**）を許可しているため、以下が許可されています:
exclude:
- tmp/**/*.html上記の例では、tmpディレクトリおよびそのサブディレクトリ内のすべてのHTMLファイルが除外されます。
許可される構成オプションについての詳細は、Axe DevTools Linter の設定を参照してください。
使用例
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オプションを指定する必要があります。