AxeWatcherOptions クラス

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

コンストラクタ

AxeWatcherOptions()

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

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

AxeWatcherOptions options = new AxeWatcherOptions();

メソッド

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");

setProjectId(String projectId)

パラメータ：

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

戻り値：

• AxeWatcherOptions - メソッドチェーンに使用する現在のインスタンス

例：

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

setServerUrl(String serverUrl)

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

パラメータ：

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

戻り値：

• AxeWatcherOptions - メソッドチェーンに使用する現在のインスタンス

例：

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

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"));

setAutoAnalyze(boolean autoAnalyze)

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

パラメータ：

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

戻り値：

• AxeWatcherOptions - メソッドチェーンに使用する現在のインスタンス

例：

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

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);

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 - 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"));

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);

setTakeScreenshots(boolean takeScreenshots)

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

パラメーター：

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

戻り値：

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

例：

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

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");

setElementInternals(boolean elementInternals)

Enables ElementInternals support for custom elements. When enabled, Axe Watcher gathers ARIA roles and properties set via the ElementInternals API, reducing false positives on pages that use custom elements with attachInternals(). Requires axe-core version 4.12.0 or later.

パラメーター：

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

戻り値：

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

例：

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

getApiKey()

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

戻り値：

• String - 現在のAPIキー

例：

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

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

getServerUrl()

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

返される値：

• String - 現在のサーバーURL

例：

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

getBuildId()

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

返される値：

• String - 現在のビルドID

例：

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

getAutoAnalyze()

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

返される値：

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

例：

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

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();

getExcludeUrlPatterns()

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

返される値：

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

例：

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

getGit()

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

返される値：

• boolean - true if Git info collection is enabled (default), false if disabled

例：

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

getConfigurationOverrides()

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

返される値：

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

例：

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

getTakeScreenshots()

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

返される値：

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

例：

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

getScreenshotDir()

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

返される値：

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

例：

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

getElementInternals()

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

戻り値：

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

例：

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

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")))
   );

関連項目

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