Selenium Java API

Overview

Configure and run accessibility analysis in your Selenium Java tests with the AccessibilityAuditor API. Use AuditConfig to provide the WebDriver instance and test behavior, and use AnalysisConfig to control report output, URL exclusions, custom tags, and other engine settings.

API methods

AccessibilityAuditor.levelAnalyze

public static AnalysisResult levelAnalyze(AuditConfig config)

Runs a static accessibility analysis on the page currently loaded by config.driver. When config.saveReport is true, the method saves a JSON report under config.analysisConfiguration.reportPath.

Properties

Property	Type	Default	Description
config	AuditConfig	—	Required audit configuration. The driver must not be null.

Returns

Returns an AnalysisResult. Determine the outcome based on the fields included in the result.

Report	Error	Meaning
Present	Null	Analysis succeeded.
Null	Present	Analysis failed before producing findings, such as from a script or input/output error.
Present	Present	Strict mode detected one or more rules with findings.
Null	Null	The engine did not run because switchOff was set to true.

AnalysisResult also provides the following methods:

• getConfig(): Returns the effective AnalysisConfig after defaults and environment variable overrides are applied.
• getIssuesFound(): Returns the total number of issues across all rules in the report. Returns 0 when no report is available.

Usage

Call levelAnalyze after the page reaches a stable success state. If you call it from a teardown hook, such as JUnit @AfterEach, check the test outcome first. Otherwise, each retry can generate a report even when the test fails before completing.

AuditConfig

Use AuditConfig to configure the Selenium audit workflow. Build the configuration with Lombok's @Builder.

Option	Type	Description
driver	WebDriver	The Selenium WebDriver instance to analyze. This value is required. levelAnalyze returns a failed result when the driver is null.
auditTimeout	Duration	Sets the JavaScript execution timeout applied to the driver while the engine runs. Default: Duration.ofMinutes(10).
analysisConfiguration	AnalysisConfig	Sets engine-level options, including switchOff, reportPath, ignoreUrls, and customTags. Default: AnalysisConfig.builder().build().
saveReport	boolean	Writes the Level CI scope report to analysisConfiguration.reportPath when set to true. Default: false. Environment variable: LEVEL_CI_SAVE_JSON_REPORT.
strict	boolean	Returns a failed result when the engine reports a rule with findings. Use strict mode to fail tests on accessibility regressions. Default: false. Environment variable: LEVEL_CI_STRICT.

AnalysisConfig

Use AnalysisConfig to configure engine behavior for an analysis run. Build the configuration with Lombok's @Builder.

Option	Type	Description
switchOff	Boolean	Disables analysis globally or for a specific run. When set to true, levelAnalyze skips the engine. Default: false. Environment variable: LEVEL_CI_SWITCH_OFF.
reportPath	String	Sets the folder path for analysis artifacts when AuditConfig.saveReport is true. Default: ./level-ci-reports. Environment variable: LEVEL_CI_REPORT_PATH.
ignoreUrls	List<String>	Skips analysis for URLs matching the provided regular expressions. Enter each regular expression as a source string without leading or trailing slashes.
customTags	Set<String>	Adds custom tags for scan identification. Tags appear with issues in the dashboard so you can associate them with the test scenario that generated them.

AnalysisResult

AnalysisResult contains the generated report, any analysis error, and the effective configuration. Refer to the levelAnalyze return values to determine the outcome of an analysis.

Component-level screenshots (experimental)

To enable component-level screenshots for detected accessibility issues, add the experimental.elementScreenshots option to your levelAnalyze() configuration.

This setting is currently experimental. Enabling component-level screenshots may increase scan execution time because screenshots are captured during the accessibility analysis.

Examples

Use these examples to configure report storage, disable analysis, add custom tags, ignore URLs, and fail tests when accessibility findings are detected.

Method AccessibilityAuditor.levelAnalyze

|
public static AnalysisResult levelAnalyze(AuditConfig config)
        

Usage levelAnalyze

|
WebDriver driver = new ChromeDriver(new ChromeOptions().addArguments(”–headless=new”));
driver.get(“http://localhost:5000”);
AnalysisResult result = AccessibilityAuditor.levelAnalyze(LevelSetup.getAuditConfig(driver));
assertThat(result.getError()).isNull();

  

    Config AuditConfig
  
  

    
|
AuditConfig.builder()
.driver(driver)
.auditTimeout(Duration.ofMinutes(10))
.analysisConfiguration(AnalysisConfig.builder().build())
.saveReport(true)
.strict(false)
.build();

  

    Config AnalysisConfig
  
  

    
|
AnalysisConfig.builder()
.switchOff(false)
.reportPath(”./level-ci/level-ci-reports”)
.ignoreUrls(List.of(“login”, “settings/privacy”))
.customTags(Set.of(“alpha”, “scenario-1”))
.build();

  

    Class AnalysisResult
  
  

    
|
public class AnalysisResult {
private AnalysisReport report;
private AnalysisError error;
private AnalysisConfig config;
public int getIssuesFound() { /* ... */ }
}

  

    Set custom report path Option 1: With the builder
  
  

    
|
AuditConfig.builder()
.driver(driver)
.analysisConfiguration(
AnalysisConfig.builder()
.reportPath(”./custom-reports-folder”)
.build()
)
.saveReport(true)
.build();

  

    Set custom report path Option 2: Using an environment variable
  
  

    
|
LEVEL_CI_REPORT_PATH=./custom-reports

  

    Disable rule check Option 1: With the builder
  
  

    
|
AnalysisConfig.builder()
.switchOff(true)
.build();

  

    Disable rule check Option 2: Using an environment variable
  
  

    
|
LEVEL_CI_SWITCH_OFF=true

  

    Add specific tags for this analysis run
  
  

    
|
AnalysisConfig.builder()
.customTags(Set.of(“my-tag”, “regression”))
.build();

  

    Ignore specific URLs during analysis
  
  

    
|
AnalysisConfig.builder()
.ignoreUrls(List.of(“localhost:3000”, “example\.com”))
.build();

  

    Fail tests on findings Option 1: With the builder
  
  

    
|
AuditConfig.builder()
.driver(driver)
.analysisConfiguration(AnalysisConfig.builder().build())
.strict(true)
.build();

  

    Fail tests on findings Option 2: Using an environment variable
  
  

    
|
LEVEL_CI_STRICT=true

  

    Strict mode Test assertion
  
  

    
|
assertThat(result.getError()).isNull();
  

Enable component-level screenshots Experimental

|
    AuditConfig.builder()
        .driver(driver)
        .analysisConfiguration(
            AnalysisConfig.builder()
                .experimental(
                    ExperimentalConfig.builder()
                        .elementScreenshots(true)
                        .build()
                )
                .build()
        )
        .build();

    AccessibilityAuditor.levelAnalyze(config);