AxeWatcherOptions クラス

このAxeWatcherOptionsクラスは、Axe Watcher の Selenium および Playwright Java 統合向けの設定オプションを提供します。このクラスを使用することで、サーバー接続の詳細、テスト実行の挙動、およびアクセシビリティ基準を含め、Axe Watcher が自動ブラウザテスト中にアクセシビリティテストをどのように実施するかをカスタマイズできます。

コンストラクタ

AxeWatcherOptions()

デフォルト設定でAxeWatcherOptionsの新しいインスタンスを作成します。デフォルト値は次のとおりです。

• serverUrl: https://axe.deque.com
• autoAnalyze: true
• git: true

AxeWatcherOptions options = new AxeWatcherOptions();

メソッド

setAllowedOrigins(String[] allowedOrigins)

クロスオリジンの<iframe>コンテンツを分析するオリジンを設定します。Watcher 4.6.0以降が必要です。

デフォルトでは、同一オリジンのフレームのみが分析され、クロスオリジンフレーム内のアクセシビリティ問題は結果に含まれません。このメソッドを呼び出して、名前を指定したオリジンを対象に加えてください。常に許可されている自分のアプリケーションのオリジンは含めないでください。

各エントリはオリジンでなければならず、それ以外は含まれてはいけません: スキーム（httpまたはhttps）、ホスト、およびオプションのポートです。末尾のスラッシュとデフォルトのポート（:80のhttp、:443のhttps）は削除され、ホストは小文字に変換され、重複は破棄されます。ワイルドカードはサポートされていないため、すべてのオリジンを明示的に指定する必要があります。英字以外の文字を含むドメインは、その内部で使用されるプニコード形式（xn--で始まるブラウザが内部で使用する等価表記）で指定する必要があります。

信頼性の影響、分析時間への影響、及び自動分析との相互作用については、クロスオリジンのiframeを分析を参照してください。

パラメーター：

• allowedOrigins - クロスオリジンのiframeを分析すべきオリジン

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例外：

• IllegalArgumentException - エントリが単純なhttpまたはhttpsオリジンでない場合、ワイルドカードを含む場合、パス、クエリ、フラグメント、クレデンシャルを含む場合、または英字以外の文字を含むドメインを使用する場合。これらのエントリは無視されるのではなく、拒否されます。なぜなら、さもなければわずかな誤差でフレームが分析されずに、テスト実行が成功として報告されるためです。

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});

setApiKey(String apiKey)

Axe Developer Hub で認証するための API キーを設定します。これは Axe Watcher を使用するために必要です。

パラメーター：

• apiKey - あなたの Axe Developer Hub API キー

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setApiKey("your-api-key-here");

setAutoAnalyze(boolean autoAnalyze)

テスト対象ページの自動解析を行うかどうかを設定します。デフォルトはtrueです。

パラメーター：

• autoAnalyze - テスト対象ページを自動解析するかどうか

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable automatic analysis for manual control
options.setAutoAnalyze(false);

setBuildId(String buildId)

並列テストランナー用のビルド ID を設定します。null でない場合、並列テストランナーが生成した結果を Axe Developer Hub 上で単一のテスト実行として表示できます。

パラメーター：

• buildId - 結果を集約するためのビルド ID、通常は CI/CD のビルド ID

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Using a CI build ID from an environment variable
options.setBuildId(System.getenv("GITHUB_RUN_ID"));

setConfigurationOverrides(ConfigurationOverrides configurationOverrides)

組織のAxeアカウント全体の設定に基づいて設定のオーバーライドを行います。

パラメーター：

• configurationOverrides - 設定のオーバーライド

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Override to use WCAG 2.2 AA and enable best practices
ConfigurationOverrides overrides = new ConfigurationOverrides()
    .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
    .setEnableBestPractices(true);
options.setConfigurationOverrides(overrides);

setElementInternals(boolean elementInternals)

カスタム要素に対するElementInternalsサポートを有効にします。有効にすると、Axe WatcherはElementInternals APIを通じて設定されたARIAロールおよびプロパティを収集し、attachInternals()を使用するカスタム要素のあるページで誤検出を減らします。axe-coreバージョン4.12.0以降が必要です。

パラメーター：

• elementInternals - ElementInternalsサポートを有効にするかどうか（デフォルト：false）

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setElementInternals(true);

setExcludeUrlPatterns(String[] excludeUrlPatterns)

URLパターンを設定して、分析から除外します。URLを一致させるためにMinimatchライブラリを使用します。

パラメーター：

• excludeUrlPatterns - 分析から除外するURLパターン

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Exclude login pages and admin dashboard
options.setExcludeUrlPatterns(new String[] {
    "https://example.com/login*",
    "https://example.com/admin/*"
});

setGit(boolean git)

Watcher が現在のテスト実行の Git 情報を収集するかどうかを設定します。デフォルトは true です。Git がない環境で実行する場合や、Git データの収集が不要な場合は false に設定します。プロジェクトがすでに Git にロックされている場合、今 setGit(false) を呼び出すと、Git のないセッションを生成するのではなく、実行が拒否されます。詳細は 実行が拒否されました: データ形式またはリポジトリがプロジェクトと一致しません を参照してください。

パラメーター：

• git - Git情報を収集するかどうか

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable Git info collection
options.setGit(false);

setGitInfo(AxeWatcherGitInfo gitInfo)

自動 Git 検出をバイパスして現在のテスト実行の明示的な Git メタデータを設定します。これは、テストがテスト対象のリポジトリとは別のリポジトリで実行される場合や、Git の自動検出が信頼できない CI 環境（例: 浅いクローンや分離された HEAD 状態）で使用します。プロジェクトがすでにリポジトリにロックされている場合、提供するメタデータはそれと一致しなければなりません。異なるリポジトリを指名するメタデータは受け入れられるのではなく、拒否されます。

非ヌルのAxeWatcherGitInfoが設定されている場合、これはsetGit(boolean)より優先されます—提供されたメタデータはsetGit(false)が以前に呼び出されていても送信されます。nullを渡すと、以前に設定されたメタデータがクリアされ、setGit(boolean)によって制御される動作に戻ります。

詳しくはGitメタデータの提供およびAxeWatcherGitInfoを参照してください。

パラメーター：

• gitInfo - 使用する明示的なGitメタデータ。nullを渡すと、以前に設定されたメタデータがクリアされ、自動検出の動作に戻ります。

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("AXE_DEVELOPER_HUB_API_KEY"))
    .setProjectId(System.getenv("AXE_DEVELOPER_HUB_PROJECT_ID"))
    .setGitInfo(new AxeWatcherGitInfo()
        .setCommitSha(System.getenv("GIT_COMMIT"))
        .setBranch(System.getenv("GIT_BRANCH"))
        .setDefaultBranch("main"));

setProjectId(String projectId)

パラメーター：

• projectId - アクセシビリティ結果を受け取るプロジェクトのプロジェクトID

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setProjectId("your-project-ID-here"); // a uuid identifying the project

setRunContext(AxeRunContext runContext)

テスト対象ページのコンテキストを設定し、解析対象の範囲を制限したり、特定の要素を解析から除外したりします。

パラメーター：

• runContext - axe-core 解析の実行コンテキスト

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Only analyze main content and exclude navigation
AxeRunContext context = new AxeRunContext()
    .setInclude(Arrays.asList("#main-content"))
    .setExclude(Arrays.asList("#navigation"));
options.setRunContext(context);

setRunOptions(AxeRunOptions runOptions)

axe-core 解析の追加オプションを設定します。例えば、実行するルールや無効にするルールなどです。

パラメーター：

• runOptions - axe-core 解析の実行オプション

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable the color contrast rule and focus on WCAG 2.1 AA
Map<String, AxeRuleOptions> rules = new HashMap<>();
rules.put("color-contrast", new AxeRuleOptions().setEnabled(false));

AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa"));

AxeRunOptions runOptions = new AxeRunOptions()
    .setRules(rules)
    .setRunOnly(runOnly);

options.setRunOptions(runOptions);

setScreenshotDir(String screenshotDir)

スクリーンショットがローカルに保存されるディレクトリを設定します。Axe Developer Hubへのアップロードに加えて行われます。setTakeScreenshots(true)も呼び出されていない限り効果はありません。

設定されると、スクリーンショットは{screenshotDir}/YYYYMMDDTHHmmssSSS-{screenshot_id}.pngに書き込まれます。相対パスはJVMの作業ディレクトリに対して解決されます。ディレクトリの作成やファイル書き込みに失敗した場合、警告が記録され、テストスイートは続行します。

パラメーター：

• screenshotDir - スクリーンショットを保存するディレクトリ。nullまたは空の文字列を渡すとローカル保存を無効にします。

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setTakeScreenshots(true)
    .setScreenshotDir("./axe-screenshots");

setServerUrl(String serverUrl)

アクセシビリティ結果を送信するサーバーの URL を設定します。デフォルトはhttps://axe.deque.comです。

パラメーター：

• serverUrl - アクセシビリティ結果を送信するサーバーの URL

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setServerUrl("https://custom.axe-instance.com");

setTakeScreenshots(boolean takeScreenshots)

違反が見つかったときにページのスクリーンショットをキャプチャするかどうかを設定します。

パラメーター：

• takeScreenshots - 違反が見つかったときにスクリーンショットをキャプチャするかどうか（デフォルト：false）

戻り値：

• AxeWatcherOptions - メソッドチェーンのための現在のインスタンス

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setTakeScreenshots(true);

getAllowedOrigins()

クロスオリジンのiframeが分析されるオリジンを取得します。正規化された値を返し、setAllowedOrigins()に渡した値と異なる場合があります: 末尾のスラッシュとデフォルトのポートは削除され、ホストは小文字に変換され、重複は破棄されます。

戻り値：

• String[] - 現在許可されているオリジン、または設定されていなければnull

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setAllowedOrigins(new String[] {"https://Pay.example.com:443/"});
String[] origins = options.getAllowedOrigins(); // {"https://pay.example.com"}

getApiKey()

現在のAPIキーを取得します。

戻り値：

• String - 現在のAPIキー

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setApiKey("my-api-key");
String apiKey = options.getApiKey(); // Returns "my-api-key"

getAutoAnalyze()

自動分析が有効かどうかを取得します。

戻り値：

• boolean - 自動分析が有効かどうか

例：

AxeWatcherOptions options = new AxeWatcherOptions();
boolean autoAnalyze = options.getAutoAnalyze(); // Returns true (default)

getBuildId()

現在のビルドIDを取得します。

戻り値：

• String - 現在のビルドID

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setBuildId("build-123");
String buildId = options.getBuildId(); // Returns "build-123"

getConfigurationOverrides()

現在の構成のオーバーライドを取得します。

戻り値：

• ConfigurationOverrides - 現在の構成のオーバーライド

例：

AxeWatcherOptions options = new AxeWatcherOptions();
ConfigurationOverrides overrides = new ConfigurationOverrides();
options.setConfigurationOverrides(overrides);
ConfigurationOverrides current = options.getConfigurationOverrides();

getElementInternals()

ElementInternalsのサポートが有効かどうかを取得します。

戻り値：

• boolean - ElementInternalsのサポートが有効な場合はtrue、そうでない場合はfalse

例：

AxeWatcherOptions options = new AxeWatcherOptions();
boolean enabled = options.getElementInternals(); // Returns false (default)

getExcludeUrlPatterns()

現在の除外URLパターンを取得します。

戻り値：

• String[] - 現在の除外URLパターン

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setExcludeUrlPatterns(new String[] {"https://example.com/login*"});
String[] patterns = options.getExcludeUrlPatterns();

getGit()

Git情報の収集が有効かどうかを取得します。

戻り値：

• boolean - Git情報収集が有効な場合はtrue、無効な場合はfalse

例：

AxeWatcherOptions options = new AxeWatcherOptions();
boolean git = options.getGit(); // Returns true (default)

getGitInfo()

現在設定されている明示的なGitメタデータを取得します。明示的なメタデータが設定されていない場合はnullを返します。

戻り値：

• AxeWatcherGitInfo - 現在の明示的なGitメタデータ、設定されていない場合はnull

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setGitInfo(new AxeWatcherGitInfo().setBranch("main"));
AxeWatcherGitInfo gitInfo = options.getGitInfo(); // Returns the configured AxeWatcherGitInfo

getProjectId()

現在のプロジェクトIDを取得します。プロジェクトIDは、Axe Watcherのアクセシビリティ結果を受け取るプロジェクトを識別します。

戻り値：

• String - 現在のプロジェクトID

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setProjectId("my-project-ID"); // should be a uuid identifying the project
String projectId = options.getProjectId(); // Returns the project ID

getRunContext()

現在の実行コンテキストを取得します。

戻り値：

• AxeRunContext - 現在の実行コンテキスト

例：

AxeWatcherOptions options = new AxeWatcherOptions();
AxeRunContext context = new AxeRunContext();
options.setRunContext(context);
AxeRunContext currentContext = options.getRunContext();

getRunOptions()

現在の実行オプションを取得します。

戻り値：

• AxeRunOptions - 現在の実行オプション

例：

AxeWatcherOptions options = new AxeWatcherOptions();
AxeRunOptions runOptions = new AxeRunOptions();
options.setRunOptions(runOptions);
AxeRunOptions currentOptions = options.getRunOptions();

getScreenshotDir()

現在のスクリーンショットディレクトリを取得し、ローカル保存ディレクトリが設定されていない場合はnullを返します。

戻り値：

• String - 現在のスクリーンショットディレクトリ、またはnull

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setScreenshotDir("./screenshots");
String dir = options.getScreenshotDir(); // Returns "./screenshots"

getServerUrl()

現在のサーバーURLを取得します。

戻り値：

• String - 現在のサーバーURL

例：

AxeWatcherOptions options = new AxeWatcherOptions();
String serverUrl = options.getServerUrl(); // Returns default "https://axe.deque.com"

getTakeScreenshots()

スクリーンショットのキャプチャが有効かどうかを取得します。

戻り値：

• boolean - 違反が見つかったときにスクリーンショットがキャプチャされる場合はtrue、それ以外はfalse

例：

AxeWatcherOptions options = new AxeWatcherOptions();
options.setTakeScreenshots(true);
boolean takeScreenshots = options.getTakeScreenshots(); // Returns true

toJson()

AxeWatcherOptionsインスタンスをJSON文字列にシリアル化します。

戻り値：

• String - オプションのJSON文字列表現

例外：

• RuntimeException - configurationOverridesとrunOptions.runOnlyが一緒に使用された場合（これらは相互排他的です）

例：

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey("my-api-key")
    .setProjectId("my-project-id")
    .setServerUrl("https://custom.axe-instance.com");
String json = options.toJson();

構成の制限事項

AxeWatcherOptionsの設定時、次の制約に注意してください：

1. APIキーが必要です：

   options.setApiKey("your-api-key"); // Required

2. プロジェクトIDが必要です：

   options.setProjectId("your-project-ID"); // Required

3. 相互排他的なオプション：

   runOptions.runOnlyとconfigurationOverrides.accessibilityStandardを一緒に使用することはできません。特定のアクセシビリティ基準を設定する必要がある場合は、以下のようにConfigurationOverridesを使用してください：

   // Correct: Using ConfigurationOverrides
   options.setConfigurationOverrides(
       new ConfigurationOverrides()
           .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
   );
   
   // Correct: Using RunOptions.runOnly
   options.setRunOptions(
       new AxeRunOptions()
           .setRunOnly(new AxeRunOnly().setType("tag").setValues(Arrays.asList("wcag22aa")))
   );
   
   // Incorrect: Using both together will throw an exception
   options.setConfigurationOverrides(
       new ConfigurationOverrides()
           .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
   ).setRunOptions(
       new AxeRunOptions()
           .setRunOnly(new AxeRunOnly().setType("tag").setValues(Arrays.asList("wcag21aa")))
   );

4. 自動分析はiframe内で行われた変更を検出しない：

   setAutoAnalyze(true)を使用すると、Watcherはトップレベルのページのみを観察するため、iframe内（同一オリジンまたはクロスオリジン）の変更はページ上の変化がないように見え、自動分析がスキップされます。したがって、iframeはトップレベルページの最後の変更時に分析されます。フレーム内での操作後は、トップレベルフレームに戻ってanalyze()を明示的に呼び出してください。ご自身で依頼した分析は決してスキップされません。

   // The automatic analysis after this interaction is skipped: the top-level page is unchanged
   driver.switchTo().frame("pay");
   driver.findElement(By.id("submit")).click();
   
   // Return to the top-level frame, then analyze the resulting state
   driver.switchTo().defaultContent();
   ((AxeWatcherDriver) driver).axeWatcher().analyze();

   詳細についてはクロスオリジンのiframeを分析を参照してください。

関連項目

• AxeWatcher
• AxeWatcherDriver
• AxeWatcherController
• AxeWatcherGitInfo
• AxeRunContext
• AxeRunOptions
• AxeRunOnly
• AxeRuleOptions
• ConfigurationOverrides