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

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

仕様ファイルを使用してページを分析するための spec および bulk-spec サブコマンドの使い方

Not for use with personal data

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

この `axe spec` コマンド

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

この <output-dir> 省略した場合、結果は現在の作業ディレクトリに保存されます。

使用例：

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/

プロジェクト

プロパティ	タイプ	説明
`name`	文字列	プロジェクトの一意の表示名。
`id`	文字列	プロジェクトの一意の識別子。
`metadata`	オブジェクト	任意です。ご使用の用途に応じた任意のメタデータ（例：製品名、環境など）。
`globalActions`	配列	任意です。プロジェクト内のすべてのページにおける状態変化に応答するアクション、例として、クッキーバナーやアンケートポップアップの閉じ方など。詳細はグローバルアクションをご覧ください。
`screenshot`	オブジェクト	オプションです。分析後に各ページのスクリーンショットをキャプチャします。詳細はスクリーンショットのキャプチャをご覧ください。
`pageList`	配列	分析するページのリスト。詳細はページをご覧ください。

ページ

プロパティ	タイプ	説明
`name`	文字列	ページの表示名。
`url`	文字列	ページの URL。
`actions`	配列	任意です。分析前後にページで行うアクション。詳細はアクションをご覧ください。

JSON/YAML フォーマット

仕様ファイルは YAML か JSON で記述できます。以下の表は、それぞれのフォーマットで同じ値を示しています。JSON では、ダブルクォートを含むアクション文字列にはバックスラッシュでエスケープする必要があります。

YAML	JSON
`type "axe" into element "#searchform input"`	`"type \"axe\" into element \"#searchform input\""`
`dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"`	`"dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\""`

アクション

アクションはその 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

セレクター

多くのアクションは、ページ上の要素を識別するセレクター引数を使用します。セレクターは、1つのCSSセレクターまたはXPathセレクターとして、単一の文字列または文字列のリストとして指定できます。

iframe内の要素をターゲットにするには、リストを使用する必要があります。リスト内の最後のセレクターを除くすべてのセレクターは、順次移動すべき <iframe> 要素を識別し、CSSセレクターでなければなりません。リスト内の最後のセレクターはターゲット要素を識別し、CSSまたはXPathのいずれかを使用できます。リスト内の各セレクターは、前のエントリによって設定されたドキュメントコンテキストに対して評価されます。最初のセレクターはルートドキュメントに対して、各後続の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\"]"

ページアクション

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

analyze：アクセシビリティ分析を実行する
change：値を変更する <input>、 <textarea>、または <select> JavaScript経由で
click：要素をクリックする
dismiss：ポップアップまたはモーダルを閉じる
eval：任意のJavaScriptを評価する
press：キーを押す（修飾子の有無にかかわらず）
select：オプションを選択する <select>
type：入力する <input>
wait：特定の状態を待機するか、休止する

`analyze`

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

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

ルールセットID	標準
`wcag2`	WCAG 2.0 AA
`wcag2.1`	WCAG 2.1 AA（デフォルト）
`wcag2.2`	WCAG 2.2 AA
`wcag2aaa`	WCAG 2.0 AAA
`wcag2.1aaa`	WCAG 2.1 AAA
`wcag2.2aaa`	WCAG 2.2 AAA
`508`	セクション508
`ttv5`	Trusted Tester v5
`en301549`	EN 301 549
`rgaav4`	RGAA v4

要素を含めるまたは除外する方法については、コンテキストパラメータに関する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" ]

# 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 の値を変更します。 <input>、 <textarea>、または <select> 要素をJavaScriptで操作します。通常の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セレクターを指定してください。どちらかが存在しない場合でも、アクションはエラーを出さずに終了します。

note

このアクションはネイティブの alert() アクションは、 confirm() ダイアログを閉じません。

# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .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 の <option> 要素をその <select> 表示テキストで選択します（ 属性ではなく ）。 value 与えられたHTML：

アクションは、

<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 グローバルアクションは、指定されたモーダルが表示されるのを待ち、それを終了させてからページアクションを続行します。

プロジェクトにグローバルアクションを追加するのは、 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 という名前のPNGファイルを1つ生成します（ページ内の / アクションは、 \ は id に置き換えられます）。ページに _がない場合、 idからすべての空白を削除して1つ生成されます。 name

プロパティ	タイプ	デフォルト	説明
`enabled`	ブール値	—	必須です。スクリーンショットキャプチャを有効にするには `true` に設定します。サポートされているすべてのブラウザで動作します。
`fullPage`	ブール値	`false`	Chrome DevTools Protocolを使用して全体のスクロール可能なページをキャプチャします。ChromeまたはChromiumが必要です。他のブラウザでは警告を伴い、ビューポートのスクリーンショットに戻ります。
`boundingBoxes`	ブール値	`false`	各違反ノードにバウンディングボックスの座標（`x`、 `y`、 `width`、および `height`）をAxeの結果の各違反ノードに記録し、スクリーンショット内で要素が表示されている場所を記録します。
`dir`	文字列	`<output-dir>/<project-id>/`	スクリーンショットPNGファイルが書き込まれるディレクトリ。

を実行すると、 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 に表示されます。

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

オプション

以下のオプションが利用可能です： axe spec：

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

Axe Developer HubのAPIキーを指定します。 --axe-devhub-project-idと共に結果をAxe Developer Hubに送信するために必要です。詳しくは Axe Developer Hub に結果を送信をご覧ください。

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

Axe Developer HubのプロジェクトIDを指定します。 --axe-devhub-api-keyと共に結果をAxe Developer Hubに送信するために必要です。詳しくは 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コマンドラインスイッチのリストをChromeDriverに渡します。これは、ブラウザの機能を有効にするか、特定の環境（たとえば、サンドボックスを無効にする必要があるコンテナ化された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`

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

`--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>`

specファイルの中から指定された名前のページのみを実行します pageListをご覧ください。

`--page-source`

スキャンしたHTMLソースを結果に追加します。必要条件： --verboseをご覧ください。

`--page-title`

ページタイトルを結果に追加します。必要条件： --verboseをご覧ください。

`--remote-proxy <proxy-server>`

指定されたリモートプロキシサーバーを介してトラフィックをルーティングします。

`--resume-from <name>`

specファイルの中で名前のついたページの前のすべてのページをスキップします pageListをご覧ください。

`--scanned-url`

ベースURLと現在のスキャンURLを冗長な結果に追加します。Chromeのみ。必要条件： --verboseをご覧ください。

`--set-distinct-id <id>`

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

`--set-legacy-mode`

非推奨となった従来のスキャンモードを有効にします。これはv5.0で削除されます。

important

これは最後の手段としてのオプションです。これにより、 window.open()の上書きという推奨されない方法を取っているページでスキャンが完了できることが報告されています。

`--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`

ブラウザ用のカスタムユーザーエージェント文字列を設定します。

`--validate`

specファイルを実行せずに検証します。

`-v, --verbose`

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

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

ネットワークがアイドル状態と見なされる前に確立される新しいネットワーク接続の数。このしきい値に達した時点か以下に落ちた時点で、CLIはスキャンを進行します。 --wait-network-idle-timeout と組み合わせて、CLIがバックグラウンドでネットワーク活動が続くページで動作するタイミングを調整します。

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

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

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

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

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

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

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

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

この axe spec コマンド

仕様ファイルの構造

YAML の例

プロジェクト

ページ

JSON/YAML フォーマット

アクション

完全なアクションの例

セレクター

Iframeセレクターの例

ページアクション

analyze

change

click

dismiss

eval

press

select

type

wait

グローバルアクション

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

バッチ処理 axe bulk-spec

オプション

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

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

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

-a, --axe-source <path>

--chrome-options [options]

-c, --custom <path>

--descendant-links

--dismiss-alerts

--enable-tracking <state>

--filter <type(s)>

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

--no-analyze

--no-exit

--no-git-data

--no-html

--no-reports

--no-wait

--page-name <name>

--page-source

--page-title

--remote-proxy <proxy-server>

--resume-from <name>

--scanned-url

--set-distinct-id <id>

--set-legacy-mode

--set-tracking-url <url>

--silent-mode

-t, --tags

--universal-best-practices

--universal-ruleset <id>

--user-agent

--validate

-v, --verbose

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

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

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

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

Is this page helpful?

Help us improve this page

Still need help?