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

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]

は、JSON 結果を保存する場所です。 <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`	配列	任意です。プロジェクト内のすべてのページにおける状態変化に応答するアクション、例として、クッキーバナーやアンケートポップアップの閉じ方など。詳細はグローバルアクションを参照してください。
`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。

スリープ期間において、数値はミリ秒として解釈されます。文字列は 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

# 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"

バッチ処理 `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に結果を送信するを参照してください。

`-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、またはカンマ区切りの組み合わせ。デフォルト： html。

`--no-git-data`

Axe Developer Hub に結果を送信する際、Gitブランチとコミット情報を除外します。詳細は Axe Developer Hub に結果を送信をご覧ください。

`--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を上書きします。

`-t, --tags`

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

`--user-agent`

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

`--validate`

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

`-v, --verbose`

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

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

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

その 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>

-c, --custom <path>

--descendant-links

--dismiss-alerts

--enable-tracking <state>

--filter <type(s)>

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

--no-git-data

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

-t, --tags

--user-agent

--validate

-v, --verbose

Is this page helpful?

Help us improve this page

Still need help?