仕様ファイルを使用してページを分析する

仕様ファイルは、Webページのリストと、アクセスビリティの問題を分析する前に各ページで実行するブラウザアクションを定義するJSONまたはYAMLファイルです。axe specを使用して単一の仕様ファイルを実行するか、axe bulk-specを使用して仕様ファイルのディレクトリを処理します。

axe specコマンド

axe spec <spec-file> <output-dir> [options]

<output-dir>はJSON結果が保存される場所です。省略すると、結果は現在の作業ディレクトリに保存されます。

使用例：

axe spec ./axe-workflow.yaml ./axe-results --format html

仕様ファイルの構造

仕様ファイルは、分析するページのリストと各ページで実行するオプションのアクションを持つ 1 つまたは複数のプロジェクトを定義します。

YAML の例

projects:
  - name: deque.com
    id: deque.com
    metadata:
      products:
        - CLI
      environment:
        - Prod
    globalActions:
      - dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"
    pageList:
      - name: Deque search
        url: https://www.deque.com/
        actions:
          - type "axe" into element "#searchform input"
          - click element "#searchform button"
          - wait for element ".m-search-page" to be found
          - analyze
      - name: Axe Dashboard
        url: https://axe.deque.com/

プロジェクト

ページ

JSON/YAML フォーマット

Specファイルは、YAMLまたはJSONで記述できます。次の表は、各フォーマットで同じ値を示しています。JSONでは、ダブルクォートを含むアクション文字列は、バックスラッシュでエスケープする必要があることに注意してください。セレクタ内のCSSエスケープ（例：.md\:hidden内のエスケープされたコロン）は、記述されたとおりにブラウザに到達します。JSONでは、そのバックスラッシュを\\として書きます。"click element \".md\\:hidden\""のように。

アクション

アクションは仕様ファイル内のactions（またはglobalActions）配列内の文字列です。ボタンのクリック、フォームの入力、ダイアログの解除、ページ状態の待機、アクセスビリティ分析の実行などのタスクを実行します。アクションはリストされている順序で実行されます。

アクションには2種類あります：

• ページアクションは特定のページで順番に実行されます。analyzeアクションは各ページで少なくとも1回呼び出す必要があります。
• グローバルアクションはプロジェクト内のすべてのページで状態変化に応じて実行されます。グローバルアクションを参照してください。

完全なアクションの例

次の例では、Deque Universityにログインし、ダッシュボードを分析します：

projects:
  - name: Deque University login flow
    id: deque-university-login-flow
    pageList:
      - name: homepage
        url: https://dequeuniversity.com/
        actions:
          - click element ".loginLink"
          - wait for element ".loginUsername" to be found
          - type "user@example.com" into element ".loginUsername"
          - type "secretpassword" into element "#loginPassword"
          - click element "input[type=submit]"
          - wait for element ".logoutLink" to be found
          - analyze page

セレクター

多くのアクションは、ページ上の要素を識別するセレクタ引数を取ります。セレクタは、CSSセレクタまたはXPathセレクタであり、単一の文字列、文字列のリスト、またはネストされたリストを含むリストとして指定されます。

• 文字列はページ自体の要素にマッチします。例えば、"#el"です。
• 文字列のリストは、以下に説明されるようにiframeに入ります。
• ネストされたリストがリスト内にあると、シャドウDOMツリーに入ります。シャドウDOMセレクタの例を参照してください。

iframe内の要素をターゲットにするには、リストを使う必要があります。リスト内の最後のセレクター以外は、CSSセレクターでなければならず、連続した<iframe>要素を特定して移動します。リスト内の最後のセレクターは、ターゲット要素を特定し、CSSまたはXPathであることができます。リスト内の各セレクターは、前のエントリーにより確立されたドキュメントコンテキストに対して評価されます。最初のセレクターはルートドキュメントに対して相対的で、各後続のiframeセレクターは、前のiframe内のドキュメントに対して相対的です。

単一の文字列（リストではない）では、iframeの内部に移動できません。フレームの内容がどのように分析および報告されるかについては、iframeの分析を参照してください。

Iframeセレクターの例

次のHTML構造を考えてみましょう：

<body>
  <!-- root document -->
  <iframe class="payment-widget">
    <!-- document inside the payment-widget iframe -->
    <div class="form-wrapper">
      <iframe id="card-fields">
        <!-- document inside the card-fields iframe -->
        <form>
          <input type="text" name="card-number" class="card-input">
        </form>
      </iframe>
    </div>
  </iframe>
</body>

カード番号入力をクリックするには、セレクターリストを使用してください。各CSSセレクターは、前のエントリによって設定されたドキュメントコンテキスト内で評価されます：

# "iframe.payment-widget" is evaluated in the root document
# "#card-fields" is evaluated in the document inside iframe.payment-widget
# ".card-input" is evaluated in the document inside #card-fields
click element ["iframe.payment-widget", "#card-fields", ".card-input"]

最後のターゲット要素にXPathを使用するには（iframeセレクターは依然としてCSSでなければなりません）：

click element ["iframe.payment-widget", "#card-fields", "//input[@name='card-number']"]

JSONでの例：

"click element [\"iframe.payment-widget\", \"#card-fields\", \".card-input\"]"

シャドウDOMセレクタの例

シャドウDOMツリー内の要素をターゲットにするには、セレクタリスト内にネストされたリストを入れます。ネストされたリストの最初のエントリがシャドウホストを識別し、それ以降の各エントリは前のエントリのシャドウツリー内で評価されるため、一つのネストされたリストでいくつかのシャドウツリーを順に通過することができます。

# Click the button inside the shadow tree of #host
click element [["#host", "button"]]

# Click the button inside #inner-host, which is inside the shadow tree of #outer-host
click element [["#outer-host", "#inner-host", "button"]]

# Go into the iframe #frame, then into the shadow tree of #host inside it
click element ["#frame", ["#host", "button"]]

JSONでの例：

"click element [[\"#host\", \"button\"]]"

これらの制限を考慮してください。

• オープンなシャドウルートのみがアクセス可能です。クローズドシャドウルート内の要素にはターゲットを合わせることができません。
• ネストされたリスト内のすべてのセレクタはCSSセレクタでなければなりません。XPathはシャドウDOMツリーを越えることはできません。
• 単一のエントリを持つネストされたリストはホスト自体を選択するため、[["#host"]]は"#host"と同じ意味を持ちます。

セレクタを取るすべてのアクションはネストされたリストを受け入れます。analyzeを含む。

ページアクション

CLIは9つのページアクションをサポートしています：

1. analyze: アクセスビリティ分析を実行
2. change: <input>、<textarea>、または<select>の値をJavaScriptで変更
3. click: 要素をクリック
4. dismiss: ポップアップまたはモーダルを非表示
5. eval: 任意のJavaScriptを評価
6. press: キーを押す（修飾キーの有無にかかわらず）
7. select: <select>のオプションを選択
8. type: <input>に文字を入力
9. wait: 特定の状態を待つ、またはスリープ

analyze

analyzeアクションはアクセスビリティ分析を実行します。各ページで少なくとも1回呼び出す必要があります。ワークフローの異なるポイントでページを分析するために、複数回呼び出すことができます（結果を区別するためにwith titleバリアントを使用してください）。

オプションのrulesetパラメーターは使用するルールセットを指定します。デフォルトはWCAG 2.1 AAです。利用可能なルールセット：

要素を含めたり除外したりする情報については、コンテキストパラメータに関するaxe-core APIドキュメントを参照してください。

# Analyze using the WCAG 2.1 AA ruleset (default) — all three forms are equivalent
analyze
analyze the page
analyze page

# Analyze using the Section 508 ruleset
analyze page with ruleset "508"

# Analyze with a custom title (useful when analyzing a page multiple times)
analyze the page with title "after login"

# Analyze only a specific element
analyze only element "#main-content"

# Analyze only specific elements
analyze only element "#idOfElement" and element ".classToAnalyze"

# Analyze everything except images that are immediate children of paragraphs
analyze the page excluding element "p > img"

# Analyze everything except elements inside a frame with a specific class
analyze the page excluding element [".classOfFrameToExclude", "#idOfElement"]

# Analyze only an element inside the shadow tree of #host
analyze only element [["#host", ".widget"]]

# Save results to a specific directory
analyze the page and save in "./homepage-team/"

# Save a copy to an additional directory while also saving to the default location
analyze the page and save a copy in "./homepage-team/"

# Use the axe-core library's built-in default ruleset
analyze the page with the source default ruleset

複数のオプションを組み合わせた例： 要素のクラスthird-party内の画像と送信時に検証されないフォームのみを分析し、クラスold-apiの要素を除外し、508ルールセットを使用し、カスタムタイトルとカスタム保存場所を設定。

analyze only element [".third-party", "img"] and element "form[novalidate]" excluding element ".old-api" with ruleset "508" with title "What is this testing" and save in "Results for Some test"

JSONでの例：

"analyze only element [\".third-party\", \"img\"] and element \"form[novalidate]\" excluding element \".old-api\" with ruleset \"508\" with title \"What is this testing\" and save in \"Results for Some test\""

change

changeアクションは、JavaScriptを使用して<input>、<textarea>、または<select>要素の値を変更します。通常のDOMイベントが利用できない場合にchangeを使用します。

# Change the value of an input
change the value of "input[name=song]" to "too many puppies"

click

clickアクションは、指定されたセレクタと一致する最初の要素をクリックします。

# Click a button by class selector
click element ".myButton"

# Click the body element
click "body"

dismiss

dismissアクションは、モーダルの閉じるボタンをクリックしてポップアップまたはモーダルを閉じます。モーダルコンテナのCSSセレクタと閉じるボタンのセレクタを提供してください。どちらかの要素が存在しない場合、アクションは正常に失敗します。

クローズボタンが単一の文字列として指定された場合、モーダル内で最初に検索され、その後ページの残り部分で検索されます。そのため、モーダルがシャドウDOMツリー内にある場合、クローズボタンセレクタにシャドウホストを繰り返す必要はありません。リストとして指定されたクローズボタンは、ページの最上部から検索されるため、ボタンまでの完全なパスを含める必要があります。

# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .close"

# Dismiss a modal inside the shadow tree of #host
dismiss modal [["#host", ".modal"]] with close button ".close"

eval

evalアクションはページ上で任意のJavaScriptを実行します。DOMを操作したりカスタムアクションを実行したりするのに使用します。

# Change the page title
eval "document.title = 'hello world'"

# Scroll an element into view
eval "document.querySelector('.someElement').scrollIntoView()"

# Scroll to the bottom of the page
eval "window.scrollTo(0, document.body.scrollHeight)"

press

pressアクションは、要素に対してキー押下を送信します（オプションで修飾キー付き）。サポートされているキー名についてはSeleniumキーのドキュメントを参照してください。

# Press H on the body element
press "H" on "body"

# Press Shift+Tab on the navigation element
press "shift+tab" on element ".navigation"

# Press Shift+Control+7 on an element
press "shift+control+7" on element ".foo"

select

selectアクションは<select>要素の<option>を属性ではなく（value属性ではない）によって選択します。

アクションは、

<select class="mySelect">
  <option></option>
  <option value="1">dog</option>
  <option value="2">cat</option>
  <option value="3">fish</option>
</select>

# Select by visible option text
select the "dog" option in ".mySelect"
select the "cat" option in element ".mySelect"

type

typeアクションは<input>または<textarea>要素に文字列を入力します。フォームを入力したり検索フィールドを埋めたりするのに使用します。

# Type into an email input
type "user@example.com" into element "input[type=email]"

# Type into a textarea
type "hello world" into "textarea.Message"

# Type with a delay between keystrokes to simulate human typing
type "sloth" into "input[type=search]" with a 150ms key delay

wait

waitアクションは、要素が指定された状態に達するのを待つか、指定された期間スリープします。

サポートされている要素状態：visible、hidden、selected、enabled、disabled、found。

要素の状態を待つために、このアクションはデフォルトで3回回まで再試行します（合計4回の試行）前に失敗します。読み込みが遅い要素を待つ時間を延ばすには、with <n> retriesを追加して試行回数を増やします。

スリープ時間については、数値はミリ秒として解釈されます。文字列はmsパッケージを使用して変換されます。例：1m = 60,000 ms、1s = 1,000 ms。

# Wait for an element to appear
wait for element ".myElement" to be found

# Wait for an element to become hidden
wait for element ".myElement" to be hidden

# Allow more retries for a slow-loading element
wait for element ".myElement" to be found with 9 retries

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

グローバルアクション

グローバルアクションは、ページアクションのように順序立てて実行されるのではなく、プロジェクト内の全ページで状態変化に応じて実行されます。現在サポートされているグローバルアクションは1つのみです：dismiss modal。

• グローバルアクションはspecモードおよびヘッドレスURIモードの両方で動作します。
• グローバルアクションは手続き型ではありません：それらは固定された順序ではなく、ページイベントに応答してトリガーされます。
• dismiss modalグローバルアクションは、指定されたモーダルが表示されるのを待ち、ページアクションが続行される前にそれを解除します。
• モーダルセレクタがシャドウDOMセレクタである場合、グローバルアクションは、ページロード時に既にページ上にあるか、そのシャドウホストが後でページに追加されたときにのみモーダルを解除します。ページに既に存在するシャドウツリー内に追加されたモーダルは検出されません。その場合は、ページレベルのdismissアクションを使用してください。

グローバルアクションをプロジェクトに追加するには、name/idの後、pageListの前に追加します：

projects:
  - id: demo
    name: CLI demo
    globalActions:
      - dismiss modal "#__next .survey" with close button ".survey button.close"
    pageList:
      - name: homepage
        url: https://dequelabs.github.io/aget-demo-site
      - name: popup
        url: https://dequelabs.github.io/aget-demo-site
        actions:
          - wait for element "#__next header nav" to be visible
          - click element "#__next header nav a[href*=popup]"
          - wait for element ".content button" to be found
          - analyze with title "before popup"
          - click element ".content button"
          - analyze with title "with popup"
          - dismiss modal ".ReactModal__Content" with close button ".ReactModal__Content .close"
          - analyze with title "after popup"
      - name: contact
        url: https://dequelabs.github.io/aget-demo-site/contact
        actions:
          - analyze with title "form disabled"
          - wait for element "#__next .toggle" to be found
          - click element ".toggle button"
          - wait for element "input[name=name]" to be enabled
          - analyze with title "form enabled"
          - type "stephen" into element "input[name=name]"
          - type "555-555-5555" into element "input[name=phone]"
          - type "stephen@deque.com" into element "input[name=email]"
          - type "hello world" into element "textarea[name=message]"
          - click element "button[type=submit]"
          - wait for element ".thanks" to be found
          - analyze with title "thanks message"

スクリーンショットのキャプチャ

分析後に各ページのスクリーンショットをキャプチャするには、screenshotオブジェクトを仕様ファイルのプロジェクトに追加します。各ページは<page-id>-screenshot.pngと名付けられた1つのPNGファイルを生成します（ページid内の/または\は_に置き換えられます）。ページにidがない場合、そのnameからすべての空白を削除して派生します。

axe specを--verboseとともに実行すると、各結果にはそのページのスクリーンショットファイルへのフルパスを含むscreenshotPathフィールドも含まれます。

projects:
  - name: My App
    id: my-app
    screenshot:
      enabled: true
      fullPage: true
      boundingBoxes: true
      dir: ./screenshots
    pageList:
      - name: Home
        url: https://example.com/

axe bulk-specによるバッチ処理

単一の実行で複数の仕様ファイルを処理するには、仕様ファイルを含むディレクトリをaxe bulk-specで使用します。CLIはディレクトリとそのサブディレクトリ内の仕様ファイルを再帰的に検索します。

axe bulk-spec <spec-files-directory> <output-directory>

<output-directory>はオプションです — 省略すると、結果は現在の作業ディレクトリに保存されます。

進行状況の更新は実行中にstdoutに表示されます。

結果は出力ディレクトリに書き込まれます：analyzeアクションごとに1つのJSONファイルに加え、失敗した仕様ファイルと失敗の理由を記載したログファイルが含まれます。

オプション

axe specに利用可能なオプションは次のとおりです：

--axe-devhub-api-key <api-key>

Axe Developer Hub APIキーを指定します。Axe Developer Hubに結果を送信するには、--axe-devhub-project-idと共に必要です。Axe Developer Hub に結果を送信を参照してください。

--axe-devhub-project-id <project-id>

Axe Developer HubプロジェクトIDを指定します。Axe Developer Hubに結果を送信するには、--axe-devhub-api-keyと共に必要です。Axe Developer Hub に結果を送信を参照してください。

--axe-devhub-server-url <url>

Axe Developer HubサーバーのURLを指定します。デフォルトはhttps://axe.deque.comです。AXE_DEVHUB_SERVER_URL環境変数と同等です。Axe Developer Hub に結果を送信を参照してください。

-a, --axe-source <path>

代替のaxe.jsファイルへのパス。ほとんどのユーザーはこのオプションを必要としません。特定のまたは修正されたバージョンのaxe-coreに対してテストするなどの高度なユースケースに意図されています。

--chrome-options [options]

カンマ区切りのコマンドラインスイッチのリストをChromeまたはEdgeに渡します。これを使用して、ブラウザの機能を有効にするか、特定の環境での制限を回避します。例えば、サンドボックスを無効にする必要があるコンテナ化されたCI環境で。

axe spec workflow.yml --chrome-options="no-sandbox,disable-gpu"

-c, --custom <path>

カスタムルールセットファイルを指定し、デフォルトのルールセットを上書きします。

--descendant-links

各ページのリンクを収集し、結果に追加します。--verboseを必要とします。

--dismiss-alerts

スキャン前にブラウザのalert()、confirm()、prompt()ダイアログを自動的に閉じます。

--enable-tracking <state>

メトリクスライブラリへのデータ送信を有効にします。

--filter <type(s)>

出力から結果タイプをフィルタリングします：passes、violations、incomplete、inapplicable。--format csvを必要とします。

-f, --format <type(s)>

レポート形式：html、junit、csv、universal、またはカンマ区切りの組み合わせ。デフォルト：html。--universal-rulesetと--universal-best-practicesを参照して、universalを使用するときに適用されるオプションを確認してください。

--no-analyze

各ページのアクションリストにanalyzeアクションを必要としなくなります。デフォルトでは、スペックファイル内のすべてのページに少なくとも1つのanalyzeアクションが含まれている必要があります。このフラグは、そのチェックを無効にします。アクションのみを実行し、アクセシビリティスキャンを行わないワークフローを実行する際に役立ちます。

--no-exit

違反が見つかってもコード0でCLIを終了させます。デフォルトでは、axe specは違反が検出された場合、コード1で終了します。CIビルドを失敗させずに結果を収集したい場合にこれを使用します。

--no-git-data

Axe Developer Hubに結果を送信する際にGitのブランチおよびコミット情報を除外します。Axe Developer Hub に結果を送信を参照してください。

--no-html

CLIがHTMLレポートを生成しないようにします。これを--formatと一緒に使用して、書き込まれるレポート形式を制御するか、HTMLサマリーなしでJSON結果のみを望むときに使用します。

--no-reports

CLIがレポートファイルを一切生成しないようにします。結果はまだ収集され、ターミナルに表示されますが、ディスクには書き込まれません。出力ファイルが必要ない簡易チェックに便利です。

--no-wait

ワークフローアクション間の自動ポーズを無効にします。デフォルトでは、アクション間に--post-get-pause、--post-script-pause、--post-analyze-pauseで設定されているポーズが適用されます（設定を参照）。このフラグはそれらすべてをスキップします。

--page-name <name>

スペックファイルのpageListから特定の名前のページのみを実行します。

--page-source

スキャンしたHTMLソースを結果に追加します。--verboseを必要とします。

--page-title

ページタイトルを結果に追加します。--verboseを必要とします。

--remote-proxy <proxy-server>

指定されたリモートプロキシサーバーを介してトラフィックをルーティングします。このオプションはChromeとEdgeのみに適用されます。

--resume-from <name>

スペックファイルのpageListで指定された名前のページの前のすべてのページをスキップします。

--scanned-url

ベースURLと現在のスキャンURLを詳細な結果に追加します。Chromeのみ。--verboseを必要とします。

--set-distinct-id <id>

別のID値を上書きします。

--set-legacy-mode

非推奨の従来のスキャンモードを有効にします。これはバージョン5.0で削除される予定です。

--set-tracking-url <url>

メトリクスデータ送信先のURLを上書きします。

--silent-mode

CLI出力からすべての装飾テキストを抑制します。--verboseがアクティブな場合にのみ結果が表示されます。クリーンな出力が必要なスクリプトやCIパイプラインで進捗バナーやステータスメッセージなしで使用してください。

-t, --tags

タグによる標準ルールセットのフィルタリングを行います。

--universal-best-practices

普遍的な形式出力のメタデータにbestPracticesEnabled=trueを記録します。--format universalを必要とします。

--universal-ruleset <id>

普遍的な形式出力のメタデータに記録するルールセットIDを指定します。デフォルトはwcag2.1です。--format universalを必要とします。有効な値についてはルールセットテーブルを参照してください。

--user-agent

ブラウザのカスタムユーザーエージェント文字列を設定します。このオプションはChromeとEdgeのみに適用されます。

--validate

Specファイルを実行せずに検証します。検証は、globalActionsの各エントリを含む各アクション文字列をチェックし、サポートされていないアクションで始まるアクション文字列を拒否します。

-v, --verbose

追加出力に含める：Axeの結果やツール名、バージョン、環境などのメタデータ。

--wait-network-idle-new-connections [number]

ネットワークがアイドルと見なされる前に確立される新しいネットワーク接続の数。このしきい値以下に新しい接続が減少すると、CLIはスキャンを続行します。バックグラウンドネットワーク活動が進行中のページでCLIが実行されるタイミングを調整するために--wait-network-idle-timeoutと一緒に使用します。--wait-network-idle-*のオプションはChromeとEdgeのみに適用されます。

--wait-network-idle-open-connections [number]

ネットワークがアイドル状態と見なされる前に残ることができるオープンネットワーク接続の数。このしきい値に達した時点か以下に落ちた時点で、CLIはスキャンを進行します。

--wait-network-idle-polling-every [ms]

ネットワークがアイドル状態になったかどうかをCLIがチェックする間隔（ミリ秒）。検出を早めるためにこの値を下げると、CPU使用率が高くなります。

--wait-network-idle-timeout [ms]

スキャンを開始する前にネットワーク活動が安定するのを待つ最大時間（ミリ秒）。ページ読み込み後、CLIはアクティブなネットワーク接続を監視し、接続数が設定されたしきい値に達するまで待機します。タイムアウトが経過してもネットワークがアイドル状態にならない場合、CLIはスキャンを続行します。

追加の設定オプションについては、設定を参照してください。