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

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

AxeConfiguration インターフェース

axeプロパティ（設定関数に渡されるパラメータ）は、アクセシビリティテストを設定するAxe Watcher向けの通常のAxeConfiguration変更手段です。以下のプロパティがAxeConfigurationに含まれています:

apiKey

（必須）apiKey値は、apiKeyとprojectIdという2つのプロパティのうちの1つであり、AxeConfigurationに設定する必要があります。その値はAPIキー管理ページから取得できます。

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY
}

autoAnalyze

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

axe: {
  autoAnalyze: false
}

buildID

（オプション）buildIDプロパティは、nullでない場合、並列テストランナーがaxe Developer Hubで単一のテスト実行として結果を生成することを可能にします。並列テスト実行の場合、各テストランナーは同じ非ヌル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
  }
}

elementInternals

(Optional) When true, Watcher gathers ARIA roles and properties set via the ElementInternals API from custom elements that use attachInternals(). This reduces false positives on pages that use custom elements for interactive components. Requires axe-core version 4.12.0 or later.

axe: {
  elementInternals: true
}

excludeUrlPatterns

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

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

分析から除外するURLでは、一致を確認するためのURLと例のパターンの表を見つけることができます。

git

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

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

詳細についてはGitメタデータの提供を参照してください。

GitConfigオブジェクトには以下のフィールドがあります:

branch、commitSha、およびurlはgitfulフィールドです。これら3つすべてが揃っていないセッションはgitlessとして記録され保存されますが、Axe Developer Hubはgitlessセッションビューに切り替わり、以前のセッションのブランチとコミット履歴は表示されません。3つすべてのフィールドが含まれている後続のセッションを提出すると、gitfulビューが復元されます。3つのうち1つまたは2つだけが存在する場合、Axe Watcherはすべてのgitfulフィールドを削除し、セッションをgitlessとして記録し、応答に警告を含めます。

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,
    url: process.env.GIT_URL,
    commitAuthor: process.env.GIT_AUTHOR_NAME,
    commitEmail: process.env.GIT_AUTHOR_EMAIL,
    commitMessage: process.env.GIT_COMMIT_MESSAGE,
    defaultBranch: 'main'
  }
}

projectId

（必須）ウォッチャーのアクセシビリティ結果を受信するプロジェクトIDを指定します。新しいプロジェクトを作成するときに指示と共にプロジェクトIDが表示され、axe Developer Hub Project Pageからも取得できます。

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はテスト実行間で要素のIDとクラスが同じままであると想定しているからです。

  ancestryがtrueの場合、Axe Developer Hubは代わりにDOMツリー内の要素の位置を使用して、テスト実行間で同じ要素を特定します。

  次の例は、ancestryがfalseの場合のセレクタを示しています。iframe要素のIDがmain-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

（オプション）アクセシビリティ結果を送信する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

（オプション）AxeConfiguration の中の Timeouts 型の timeout オブジェクトは、各コントローラーメソッド（またはCypress用のカスタムコマンド）のタイムアウト値をミリ秒単位で設定します。（コントローラークラスについての情報はコントローラークラス、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

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

  Configuration にSelenium WebDriver 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インターフェイスは設定関数と共に使用され、1つのプロパティを含みます:

すべての設定関数はこのaxeプロパティを使用して、ウォッチャーをセットアップし、アクセシビリティテストを設定できるようにします。詳細については、上記の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のドキュメンテーションサイトのカスタムコマンドをご覧ください。

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

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
}