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

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

仕様ファイルは、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/

プロジェクト

プロパティ	タイプ	説明
`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内の要素をターゲットにするには, you must use a list. All selectors in the list except the last one identify successive <iframe> elements to navigate into, and must be CSS selectors. The last selector in the list identifies the target element and can be CSS or XPath. Each selector in the list is evaluated relative to the document context established by the previous entry: the first selector is relative to the root document, and each subsequent iframe selector is relative to the document inside the preceding 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アクションは、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セレクタと閉じるボタンのセレクタを提供してください。どちらかの要素が存在しない場合、アクションは正常に失敗します。

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

グローバルアクションをプロジェクトに追加するには、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からすべての空白を削除して派生します。

プロパティ	タイプ	デフォルト	説明
`enabled`	ブール値	—	必須。スクリーンショットを取得するには、`true`を設定します。すべてのサポートされているブラウザで動作します。
`fullPage`	ブール値	`false`	Chrome DevTools Protocolを使用して全体のスクロール可能なページをキャプチャします。ChromeまたはChromiumが必要です。他のブラウザでは警告を伴い、ビューポートのスクリーンショットに戻ります。
`boundingBoxes`	ブール値	`false`	Axe結果の各違反ノードに境界ボックスの座標（`x`、`y`、`width`、`height`）を追加し、要素がスクリーンショット上で表示される位置を記録します。
`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に表示されます。

結果は出力ディレクトリに書き込まれます：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コマンドラインスイッチのリストを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`

違反が見つかってもコード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>`

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

`--resume-from <name>`

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

`--scanned-url`

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

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

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

`--set-legacy-mode`

非推奨の従来のスキャンモードを有効にします。これはバージョン5.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はスキャンを継続します。バックグラウンドでネットワーク活動を続けるページでCLIを実行するタイミングを調整するために--wait-network-idle-timeoutと一緒に使用してください。

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