Ruby を使った高度な API の利用

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

カスタムルール、レポートオプション、利用サービスを含む Web Ruby 用の高度な Axe DevTools の利用

Not for use with personal data

このドキュメントでは、Ruby を用いたカスタムルール、レポートオプション、および利用サービスについて説明します。

カスタム要素とElementInternals

Axe DevTools Ruby 4.13.0以降では、スキャンによってマークアップに存在するroleやaria-*属性だけでなく、ElementInternalsを通じてJavaScriptで宣言されたウェブコンポーネントのARIAセマンティクスを読み取ります。設定は不要です。DOM内のセマンティクスが依然として優先されます。要素にroleまたはaria-*属性が明示的に指定されると、ElementInternalsからの値を上書きします。

これを有効にするには、コンポーネントがその内部を公開する必要があります。また、プライベートクラスフィールドに格納されているコンポーネントは読み取ることができません。ElementInternalsを使用するカスタム要素のテストをご覧ください。

カスタムルール

JSONファイルでカスタムaxe-coreルールを指定できます。

note

まだカスタムルールがなく、空のカスタムルールセットで始めたい場合は、空の JavaScript オブジェクトを含む axe-ruleset.json ファイルをローカルディレクトリに作成します。例: {}。

カスタムルールを環境変数で設定する

デフォルトの設定では、カスタムルールファイルの位置は現在の作業ディレクトリに対して相対的に config/axe-ruleset.json である必要があります。

この位置を AXE_RULESET_PATH 環境変数で上書きするか、Axe DevTools の設定を介して手動で変更できます。

axe-ruleset.json の位置を変更するために AXE_RULESET_PATH 環境変数を設定します:

AXE_RULESET_PATH=/path/to/your/axe-ruleset.json

Axe DevTools設定を通じたカスタムルールの設定

AXE_RULESET_PATH 環境変数を使用せずに、AxeDevTools.configure メソッドを使用してカスタムルールの場所を定義するための設定オブジェクトが利用可能です。

以下のすべての設定はオプションです。元のデフォルト値を使用するために、AxeDevTools.configure の呼び出し全体を省略することができます。

AxeDevTools.configure do |config|
  # path to json configuration providing custom rules and checks
  # set defaults to "config/axe-ruleset.json"
  config.axe_ruleset_path = "config/axe-ruleset.json"

  # Configure user pre-defined standard rule sets. Custom
  # rules override these rule sets. See https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
  config.rule_set_id = '508'
end

レポートオプション

Axe DevTools設定でレポートオプションを設定する

axe-devtools-* ジェムはテスト結果のログ記録を可能にします。AxeDevTools.Configure の呼び出しを使って、レポート用のグローバル設定をセットアップします:

AxeDevTools.configure do |config|
  config.output_directory: 'my-results',
  config.test_machine: 'my-server',
  config.test_suite_name: 'Accessibility Tests For Application',
  config.user_agent: 'Headless Chrome'
end

expect(page).to be_audited_for_accessibility.logging_results({
  ui_state: 'Landing Page Load',
})

レポート設定は次のプロパティを取ることができます:

属性 デフォルト値 説明
ui_state (必須) options オブジェクトに渡す属性です。
output_directory (オプション) axe-reports レポートを生成するディレクトリ名。
test_machine (オプション) テストが実行される場所を示す値。例: CircleCI, TesterMachine01
test_suite_name (オプション) axe-a11yCheck テストのスイート名。例: My Module Test Suite
user_agent (オプション) null 対象のユーザーエージェントを渡します。例: chrome。
verbose (オプション) false スタックトレースとメッセージの詳細ログを有効/無効にするフラグです。

また、AxeDevTools.configure 用の上記のすべてのオプションは、選択した WebDriver を構成する際に渡すことができます。例えば:

require 'axe-devtools-capybara'

AxeCapybara.configure do |config|
 config.axe_config_path = 'config/my-ruleset.json'
end

参照

使用状況サービス

利用サービスを利用して、組織内の Axe DevTools の利用傾向を把握することができます。

デフォルトでは、使用状況サービスは有効で、追跡URLはhttps://usage.deque.comです。

note

Ruby APIでは、使用状況トラッキングをオフにするには、以下に説明するenableTracking構成プロパティを使用し、AXE_TRACK_USAGE環境変数は使用しないでください。使用イベントがDequeに届かない場合は、setTrackingUrlで追跡URLを明示的に設定してください。

Axe DevTools設定による使用状況サービスオプションの設定

axe-devtools-* ジェムはグローバル設定を通じて利用サービスを設定することを可能にします:

AxeDevTools.configure do |config|
  config.setTrackingUrl: 'https://usage.deque.com',
end

利用サービスの特定の設定プロパティは次のとおりです:

属性 デフォルト値 説明
enableTracking true 利用追跡を有効にするオプションです。
setTrackingUrl https://usage.deque.com トラッキングURLを上書きするオプション。
チーム テストを実行するチームを、{ id: "...", name: "..." }ハッシュの配列として示します。チームを参照してください。

また、選択したWebDriverを設定する際には、上記のすべてのオプションをAxeDevTools.configureとして渡すことができます。例えば、Capybaraの場合:

require 'axe-devtools-capybara'

AxeCapybara.configure do |config|
 config.enableTracking = false
end

チーム

テストを実行するチームを使用状況イベントで記録できます。各チームは文字列idとnameの値を持つハッシュです。両方がないエントリは削除され、空の配列はチームを送信しません。

チームは3か所で設定できます。複数設定された場合、このリストで最初のものが使用されます。

  1. 単一のRSpecチェックの場合、for_teams句。

  2. 全体の実行に対しては、teams設定プロパティ:

    AxeDevTools.configure do |config|
      config.teams = [{ id: "1", name: "Web" }]
    end
  3. JSON{ "id": "...", "name": "..." }オブジェクトの配列、またはそれを含むJSONファイルのパスを設定したAXE_TEAMS環境変数。値が読み取れない場合、APIは警告を出しチームを送信せず、スキャンは続行されます。

Cucumber gemにはチェックごとのオプションがありませんので、teams設定プロパティまたはCucumberとAXE_TEAMSを使用してください。

使用状況イベントは、テストを誰が実行したか、または自動化されたパイプラインで実行されたかも記録します。よく使われるCI環境変数CI、GITHUB_ACTIONS、JENKINS_URLなどが設定されている場合、APIはautomationを報告し、それ以外の場合はhumanを報告します。これを上書きするには、AXE_ACTORをhumanまたはautomationに設定してください。

環境変数による使用状況サービスオプションの設定

さらに、利用サービスオプションは環境変数を通じて設定することもできます。

名前 タイプ 上書き可能 説明
AXE_DISTINCT_ID 文字列 — ログイン中のユーザーに対して同じままのUUID識別子(再生成されない限り)。Rubyでは、この変数はDEQUE_DISTINCT_IDと名付けられています。
AXE_INCLUDE_TEST_RESULTS ブール値 — 各イベントのtestResultsオブジェクトに完全なaxe-core結果を含めるには、trueに設定します(デフォルトはfalse)。CLIおよびNode.js APIのみでサポートされています。
AXE_METRICS_URL 文字列 — REST使用エンドポイントのURL(デフォルトはhttps://usage.deque.com)
AXE_TRACK_USAGE ブール値 — 使用サービスの報告を無効にするには、falseに設定します。報告はデフォルトで有効です。
AXE_ACTOR 文字列 — テストを実行するのが人か自動化されたパイプラインかを上書きするには、humanまたはautomationに設定します。デフォルトでは、一般的なCI環境変数からautomationが検出されます。CLI、Node.js API、およびRuby APIのみがサポートしています。
AXE_APPLICATION 文字列 false アクセシビリティエラーのチェックに使用されたアプリケーション
AXE_DEV_INSTANCE ブール値 true このイベントがソフトウェア開発者の行動によるものかを示します。開発またはテスト中に記録されたイベントをマークし、後で削除するのに便利です。
AXE_DEPARTMENT 文字列 true 組織内でのユーザーの部署
AXE_KEYCLOAK_ID 文字列 false ユーザーのKeycloak ID
AXE_LOGGED_IN ブール値 false テスト対象アプリケーションにユーザーがログインしているかどうかを記録します
AXE_ORGANIZATION 文字列 true ユーザーの組織。Axe Reportsに使用状況を表示するには、これを組織のIDに設定してください(取得するにはDequeに連絡してください)。
AXE_SESSION_ID 文字列 false ユーザーのセッションを識別するUUID
AXE_TEAMS 文字列 false テストを実行するチームを、{ "id": "...", "name": "..." }オブジェクトのJSON配列として、またはそれを含むJSONファイルへのパスとして指定します。CLIの--set-teamsオプション、Node.js APIのsetTeamsメソッド、Ruby APIのfor_teams句またはteams設定プロパティに渡された値が優先されます。CLI、Node.js API、およびRuby APIのみがサポートしています。
AXE_USER_ID 文字列 false 特定のユーザーのID。例えば、メールアドレス、名前、またはログインIDなどです。Axe Reportsはこの値を基にユニークユーザーをカウントします。
AXE_USER_JOB_ROLE 文字列 false ユーザーの役割
AXE_USER_STATUS 文字列 false ユーザーに紐づけたいステータス情報