スキャンを管理する

デフォルトでは、自動モードとして知られるモードで、Axe Watcher はウェブページを分析するタイミングを自動的に決定します（テストスイートがページに訪れたときや、ページのDOMの変化が検出されたとき）。この自動解析が、組織の目標に合わない結果をもたらすことがあります：あまり関心のないページや、組織の他の部門に属するページを含む多すぎるページを分析する場合です。自動モードをオフにすることで、ウェブページを分析するタイミング（または分析するかどうか）を自分で決定することができます（手動モードとして知られています）。

ユースケース

ウェブサイトの一部分のみをスキャンする

手動モードを使用して、ウェブサイトの一部分のみをスキャンできます。たとえば、あなたのチームがサイトのショッピングカート機能を管理していて、テストスイートが製品をカートに追加するためにカタログページ（あなたのチームが管理していないページ）を訪れる必要がある場合、カタログページのアクセシビリティテストは避けたいと思うでしょう。テストスイートでショッピングカートページに到達したら、自動解析を再度有効にできます。それから、ショッピングカートのテストが完了したときに再度自動解析を無効にすることができます。

次のステップ

• カタログページのテストを避けるための設定で自動分析を無効化。
• ショッピングカートページのために自動分析の有効化。
• ショッピングカートページのテスト終了時にページ訪問を後のページがテストされないようにコールによる自動分析の無効化。

ダイナミックコンテンツの読み込み

複雑な読み込みシーケンスを持つページをテストしないようにするために手動モードを使用できます。テストしたいページがバックグラウンドで多くのリソースを動的にロードする場合、それが完全にロードされるまで自動モードを無効にできます。これにより、ページが完全にロードされたときにのみ存在するアクセシビリティ問題に限定することができます。また、ロード中のアニメーションやその他のロード UI の間に発生するアクセシビリティチェックを防ぐことができます。

次のステップ

• 読み込みアニメーションや UI がアクセシビリティエラーについてテストされないように設定で自動分析を無効化。
• ページが完全に読み込まれたときに自動アクセシビリティテストを再開するために自動分析の有効化。

特定のページ状態をキャプチャする

特定のページ状態をスキャンしたい場合、ページを設定した後にアクセシビリティ解析を手動でトリガーすることができます。

次のステップ

• ページが必要な状態になる前にアクセシビリティ解析が発生するのを防ぐために設定で自動分析を無効化。
• 興味のある特定のページ状態をテストするためにページの手動分析。

大規模なテストスイートのスコープを制限する

自動解析を無効にすることで、より大規模で包括的なテストスイートを使用しつつ、アクセシビリティテストをその一部に限定することができます。この場合、より大規模なテストスイートを小さなテストスイートに分解し、必要なテストスイートのみでアクセシビリティをテストする必要はありません。

次のステップ

• テストスイートの冒頭での自動アクセシビリティ解析の開始を防ぐために設定で自動分析を無効化。
• テストしたいテストスイートの部分に到達したときに自動分析の有効化。
• アクセシビリティエラーをテストしたくないテストスイートの部分のアクセシビリティテストを無効にするためにコールによる自動分析の無効化。

手動モードの使い方

設定で自動分析を無効化を参照して設定で自動解析を無効にすることができます。

ページ解析は、Controllerオブジェクト上の3つのメソッドまたはCypressの同等のコマンドで制御されます。

1. 現在のページを解析するためにanalyze()（Cypressではcy.axeWatcherAnalyze()）。
2. 自動アクセシビリティ解析を有効にするためにstart()（Cypressではcy.axeWatcherStart()）。
3. 自動アクセシビリティ解析を無効にするためにstop()（Cypressではcy.axeWatcherStop()）。

コントローラーオブジェクトの取得

（JavaScript/TypeScript）Controllerオブジェクトの取得に関する情報は、テストフレームワークの説明ページのステップ４を参照してください。

JavaScript：

• Playwright
• Puppeteer
• WebdriverIO
• WebdriverIO TestRunner
• WebDriverJS

TypeScript：

• Playwright
• Puppeteer
• WebdriverIO
• WebdriverIO TestRunner
• WebDriverJS

（Java）Javaの場合は、テストフレームワークの説明ページのステップ3を参照してください。ステップ4 はそのwrappedDriverをキャストしてそのflush()メソッドを呼び出す方法を示しています：

• Selenium

Cypress

（JavaScript/TypeScript）Cypressの場合、グローバルcyオブジェクトを以下の同等のコマンドで使用できます：

Playwright Test

（JavaScript/TypeScript）Playwright Testの場合、pageから取得できるControllerオブジェクト（PlaywrightController）にはaxeWatcherオブジェクトが含まれています。このaxeWatcherオブジェクトを使用してControllerメソッドを呼び出すことができます（以下の例はTypeScriptです）：

import { test, expect } from './fixtures'

test('example test', async ({ page }) => {
  await page.goto('https://example.com')
  await page.axeWatcher.analyze()
})

設定で自動分析を無効化

自動アクセシビリティテストを無効化するには、

• （JavaScript/TypeScript）axe設定オブジェクトにあるautoAnalyzeプロパティをfalseに設定します。
• （Java） setAutoAnalyze()メソッドをfalseで呼び出します。

（JavaScript/TypeScript）例えば、設定でautoAnalyzeをfalseに設定します（以下のCypress JavaScriptサンプルで行を強調）。

const { defineConfig } = require('cypress');
const { cypressConfig } = require('@axe-core/watcher/cypress/config');

const API_KEY = process.env.API_KEY
const PROJECT_ID = process.env.PROJECT_ID

module.exports = defineConfig(  
  cypressConfig({
    axe: {
      apiKey: API_KEY,      projectId: PROJECT_ID,
      autoAnalyze: false
    },
    // Your existing Cypress configuration code here
  })
);

コールによる自動分析の無効化

Cypressでは、axeWatcherStop()コマンドを使用できます：

cy.axeWatcherStop()

他のテスト統合では、あなたのコントローラーオブジェクトでstop()メソッドを使用します：

await controller.stop()

（Java）Javaウォッチャー統合では、AxeWatcherController.stop()メソッドを使用します。

テストフレームワークのためのコントローラーオブジェクトの取得についての詳細はコントローラーオブジェクトの取得を参照してください。

ページの手動分析

自動分析を無効にした後、（JavaScript/TypeScript）axeWatcherAnalyze()（Cypress用）やanalyze()（他のテスト統合で）を追加できます。（Java）Javaの場合は、AxeWatcherController.analyze()メソッドを使用します。

例えば、Cypressの場合：

describe('My Login Application', () => {
  it('should login with valid credentials', () => {
    cy.visit('https://the-internet.herokuapp.com/login')
      // Analyze the page.
      .axeWatcherAnalyze()      .get('#username')
      .type('tomsmith')
      .get('#password')
      .type('SuperSecretPassword!')
      .get('button[type="submit"]')
      .click()
      .wait(1000)
      // Analyze the page.
      .axeWatcherAnalyze()      // Restart automatic axe analysis.
      .axeWatcherStart()
      .get('#flash')
      .should('exist')
  })
})

テストフレームワークのためのコントローラーオブジェクトの取得についての詳細はコントローラーオブジェクトの取得を参照してください。

自動分析の有効化

Cypressでは、axeWatcherStartコマンドを使用できます：

cy.axeWatcherStart()

他のテスト統合では、あなたのコントローラーオブジェクトでstartメソッドを使用します：

await controller.start()

テストフレームワークのためのコントローラーオブジェクトの取得についての詳細はコントローラーオブジェクトの取得を参照してください。

特定のテスト実行のみウォッチャーを実行

エンドツーエンドテストは時間やクラウドのコンピューティングコストが高い場合があります。全てのコミットやテスト実行ごとにウォッチャーにページを分析させるのではなく、専らアクセシビリティスキャンが必要な時に実行したいかもしれません。環境変数の値をautoAnalyzeに渡すことで分析の開始を制御できます。これにより、分析なしのテストコマンドと、それを含めたコマンドの二つの異なるテスト命令を作成できます。

（JavaScript/TypeScript）例えば、Cypress設定の場合：

const { defineConfig } = require('cypress')
const { cypressConfig } = require('@axe-core/watcher/cypress/config')

const API_KEY = process.env.API_KEY
const PROJECT_ID = process.env.PROJECT_ID
const ACCESSIBILITY_TESTING = process.env.ACCESSIBILITY_TESTING === 'true'

module.exports = defineConfig(
  cypressConfig({
    axe: {
      apiKey: API_KEY,
      projectId: PROJECT_ID,
      autoAnalyze: ACCESSIBILITY_TESTING
    },
    // Your existing Cypress configuration code here
  })
)

package.jsonに2つのスクリプトを追加し、一つは変数を設定し、もう一つは設定しません：

{
  "scripts": {
    "test:e2e": "cypress run",
    "test:e2e:accessibility": "ACCESSIBILITY_TESTING=true cypress run"
  }
}

Windows上では、cross-envを使って環境変数をクロスプラットフォームで設定します。環境変数名は任意に選べます；ACCESSIBILITY_TESTINGはただの例です。

同じアプローチは、他のJavaScriptおよびTypeScriptのテストフレームワークにも適用されます: 設定ファイルで変数を読み、そのブール値をautoAnalyzeに渡します。(Java) Javaユーザーは、その値をsetAutoAnalyze()に渡すことができます。

関連情報

• (JavaScript/TypeScript) 手動モードテストの動作する例が2つ（CypressとPlaywright）あります、GitHubのwatcher-examplesレポに以下の例を参照してください:
  • Cypressについては、Cypress 手動モードを参照してください
  • Playwrightについては、Playwright 手動モードを参照してください