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

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

AxeConfiguration インターフェース

その axe プロパティ（ 設定関数に渡されるパラメータ）は、 AxeConfiguration Axe Watcherを使用してアクセシビリティテストを設定するための一般的な手段です。以下のプロパティが含まれています AxeConfiguration：

apiKey

（必須）この apiKey 値は、次の2つのプロパティのうちの1つで、apiKey との交差型です projectIdでなければなりません。 AxeConfiguration。その値は APIキー管理ページ 。

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY
}

autoAnalyze

（オプション）この値を false に設定することで、ページが自動的に分析されるのを防ぎます。手動モードに関する詳細については、 スキャンの管理。

axe: {
  autoAnalyze: false
}

buildID

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

抽象基底クラスで実装されたメソッドについては 並列でのテスト実行 を行う方法についての情報を知るために、多くの継続的インテグレーションプロバイダーで buildID を使用する方法について。

axe: {
  buildID: process.env.CI_BUILD_ID
}

configurationOverrides

（オプション）グローバル構成で設定されている値を上書きします。 グローバル設定を参照してください。 構成オーバーライドインターフェース 詳細については、

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA',
    bestPractices: true
  }
}

excludeUrlPatterns

（オプション） minimatch パターンのいずれかに一致するURLが分析されるのを防ぎます。 excludeUrlPatterns 配列内の

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

。 分析から除外するURL セクションに、URLとマッチ確認用の例のパターンのテーブルがあります。

git

（オプション）Watcherが現在のテスト実行のGitメタデータを収集する方法を制御します。次の3つの値のいずれかを受け入れます：

• true （デフォルト）：WatcherはローカルGitバイナリを使用してGit情報（ブランチ、コミットSHA、著者、およびその他のフィールド）を自動的に収集します。
• false：すべてのGitメタデータの収集を無効にします。Gitがない環境で実行する場合やGitデータの収集が不要な場合に使用してください。
• Selenium WebDriver GitConfig オブジェクト ：明示的なGitメタデータを提供し、自動検出を完全にスキップします。省略したフィールドはデフォルトで nullに設定されます。テストが別のリポジトリで実行される場合や、CI環境でGitの自動検出が信頼できない場合に使用してください。

抽象基底クラスで実装されたメソッドについては Gitメタデータの提供 詳細については、

その GitConfig オブジェクトには、以下のオプションフィールドがあります：

CI環境変数を使用した明示的なGitメタデータの供給例：

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    defaultBranch: 'main'
  }
}

projectId

（必須）プロジェクトIDを指定し、Watcherのアクセシビリティ結果を受け取ります。新しいプロジェクトを作成した際にプロジェクトIDが表示されます。また、 axe Developer Hub プロジェクトページ 。

axe: {
  projectId: process.env.AXE_PROJECT_ID
}

runContext

（オプション）ページのアクセシビリティ分析に含める要素と除外する要素を選択できます。

の値には次の選択肢があります： runContext ：

1. 分析に含める要素の単一のCSSセレクター：

   axe: {
     runContext: '.main'
   }

2. 分析に含める要素のCSSセレクターの配列：

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

3. を含むコンテキストオブジェクト： include との交差型です exclude プロパティ（上記の例の通り）。 include か exclude のいずれかまたは両方を指定します。それぞれの 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 が trueAxe 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' ]
       }
     }  
   }

• 使用例について詳しくは、 runOnly （axe-coreと共に）の オプションパラメータの例
• で詳しく確認してください。利用可能なタグ値については、 axe-coreのタグ。
• ルール、ルールID、タグに関する情報については、 ルールの説明

rules

その rules 値（ runOptions オブジェクト上）により、分析中に特定のルールを有効（enabled: true）または無効（enabled: false）にすることができます。以下に示します：

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

serverURL

（オプション）Watcherがアクセシビリティ結果を送信するAxe Developer HubサーバーのURL。デフォルトでは、 https://axe.deque.com。

プロジェクトが axe.deque.comで作成された場合、この値を設定する必要はありません。ただし、組織がAxe Developer Hubの地域インスタンス、プライベートクラウド、またはオンプレミスのデプロイメントを使用している場合は、 serverURL そのインスタンスの基本URLに設定してください：

axe: {
  apiKey: process.env.ACCESSIBILITY_API_KEY,
  projectId: process.env.PROJECT_ID,
  serverURL: process.env.SERVER_URL // e.g., 'https://axe-eu.deque.com'
}

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 が提供する設定関数によって、指定されたテストフレームワーク用にセットアップを変更し、ニーズに合わせてウォッチャーを実行する方法を調整することができます。 AxeConfigurationインターフェース 詳細については、

cypressConfig

Cypressの設定を作成します。

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

cypressConfig パラメータ

• config： Cypress.ConfigOptions & Configuration

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

戻り値： Cypress.ConfigOptions

cypressConfig 例

import { defineConfig } from 'cypress'
import { cypressConfig } from '@axe-core/watcher/cypress/config'

export default defineConfig(
  cypressConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightConfig

Playwrightの設定を作成します。

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig パラメータ

• opts： Configuration & LaunchOptions

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

戻り値： LaunchOptions

playwrightConfig 例

import { chromium } from 'playwright'
import { playwrightConfig } from '@axe-core/watcher/playwright'

const browserContext = await chromium.launchPersistentContext(
  '',
  playwrightConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightTest

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

playwrightTest(options: Options): ReturnValue

playwrightTest パラメータ

• options： Options

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

戻り値： ReturnValue

playwrightTest 例

// fixtures.ts
import { playwrightTest } from '@axe-core/watcher/playwright-test'

export default playwrightTest({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

puppeteerConfig

Puppeteerの設定を作成します。

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

puppeteerConfig パラメータ

• opts： Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  の交差型 LaunchOptions、 BrowserLaunchArgumentOptions、 BrowserConnectOptions、および Configuration。

戻り値： Options

puppeteerConfig 例

import puppeteer from 'puppeteer'
import { puppeteerConfig } from '@axe-core/watcher/puppeteer'

const browser = await puppeteer.launch(
  puppeteerConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

wdioConfig

WebdriverIOの設定を作成します。

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

wdioConfig パラメータ

• arg： Options

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

戻り値： RemoteOptions

wdioConfig 例

import { remote } from 'webdriverio'
import { wdioConfig } from '@axe-core/watcher/wdio'

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    },
    capabilities: { browserName: 'chrome' }
  })
)

wdioTestRunner

WebdriverIO Testrunnerの設定を作成します。

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

wdioTestRunner パラメータ

• params： unknown[]

  その params 値は以下のいずれかです：

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

戻り値： Options.Testrunner

wdioTestRunner 例

import { wdioTestRunner } from '@axe-core/watcher/wdio'

export const config = wdioTestRunner({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

webdriverConfig

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

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig パラメータ

• arg： WebDriverArgs

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

戻り値： Options

webdriverConfig 例

import { Builder } from 'selenium-webdriver'
import { Options } from 'selenium-webdriver/chrome'
import { webdriverConfig } from '@axe-core/watcher/webdriver'

const options = new Options()
const browser = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(
    webdriverConfig({
      axe: {
        apiKey: process.env.API_KEY,
        projectId: process.env.PROJECT_ID
      },
      options
    })
  )
  .build()

Configuration インターフェース

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

すべての 設定関数 は、この axe プロパティによって、Watcherのセットアップやアクセシビリティテストの設定が可能です。詳細は、 AxeConfigurationインターフェース 上記のセクションを参照してください。

ConfigurationOverrides インターフェース

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

accessibilityStandard

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

• 「All」 - すべての利用可能な標準に対してテストします
• 「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 以降が必要）

貴社はこの設定がグローバル設定でオーバーライドされることを許可する必要があり、選択された標準は許可されたオプションの中に含まれていなければなりません。

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA'
  }
}

axeCoreVersion

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

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

貴社はこの設定がグローバル設定でオーバーライドされることを許可する必要があり、選択されたバージョンは許可されたオプションの中に含まれていなければなりません。

axe: {
  configurationOverrides: {
    axeCoreVersion: 'latest'
  }
}

bestPractices

有効または無効にします ベストプラクティスルール のテスト実行用。有効にするとアクセシビリティが向上しますが、公式な標準の一部ではありません。これが適用されるためには、貴社がこの設定をオーバーライドすることを許可する必要があります。

axe: {
  configurationOverrides: {
    bestPractices: true
  }
}

experimentalRules

有効または無効にします 実験的ルール のテスト実行用。実験的ルールはまだ開発中であり、誤った見解を生む可能性があります。貴社は、これが適用されるために グローバル設定 でこの設定をオーバーライドすることを許可する必要があります。

axe: {
  configurationOverrides: {
    experimentalRules: true
  }
}

Controller クラス

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

Controller

abstract class Controller

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

analyze

analyze(): Promise<void>

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

analyze 戻り値

Promise<void>

analyze 例

await controller.analyze()

analyze 同等のCypressコマンド

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

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

flush 戻り値

Promise<void>

flush 例

await controller.flush()

flush 同等のCypressコマンド

cy.axeWatcherFlush()

start

start(): Promise<void>

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

start 戻り値

Promise<void>

start 例

await controller.start()

start 同等のCypressコマンド

cy.axeWatcherStart()

stop

stop(): Promise<void>

ウェブページの自動解析を停止します。この stop メソッドを呼び出した後、ウェブページの追加セットアップを行い、その後 analyze メソッドを呼び出して、アクセシビリティエラーをチェックします。

stop 戻り値

Promise<void>

stop 例

await controller.stop()

stop 同等のCypressコマンド

cy.axeWatcherStop()

PlaywrightController

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

Playwrightについての詳細は、 Playwrightのドキュメント。

コンストラクタ

new PlaywrightController(driver: Page): PlaywrightController

パラメータ

• driver： Page

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

戻り値 PlaywrightController

PlaywrightController 例

import { PlaywrightController, wrapPlaywrightPage } from '@axe-core/watcher/playwright'

let page = await browserContext.newPage()
const controller = new PlaywrightController(page)
page = wrapPlaywrightPage(page, controller)

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

PuppeteerController

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

Puppeteerについての詳細は、 Puppeteer。

コンストラクタ

new PuppeteerController(driver: Page): PuppeteerController

パラメータ

• driver： Page

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

戻り値 PuppeteerController

PuppeteerController 例

import { PuppeteerController, wrapPuppeteerPage } from '@axe-core/watcher/puppeteer'

let page = await browser.newPage()
const controller = new PuppeteerController(page)
page = wrapPuppeteerPage(page, controller)

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

WdioController

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

コンストラクタ

new WdioController(driver: Browser): WdioController

パラメータ

• driver： Browser

戻り値 WdioController

WdioController 例

import { WdioController, wrapWdio } from '@axe-core/watcher/wdio'

// browser is the WebdriverIO Browser instance from your wdioConfig() setup
const controller = new WdioController(browser)
wrapWdio(browser, controller)

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

WebdriverController

コンストラクタ

new WebdriverController(driver: WebDriver): WebdriverController

パラメータ

• driver： WebDriver

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

戻り値 WebdriverController

WebdriverController 例

import { WebdriverController, wrapWebdriver } from '@axe-core/watcher/webdriver'

// browser is the Selenium WebDriver instance from your webdriverConfig() setup
const controller = new WebdriverController(browser)
browser = wrapWebdriver(browser, controller)

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

Cypressカスタムコマンド

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

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

Cypressコマンド例

次の例は、 @axe-core/watcher パッケージからAxe Developer HubのCypressコマンドをインポートし、各テストの最後に 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
}