WatcherのJavaScriptおよびTypeScriptバージョンのAPIリファレンス

このリファレンスガイドは、提供されるAPIを説明しています @axe-core/watcher パッケージ（別名 axe Watcher または単に Watcher）のJavaScriptおよびTypeScript用です。

AxeConfiguration インターフェース

axe プロパティ（ 構成関数に渡されるパラメータ）は、 AxeConfiguration axe Watcherを使用してアクセシビリティテストを構成する通常の手段です。次のプロパティが含まれています AxeConfiguration：

apiKey

（必須）この apiKey 値は、2つのプロパティの1つです（apiKey および projectId）が、次の設定で設定される必要があります AxeConfiguration。この値を取得するには、次の APIキー管理ページ を参照してください。

autoAnalyze

（オプション）この値を false に設定して、ページが自動的に分析されないようにします。手動モードについての詳細は、 ページ分析の制御を参照してください。

buildID

（オプション）この buildID プロパティは、 nullされていない場合、並行テストランナーでaxe Developer Hubに1つのテスト実行として表示される結果を生成できるようにします。並行テスト実行の場合、各テストランナーは同じ非ヌルの buildID 文字列を共有し、これにより各テスト実行は同じ buildID およびGitのコミットSHAの既存の結果にその結果を結合します。ただし、 buildID が nullの場合、複数のテスト実行は 上書き が、同じGitのコミットSHAを持つ既存の結果を上書きします。

一般に、継続的インテグレーションプロバイダーから使用可能な buildID 値を取得できます。たとえば、以下の値を使用できます：

• github.run_id

  GitHubワークフロー内で利用可能です。詳細は、 GitHubコンテキスト をGitHubのドキュメントで参照してください。

• CIRCLE_PIPELINE_ID

  CircleCIの場合、上記の値はプロセスの環境から入手できます。詳細は、 組み込み環境変数 をCircleCIのドキュメントで参照してください。

  他の継続的なインテグレーション環境変数には、 buildIDを使用できます：

  プロバイダー	環境変数
  Bitbucket	BITBUCKET_BUILD_NUMBER
  GitLab	CI_PIPELINE_ID
  Jenkins	BUILD_NUMBER

configurationOverrides

（オプション）全体設定で設定された値を上書き グローバル設定を参照してください。 ConfigurationOverridesインターフェース の詳細はこちらをご覧ください。

excludeUrlPatterns

（オプション）次のいずれかに一致するURLを防ぎます。 minimatch", "context": "link text パターンを ", "context": "paragraph excludeUrlPatterns 配列で分析されないようにします。", "context": "paragraph

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

例", "context": "heading level 4

git

（オプション） ", "context": "paragraph false を設定して、現在のテスト実行で Watcher が Git 情報を収集しないようにします。デフォルトは ", "context": "paragraph trueです。これは、Git リポジトリに属さないプロジェクトや Git データ収集によってエラーが発生するプロジェクトに役立ちます。", "context": "paragraph

projectId

（必須） Watcher のアクセシビリティ結果を受信するプロジェクト ID を指定します。新しいプロジェクトを作成すると、プロジェクト ID が手順とともに表示され、また ", "context": "paragraph axe Developer Hub Projects Page ", "context": "paragraph からも取得できます。", "context": "paragraph

runContext

（オプション） ページのアクセシビリティ分析に含める要素を選択および除外することができます。", "context": "paragraph

：", "context": "paragraph runContext 分析に含める要素の単一の CSS セレクタ：", "context": "paragraph

1. 分析に含める要素の CSS セレクタの配列：", "context": "paragraph

   axe: {
     runContext: '.main'
   }

2. が含まれるコンテキストオブジェクト", "context": "paragraph

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. と ", "context": "paragraph include プロパティ（上記の例に示されています）。以下を指定できます：", "context": "paragraph exclude または", "context": "paragraph include またはその両方。各 ", "context": "paragraph exclude or both. Each include または exclude は単一のCSSセレクターまたはCSSセレクターの配列である可能性があります：

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

詳細は axe-coreコンテキストのドキュメントで確認できます。

runOptions

（オプション） runOptions オブジェクトは、axe-coreの Options タイプからの以下のプロパティのサブセットを許可します：

• ancestry：デフォルトは falseです。もし trueなら、返されるCSSセレクターには、返される要素の祖先要素が含まれます。

  important

  ページが動的なIDやクラス（再読み込み時に変わる要素IDやクラス）を使用している場合、 ancestry を指定する必要があります true ことで、axe Developer Hubがアクセシビリティの問題が 重複しているか を正しく検出し追跡できるようにします。デフォルトでは、axe Developer Hubはテストの実行間で要素IDやクラスが同じであると仮定します。

  の場合、 ancestry こんなことが起こります： true、axe Developer Hubは代わりにDOMツリー内の要素の位置を使用して、テストの実行間で同じ要素を見つけます。

  以下は、 ancestry の場合のセレクターの例です： false は main-iframe というIDのiframe要素に対して、(<iframe id="main-iframe" ...>)：

  iframe#main-iframe

  が ancestry なら、 trueセレクターにはルート要素からの全経路が含まれ、IDやクラスは指定されません：

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly：これにより、名前やタグを指定することでどのルールが実行されるかを制限できます。詳細は以下の runOnly を参照してください。

• rules：ルールを使用するには、 enabled プロパティを使って有効化または無効化します。詳細は以下の rules を参照してください。

以下は runOptionsの例です：

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: [ 'wcag2a' ]
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

runOnly の値（ runOptions オブジェクトの一部）は以下のいずれかになります：

1. アクセシビリティ分析に使用したいルールのIDを表す文字列：

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. 使用したいルールのIDを表す文字列の配列：

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. 以下のプロパティを持つオブジェクト type と values のプロパティです。 type の値は、次のいずれかの文字列です。 rule、 rules、 tag、または tags。 values プロパティは、アクセシビリティ分析で使用したいルールやタグを表す文字列の配列でなければなりません。以下の例では、 runOnly オブジェクトを使用して、 wcag2aがタグ付けされたルールにアクセシビリティテストを限定する方法を示しています。

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: [ 'wcag2a' ]
       }
     }  
   }

• の使用例（axe-coreを使用）については、 runOnly オプションパラメータの例を参照してください。 オプションパラメータの例
• 利用可能なタグの値についての詳細は、 axe-coreのタグを参照してください。
• ルール、ルールID、タグについての情報は、 ルールの説明

rules

を参照してください。 rules の値（ runOptions オブジェクト内）は、分析中に特定のルールを有効に（enabled: true）または無効に（enabled: false）することを可能にします。以下に示すように：

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

（オプション）この sessionId プロパティは廃止されており、使用しないでください。上記を参照してください。 buildID 詳細は上記を参照してください。

testingTypes

（オプション） testingTypes は、Cypressでコンポーネントまたはe2e（エンドツーエンド）テスト（または両方）を指定するための文字列の配列です。

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

（オプション） timeout オブジェクト（タイプ Timeouts）は AxeConfiguration で、それぞれのコントローラーメソッド（またはCypress用のカスタムコマンド）のタイムアウト値をミリ秒単位で設定します。 コントローラクラス についての情報は Cypressのカスタムコメント を参照してください。）タイムアウトが発生した場合、テストはタイムアウトが超過したことを示すメッセージとともに失敗します。エラーを防ぐために、タイムアウトを延長することができます。

この例では、 analyze のタイムアウトを8秒に設定し、 flush を15秒に設定し、 start を10秒に設定し、 stop を10秒に設定しています。（デフォルト値は Timeouts インターフェースの表に示されています。）

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

構成関数

Watcherが提供する構成関数は、指定したテストフレームワーク用のセットアップを修正したり、要求に応じてWatcherの実行方法を調整したりすることができます。詳細は AxeConfigurationインターフェース を参照してください。

cypressConfig

Cypressの設定を作成します。

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig パラメーター

• config: Cypress.ConfigOptions & Configuration

  の交差型 Cypress.ConfigOptions と Configurationです。

戻り値: Cypress.ConfigOptions

playwrightConfig

Playwrightの設定を作成します。

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig パラメーター

• opts: Configuration & LaunchOptions

  の交差型 LaunchOptions と Configurationです。

戻り値: LaunchOptions

playwrightTest

Playwright Testの設定を作成します。

playwrightTest(options: Options): ReturnValue

playwrightTest パラメーター

• options: Options

  Options はの交差型 Configuration と LaunchOptionsです。

戻り値: ReturnValue

puppeteerConfig

Puppeteerの設定を作成します。

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig パラメーター

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  の交差型 LaunchOptions、 BrowserLaunchArgumentOptions、 BrowserConnectOptions、そして Configurationです。

戻り値: Options

wdioConfig

WebdriverIOの設定を作成します。

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig パラメーター

• arg: Options

  Options はの交差型 RemoteOptions と Configurationです。

戻り値: RemoteOptions

wdioTestRunner

WebdriverIOテストランナーの設定を作成します。

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner パラメーター

• params： unknown[]

  この params 値は次のいずれかです：

  1. 1つの値を含む配列で、これは Options.Testrunner と Configurationの交差型です。
  2. 最初の配列の値が AxeConfiguration で、2番目の値が Options.Testrunnerである配列。

戻り値： Options.Testrunner

webdriverConfig

Selenium WebDriverの設定を作成します。

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig パラメーター

• arg： WebDriverArgs

  Selenium WebDriver Configuration メンバーを含むように拡張された Options 。

戻り値： Options

Configuration インターフェース

この Configuration インターフェースは 設定関数 と共に使用され、1つのプロパティを含みます：

すべての 設定関数 は、この axe プロパティを使用してウォッチャーを設定し、アクセシビリティテストを構成します。次のセクション「 AxeConfigurationインターフェース」を参照してください。

ConfigurationOverrides インターフェース

この ConfigurationOverrides インターフェースにより、組織全体のグローバル設定を個別のテスト実行用に上書きできます。このプロパティは、企業のグローバル設定で指定された権限に従って使用する必要があります。

accessibilityStandard

テストするアクセシビリティ標準を設定します。利用可能なオプション：

• 「すべて」 - 利用可能なすべての標準に対してテスト
• 「WCAG 2.2 AAA」
• 「WCAG 2.2 AA」
• 「WCAG 2.2 A」
• 「WCAG 2.1 AAA」
• 「WCAG 2.1 AA」
• 「WCAG 2.1 A」
• 「WCAG 2.0 AAA」
• 「WCAG 2.0 AA」
• 「WCAG 2.0 A」
• 「Trusted Tester v5」
• 「EN 301 549」
• 「RGAAv4」 - RGAAバージョン4（フランスのアクセシビリティ標準；axe-core 4.11.0以降が必要）

組織はこの設定をグローバル設定で上書きすることを許可し、選択された標準が許可されたオプションの中にある必要があります。

axeCoreVersion

テストに使用するaxe-coreのバージョンを指定します。利用可能なオプションには以下が含まれます：

• 「最新」 - 現在axe Watcherにバンドルされている最新のサポートバージョン
• 4.4.0以降の特定のバージョン（例：'4.10.2'、'4.9.1'など）

組織はこの設定をグローバル設定で上書きすることを許可し、選択されたバージョンが許可されたオプションの中にある必要があります。

bestPractices

有効または無効にします ベストプラクティスルール テストランのために。ベストプラクティスはアクセシビリティを向上させますが、公式な標準には含まれません。組織はこの設定を上書きすることを許可しなければ、それは有効になりません。

experimentalRules

有効または無効にします 実験的ルール テストランのために。実験的ルールはまだ開発中であり、誤検知を生む可能性があります。組織はこの設定を グローバル設定 で上書きすることを許可しなければ、有効にはなりません。

Controller クラス

次のクラスは Controller 抽象クラスを拡張して、ウェブサイトのページのアクセシビリティ分析を手動で制御できるようにします。

Controller

abstract class Controller

その Controller 抽象クラスにはページ分析を制御するためのメソッドが含まれています。各具象クラスはこのクラスを拡張しているため、以下のメソッドはすべての具象クラスで利用可能です。

analyze

analyze(): Promise<void>

現在のページをアクセシビリティエラーに対して分析します。これを呼び出すのは、ウェブページを分析用にセットアップした後（例えば、フォームに値を入力した後）であり、 stop メソッドを使って、または autoAnalyze に設定することによって、自動分析をオフにした後です。 false。

analyze 返却値

Promise<void>

analyze 同等のCypressコマンド

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

アクセシビリティスキャンのすべての結果をaxe Developer Hubに送信します。テストランの最後に呼び出して、結果がDequeのaxe Developer Hubサーバーに送信されたことを確認してください。

flush 返却値

Promise<void>

flush 同等のCypressコマンド

cy.axeWatcherFlush()

start

start(): Promise<void>

ウェブページの自動解析を再開します。このメソッドは、ウェブページのアクセシビリティエラーを自動解析する際に再開したいときに呼び出します。

start 返却値

Promise<void>

start 同等のCypressコマンド

cy.axeWatcherStart()

stop

stop(): Promise<void>

ウェブページの自動解析を停止します。 stop メソッドを呼び出した後、ウェブページが必要とする追加のセットアップを行い、 analyze メソッドを呼び出してページのアクセシビリティエラーを確認できます。

stop 返却値

Promise<void>

stop 同等のCypressコマンド

cy.axeWatcherStop()

PlaywrightController

この PlaywrightController クラスは、PlaywrightおよびPlaywright Testでのテストランのアクセシビリティ解析を手動で制御することができます。自動アクセシビリティ解析を開始および停止し、追加のセットアップが必要なページを解析することができます。

Playwrightに関する詳細は、 Playwrightドキュメントをご覧ください。

コンストラクタ

new PlaywrightController(driver: Page): PlaywrightController

パラメータ

• driver: Page

この driver 値はPlaywright Page オブジェクトです。

返却値 PlaywrightController

概要については Controller を参照してください。

PuppeteerController

この PuppeteerController クラスは、Puppeteerによるテストランを手動で制御することができます。手動制御により、より複雑なウェブページが要求する追加セットアップを提供できます。

Puppeteerに関する詳細は、 Puppeteerをご覧ください。

コンストラクタ

new PuppeteerController(driver: Page): PuppeteerController

パラメータ

• driver: Page

この driver 値はPuppeteer Page オブジェクトです。

返却値 PuppeteerController

概要については Controller を参照してください。

WdioController

この WdioController は、WebdriverIOおよびWebdriverIO Testrunnerのテストランを手動で制御することができます。追加のセットアップや構成が必要なページについては、自動テストを停止し、そのようなセットアップが必要な各ページを手動で解析することができます。

コンストラクタ

new WdioController(driver: Browser): WdioController

パラメータ

• driver: Browser

返却値 WdioController

概要については Controller を参照してください。

WebdriverController

コンストラクタ

new WebdriverController(driver: WebDriver): WebdriverController

パラメータ

• driver： WebDriver

この driver 値はSelenium WebDriver オブジェクトです。

戻り値 WebdriverController

抽象基底クラスで実装されたメソッドは Controller を参照してください。

Cypressカスタムコマンド

Cypressのブラウザ自動化プラットフォームでは、 *Controller クラスのメソッドがカスタムコマンドとして実装されています。詳細については、 カスタムコマンド をCypressのドキュメントサイトで参照してください。

以下のカスタムコマンドが実装されています。各カスタムコマンドは、 Chainable<void> を返し、他のCypressコマンドとチェインできます。

Cypressコマンドの例

次の例は、axe Developer HubのCypressコマンドを @axe-core/watcher パッケージからインポートして、各テストの最後に axeWatcherFlush コマンドを呼び出す方法を示しています（ afterEach()に配置することによって）。

// Import the axe-watcher commands.
require('@axe-core/watcher/cypress/support')

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

タイムアウトインターフェイス

この タイムアウト オブジェクト （タイプ： タイムアウト）は、 AxeConfigurationインターフェイス 上でユーザーがそれぞれのコントローラ関数やCypressカスタムコマンドのタイムアウト値（ミリ秒）を変更できるようにします。

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}