API Methods

AccessibilityAuditor.levelAnalyze

public static AnalysisResult levelAnalyze(AuditConfig config)

Runs a static accessibility analysis on the page currently loaded by config.driver and (when config.saveReport is true) persists a JSON report under config.analysisConfiguration.reportPath.

Properties

Returns

AnalysisResult — outcome is inferred from which fields are present:

AnalysisResult also exposes:

• getConfig() — the effective AnalysisConfig after defaults and environment overrides.
• getIssuesFound() — total number of issues across all rules in the report (returns 0 when there’s no report).

Usage

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

Important: Call levelAnalyze once the page has reached a stable success state. If you call it from a teardown hook (e.g. JUnit @AfterEach), guard it with a check on the test outcome — otherwise every retry will produce a report that has to be uploaded and processed, even when the test failed mid-execution.

Config

AuditConfig

Selenium-side audit workflow. Built with Lombok’s @Builder:

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

driver   WebDriver

The Selenium WebDriver instance to analyse. Required — levelAnalyze short-circuits to a failed result when driver is null.

auditTimeout   Duration

JavaScript execution timeout applied to the driver while the engine runs.

Default: Duration.ofMinutes(10).

analysisConfiguration   AnalysisConfig

Engine-level options (switchOff, reportPath, ignoreUrls, customTags, experimental).

Default: AnalysisConfig.builder().build() (zero-config).

saveReport   boolean

When true, writes the Level CI scope report under analysisConfiguration.reportPath (or the default reports folder when reportPath is unset).

Default: false
Environment variable: LEVEL_CI_SAVE_JSON_REPORT
Example value: true

strict   boolean

When true, levelAnalyze returns a failed result as soon as the engine reports any rule with findings. Use it to fail tests on accessibility regressions.

Default: false
Environment variable: LEVEL_CI_STRICT
Example value: true
See code example here.

AnalysisConfig

Mirror of the JS LaunchConfig. Built with Lombok’s @Builder:

AnalysisConfig.builder()
    .switchOff(false)
    .reportPath("./level-ci/level-ci-reports")
    .ignoreUrls(List.of("login", "settings/privacy"))
    .customTags(Set.of("alpha", "scenario-1"))
    .experimental(
        AnalysisConfig.Experimental.builder()
            .cssSelector(
                AnalysisConfig.CssSelector.builder()
                    .stableAttributes(List.of("data-testid"))
                    .build()
            )
            .build()
    )
    .build();

switchOff   Boolean

Disable the analysis globally or per specific run. When true, levelAnalyze skips the engine entirely.

Default: false
Environment variable: LEVEL_CI_SWITCH_OFF
Example value: true
See code example here.

reportPath   String

Folder path for analysis artifacts when AuditConfig.saveReport is true.

Default: "./level-ci-reports"
Environment variable: LEVEL_CI_REPORT_PATH
Example value: "my-custom-report-path"
See code example here.

ignoreUrls   List<String>

Skip analysis for URLs matching these regular expressions. Each entry is a regex source string (no leading/trailing /).

Example value: List.of("home", "settings/privacy", "articles/.*")
See code example here.

customTags   Set<String>

Add custom tags for scan identification. Tags appear next to issues on the dashboard so you can correlate them with the test scenario that produced them.

Example values: Set.of("alpha", "beta", "scenario-1")
See code example here.

Experimental selector configuration

Tune how Level CI builds CSS selectors for elements with accessibility issues. Configure via AnalysisConfig.Experimental and AnalysisConfig.CssSelector. When omitted, Level CI uses its default selector behavior.

stableAttributes   List<String>

Use stable attributes when element IDs or generated classes can change between runs. Level CI uses the selector to recognize the same issue over time. If the selector changes, an existing issue can appear resolved and return as a new issue.

Add an attribute whose value stays stable:

<button data-testid="submit-order">Submit order</button>

List attribute names in priority order. Level CI uses the first one that uniquely identifies the element.

Default: List.of("id")

Example values: List.of("data-testid"), List.of("data-testid", "data-qa")

AnalysisConfig.CssSelector.builder()
    .stableAttributes(List.of("data-testid", "data-qa"))
    .build();

includeClasses   Boolean

Set this to false when your application generates class names that change between builds. Level CI then omits all class names from generated selectors.

AnalysisConfig.CssSelector.builder()
    .includeClasses(false)
    .build();

ignoredClassPatterns   List<String>

Use this option when only some class names are unstable. Each value is a regular expression pattern for class names Level CI should omit. Write the pattern without leading or trailing /.

Example values: List.of("^sc-", "^css-")

AnalysisConfig.CssSelector.builder()
    .ignoredClassPatterns(List.of("^sc-", "^css-"))
    .build();

AnalysisResult

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

See the levelAnalyze Returns section above for the outcome-inference rules.

Examples

Set custom report path

Option 1: With the builder

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

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

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

Configure experimental CSS selectors

AnalysisConfig.builder()
    .experimental(
        AnalysisConfig.Experimental.builder()
            .cssSelector(
                AnalysisConfig.CssSelector.builder()
                    .stableAttributes(List.of("data-testid", "data-qa"))
                    .includeClasses(false)
                    .ignoredClassPatterns(List.of("^sc-", "^css-"))
                    .build()
            )
            .build()
    )
    .build();

Fail tests on findings (strict mode)

Option 1: With the builder

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

Option 2: Using an environment variable

LEVEL_CI_STRICT=true

When strict is on, levelAnalyze returns an AnalysisResult with both report and error populated as soon as any rule has findings, so a single assertThat(result.getError()).isNull() is enough to fail the test on regressions.