Selenium Java SDK

The Evinced Selenium Java SDK integrates with new or existing Selenium WebDriver tests to automatically detect accessibility issues. By adding a few lines of code to your Selenium WebDriver project, you can begin analyzing all the web pages and DOM changes to provide a dynamic view of how your site can become more accessible. As a result of the test, a rich and comprehensive report is generated to easily track issues to resolution.

Interested in seeing this in action? Contact us to get started!

Prerequisites

• Selenium version 3.141.59 or higher
• Java Version 11 or higher
• ChromeDriver or FirefoxDriver

Get started

Installation

To install Selenium Java SDK you will need either a file provided by Evinced Support or access to a remote repository that provides it. If you have neither, contact us to get started.

Installation with a locally provided file

You can install Selenium Java SDK using a standalone .jar distribution. In this case, you need to do the following:

1. Download the .jar file.
2. Unpack the provided selenium-sdk.zip to any desirable location.
3. Add the following dependencies entries pointing to selenium-sdk.jar
   1. Gradle:

      1 implementation files('/Users/<path-to-your-unpacked-folder>/selenium-sdk.jar')

   2. Maven:
      1. First, install the “all” jar into your local Maven repository by the following command:

         1mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=selenium-sdk-<version>.jar -DpomFile=selenium-sdk-<version>.pom

         Example:

         1mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=selenium-sdk-1.30.1.jar -DpomFile=selenium-sdk-1.30.1.pom

      2. Add the corresponding dependency into your pom.xml:

         1 <dependency>
         2     <groupId>com.evinced</groupId>
         3     <artifactId>selenium-sdk</artifactId>
         4     <version>1.30.1</version>
         5 </dependency>

Installation from a remote repository

Evinced Customers have the option of accessing Selenium Java SDK from a remote repository - the Evinced JFrog Artifactory - to keep their SDK version up-to-date and to share the SDK internally at their organization.

When access is enabled, Selenium Java SDK is available at
https://evinced.jfrog.io/artifactory/restricted-maven/com/evinced/selenium-sdk.

Authentication

To launch Selenium Java SDK, you need to have a Service ID and an API Key.

Please set credentials in environment variables and reference the environment variables in code.

1# Online mode
2export EVINCED_SERVICE_ID=<serviceId>
3export EVINCED_API_KEY=<apiKey>
4
5# Offline mode, when a JWT has been provided by Evinced
6export EVINCED_SERVICE_ID=<serviceId>
7export EVINCED_AUTH_TOKEN=<token>

Setting credentials, an example:

Add this code either in some static initializer section or into BeforeAll clause, so it should be called once before the first test.

1// Online mode
2EvincedSDK.setCredentials(System.getenv("EVINCED_SERVICE_ID"), System.getenv("EVINCED_API_KEY"));
3
4// OR
5
6// If provided a JWT by Evinced
7// Offline mode
8EvincedSDK.setOfflineCredentials(System.getenv("EVINCED_SERVICE_ID"), System.getenv("EVINCED_AUTH_TOKEN"));
9

Your First Test

SDK Initialization

To use Selenium Java SDK, you first need to authenticate. Please refer to Authentication for details.

Add the import statement to the beginning of your test file.

1import com.evinced.EvincedWebDriver;

Under the hood, the Evinced SDK utilizes several Selenium commands in order to get accessibility data. For this reason, we need to initialize EvincedWebDriver with the ChromeDriver instance in the following way:

1EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver());

1EvincedRemoteWebDriver driver = new EvincedRemoteWebDriver(new ChromeDriver());

Add Evinced Accessibility Checks (Single Run Mode)

This is a simple example of how to add an Evinced accessibility scan to a test. Please note the inline comments that give detail on each test step.

This is a simple JUnit example of how to add a single Evinced accessibility scan to a test. Please note the inline comments that give detail on each test step.

1@Test
2public void evAnalyzeSimpleTest() {
3    // Initialize EvincedWebDriver which wraps a ChromeDriver instance
4    EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver());
5
6    // Navigate to the site under test
7    driver.get("https://www.google.com");
8
9    // Run analysis and get the accessibility report
10    Report report = driver.evAnalyze();
11
12    // Assert that there are no accessibility issues
13    assertTrue(report.getIssues().size() == 0);
14}

Add Evinced Accessibility Checks (Continuous Mode)

This is an example of how to add a continuous Evinced accessibility scan to a test. Using the evStart() and evStop() methods, the Evinced engine will continually scan in the background capturing all DOM changes and page navigation as the test is executed. This will capture all accessibility issues as clicking on drop-downs or similar interactions reveals more of the page. The advantage of continuous mode is that no interaction with the actual test code is needed.

This is a simple JUnit example of how to add a continuous Evinced accessibility scan to a test. Using the evStart and evStop methods, the Evinced engine will continually scan in the background capturing all DOM changes as the test is executed. This will capture all accessibility issues as clicking on dropdowns or similar interactions reveals more of the page. The advantage of continuous mode is that no interaction with the actual test code is needed.

1import com.evinced.EvincedWebDriver;
2import com.evinced.EvincedSDK;
3import com.evinced.EvincedReporter;
4
5@BeforeClass
6public static void setUp() throws MalformedURLException, IOException {
7    EvincedSDK.setCredentials(System.getenv("EVINCED_SERVICE_ID"), System.getenv("EVINCED_API_KEY"));
8    driver = new EvincedWebDriver(new ChromeDriver());
9    // Start the Evinced engine scanning for accessibility issues
10    driver.evStart();
11    //... the rest of our setup code
12}
13
14@AfterClass
15public static void tearDown() throws MalformedURLException, IOException {
16    // Stop the Evinced engine
17    Report report = driver.evStop();
18    //Output the Evinced report in either JSON or HTML format
19    EvincedReporter.evSaveFile("test-results", report, EvincedReporter.FileFormat.HTML);
20    EvincedReporter.evSaveFile("test-results", report, EvincedReporter.FileFormat.JSON);
21    driver.quit();
22}
23
24@Test
25public void evAnalyzeSimpleTest() {
26    // Navigate to the site under test
27    driver.get("https://www.google.com");
28    // More test code...
29}

1ChromeOptions options = new ChromeOptions();
2options.setCapability("webSocketUrl", true);
3ChromeDriver chromeDriver = new ChromeDriver(options);
4EvincedWebDriver driver = new EvincedWebDriver(chromeDriver);

API

EvincedWebDriver(chromeDriver, configuration)

Prepares the Evinced object for use in the project.

The EvincedWebDriver constructor expects an instance of ChromeWebDriver. It is possible to pass an instance of a class that inherits or extends WebDriver.

1ChromeDriver chromeDriver = new ChromeDriver();
2EvincedWebDriver driver = new EvincedWebDriver(chromeDriver);

Refer to Configuration to see examples of initializing with options.

evAnalyze(options)

Scans the current page and returns a list of accessibility issues. This is the recommended method for static page analysis.

Note: This method is not supported if evStart() is already running.

1Report report = evincedWebDriver.evAnalyze();

Returns Report.

The returned report object contains a list of accessibility issues.

For more information regarding reports as well as the report object itself, please refer to our detailed Web Reports page.

evStart(options)

Continually watches for DOM mutations and page navigation, recording accessibility issues until the evStop() method is called. This method is recommended for dynamic page flows.

1evincedWebDriver.evStart();

Returns void.

evStop(options)

Stops the issue-gathering process started by evStart().

1evincedWebDriver.evStart();
2Report report = evincedWebDriver.evStop();

Returns Report.

The returned report object includes all accessibility issues detected between the evStart() and evStop() method calls. A single evStop() call still returns one deduplicated report even if evSwitchDriver rebound the session to a different WebDriver mid-session.

For more information regarding reports as well as the report object itself, please refer to our detailed Web Reports page.

evSwitchDriver(newDriver)

Rebinds an active continuous-analysis session to a new WebDriver instance, mid-session, without ending it — every accessibility issue captured before and after the swap is aggregated into the same session. Useful when the driver actually driving the test is created after evStart() (for example, a fresh driver per test step), or when a page reload recreates the driver.

1evincedWebDriver.evStart();
2
3evincedWebDriver = (EvincedWebDriver) evincedWebDriver.evSwitchDriver(new ChromeDriver());
4evincedWebDriver.get("https://www.example.com");
5
6Report report = evincedWebDriver.evStop(); // one aggregated report spanning every driver used

Important. Always reassign your driving variable to the value evSwitchDriver returns (a cast back to EvincedWebDriver is needed to keep calling evStart/evStop/evAnalyze on it) — interactions performed on the old driver instance after the swap are no longer captured.

1EvincedRemoteWebDriver session = new EvincedRemoteWebDriver(gridRemoteWebDriver);
2session.evStart();
3
4WebDriver driver = session.evSwitchDriver(new ChromeDriver()); // first step's driver
5driver.get("https://www.example.com");
6
7driver = session.evSwitchDriver(new ChromeDriver()); // next step's driver
8driver.get("https://www.example.com/next-page");
9
10Report report = session.evStop(); // one aggregated report across every driver used

Returns the WebDriver handle to keep driving the page through — reassign your driver variable to it and continue the test from there.

evSaveFile(destination, issues, format)

Saves issues in a file with the specified format and location. Supported formats are json, html, sarif, and csv. Find detailed information in the Web Reports page.

1Report report = evincedWebDriver.evStop();
2 -- or --
3Report report = evincedWebDriver.evAnalyze();
4
5// create a JSON file named jsonReport.json
6EvincedReporter.evSaveFile("jsonReport", report, EvincedReporter.FileFormat.JSON);
7
8// create an HTML file named htmlReport.html
9EvincedReporter.evSaveFile("htmlReport", report, EvincedReporter.FileFormat.HTML);
10
11// create an SARIF file named sarifReport.sarif.json
12EvincedReporter.evSaveFile("sarifReport", report, EvincedReporter.FileFormat.SARIF);
13
14// create an CSV file named csvReport.csv
15EvincedReporter.evSaveFile("csvReport", report, EvincedReporter.FileFormat.CSV);

Note: To generate a report in the specific format (but JSON) we are running some code on the browser side. If you are using custom WebDriver or there are some environmental issues with starting browser or driver during report generation, please use the command where you can provide the WebDriver object.

1WebDriver driver = yourCustomMethodToInstaantiateDriver();
2// Generates aggregated report using custom WebDriver object
3EvincedReporter.evSaveFile("htmlReport", EvincedReporter.FileFormat.HTML, driver);
4driver.quit();

FileFormat

Defines the file type of the report. Options are JSON, HTML, SARIF and CSV.

Returns Path.

Aggregated Report

The aggregated report feature allows you to have a general aggregated report for the whole run (not only for one test or suite). This report will contain all the issues found by the tests where evStart() and evStop() commands were called. It is still possible to use the evSaveFile() command in any place of your code along with this Aggregated Report feature.

1Path htmlAggregatedReport = EvincedReporter.evSaveFile("evinced-html-report", EvincedReporter.FileFormat.HTML);

Configuration

The same configuration options can be used when initializing the Evinced object using EvincedConfiguration() and when calling the evStart() and evAnalyze() methods but with a bit different consequences. Providing options when initializing defines a global configuration for all calls of evAnalyze() and evStart(), while providing options to either of those methods affect only the test in which they are called. Some SDKs also let you define configuration outside your code, in a config file that is picked up automatically at startup.

Options provided in either evAnalyze() or evStart() override those set in Evinced engine initialization.

Engines Configuration

Evinced uses two separate engines when scanning for accessibility issues, one is the aXe engine and the other is the Evinced engine. By default, Evinced disables the aXe Needs Review and Best Practices issues based on customer request and due to the fact they are mostly false positives. Please note this setting when comparing issue counts directly. See an example of how to enable Needs Review and Best practices issues in the Toggles section.

Configuration File

Place a configuration file at the root of your working directory to set options without touching code. The SDK looks for one of the following, in this order, and uses the first one it finds — file formats are never merged together:

1. evConfig.yaml
2. evConfig.yml
3. evConfig.json

1scan:
2  iframes: true
3logging:
4  enabled: true
5  preset: standard
6platform:
7  upload:
8    enabled: true

1{
2  "scan": {
3    "iframes": true
4  },
5  "logging": {
6    "enabled": true,
7    "preset": "standard"
8  },
9  "platform": {
10    "upload": {
11      "enabled": true
12    }
13  }
14}

How settings are combined

Configuration can come from several places, and each one can override the ones before it:

1. Built-in defaults — what the SDK ships with.
2. Environment variables — a small set of process-wide switches, listed below.
3. The evConfig file — settings for the whole project, discovered automatically as described above.
4. Your code, when you create the SDK instance — using EvincedOptions, or the deprecated configuration object.
5. Your code, on an individual call — options passed directly to a single evStart() or evAnalyze() call, which apply only to that call.

Later steps win over earlier ones for the same setting. A setting your code never touches keeps falling through to whatever the evConfig file, an environment variable, or the built-in default provided.

Environment variables

A handful of environment variables participate in this same layering, primarily useful in CI environments where you don't want to check in a config file:

An environment variable that is left unset never overrides a lower-priority default — it only takes effect when you explicitly set it.

Configuration Object

Global configuration for Selenium Java SDK can be defined in three ways, all sharing the same nested structure: an evConfig file at the root of your project (see Configuration File), the modern EvincedOptions builder passed to EvincedWebDriver(chromeDriver, configuration), or the deprecated configuration object, which keeps working unchanged. Options passed directly to a single evStart() or evAnalyze() call override all three for that call only.

The full shape of the configuration, shown here as a type definition for reference:

1type EvConfig = {
2  switchOn?: boolean;
3  mock?: boolean;
4  scan?: {
5    rootSelector?: string;
6    iframes?: boolean;
7    iframeDomains?: string[];
8    withPasses?: boolean;
9    screenshots?: {
10      enabled?: boolean;
11      mode?: 'browser' | 'sdk';
12      scale?: number;
13      quality?: number;
14      timeout?: number;
15    };
16    dedupe?: {
17      local?: boolean;
18    };
19    settle?: {
20      enabled?: boolean;
21      throttle?: { enabled?: boolean; delay?: number };
22    };
23    alerts?: { expected?: boolean; timeout?: number };
24    navigation?: {
25      spaTracking?: boolean;
26      lossRecovery?: boolean;
27      processingTimeout?: number;
28      iframeInjectionWaitTime?: number;
29      finishInterval?: number;
30    };
31  };
32  analysis?: {
33    [key: string]: unknown;
34  };
35  logging?: {
36    enabled?: boolean;
37    preset?: 'errors' | 'standard' | 'diagnostic';
38    level?: 'error' | 'warn' | 'info' | 'debug' | 'trace';
39    outputDir?: string;
40    maxEntryLength?: number;
41    consoleLogger?: boolean;
42    systemInfo?: boolean;
43    configurationFile?: string;
44    channels?: {
45      sdk?: boolean;
46      engine?: boolean;
47      browserConsole?: boolean;
48      httpClient?: boolean;
49      performance?: boolean;
50      scanInsights?: boolean;
51    };
52  };
53  network?: {
54    enabled?: boolean;
55    maxRetries?: number;
56    retryDelay?: number;
57    idle?: { enabled?: boolean; timeout?: number; maxWait?: number };
58  };
59  platform?: {
60    upload?: { enabled?: boolean; autoUpload?: boolean };
61  };
62  telemetry?: {
63    enabled?: boolean;
64    channels?: { sdk?: boolean; engine?: boolean };
65  };
66  performance?: {
67    scriptBatching?: boolean;
68    bundleCache?: boolean;
69  };
70};

1switchOn: true
2scan:
3  rootSelector: '#main'
4  iframes: true
5  screenshots:
6    enabled: true
7logging:
8  enabled: true
9  level: debug

1{
2  "switchOn": true,
3  "scan": {
4    "rootSelector": "#main",
5    "iframes": true,
6    "screenshots": {
7      "enabled": true
8    }
9  },
10  "logging": {
11    "enabled": true,
12    "level": "debug"
13  }
14}

1EvincedOptions options = EvincedOptions.create()
2    .scan(s -> s
3        .rootSelector("#main")
4        .iframes(true)
5        .screenshots(sc -> sc.enabled(true)))
6    .logging(l -> l.enabled(true).level("debug"));
7
8EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1driver.evAnalyze(EvincedOptions.create().scan(s -> s.rootSelector(".block-dropdown")));

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setRootSelector("#main");
3configuration.setIncludeIframes(true);
4configuration.setEnableScreenshots(true);
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setRootSelector(".block-dropdown");
3driver.evAnalyze(configuration);

Root Selector

Sets a CSS selector to limit the Evinced Engine to scan only the selected element and its children. Must be a valid CSS selector. If not set, the Evinced Engine will scan the entire document.

Default: no value

1scan:
2  rootSelector: '.some-selector'

1{
2  "scan": {
3    "rootSelector": ".some-selector"
4  }
5}

1EvincedOptions options = EvincedOptions.create().scan(s -> s.rootSelector(".some-selector"));
2
3EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setRootSelector(".some-selector");
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Axe Configuration

Configures Axe open-source accessibility toolkit, which the Evinced engine includes with its own, more extensive accessibility detection. For full Axe config options, see Axe Core API.

1analysis:
2  AXE_CONFIG:
3    rules:
4      html-has-lang:
5        enabled: false

1{
2  "analysis": {
3    "AXE_CONFIG": {
4      "rules": {
5        "html-has-lang": { "enabled": false }
6      }
7    }
8  }
9}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a.rule("html-has-lang", false));
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1Map<String, Object> rules = new HashMap<>();
2rules.put("html-has-lang", Collections.singletonMap("enabled", false));
3
4EvincedOptions options = EvincedOptions.create()
5    .analysis(a -> a.raw("AXE_CONFIG", Collections.singletonMap("rules", rules)));
6
7EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2AxeConfiguration axeConfig = new AxeConfiguration();
3
4// Axe's own syntax to disable the html-has-lang validation
5axeConfig.setRules(Collections.singletonMap("html-has-lang", new AxeRuleConfiguration(false)));
6configuration.setAxeConfig(axeConfig);
7
8EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Engine Logging

Set level of messages the Evinced engine will print to the console. Valid levels are "debug", "info", "warn" and "error".

Default: "error"

Beyond the engine's own log level, the logging.* section controls the SDK's logging as a whole: whether logging is on at all, which channels are captured (the SDK's own messages, the engine's, the browser console, the HTTP client, performance timings, and scan insights), where logs are written, and how verbose they are. A preset is a shortcut that sets several of these at once — errors, standard, or diagnostic (which additionally turns on the engine channel).

1logging:
2  enabled: true
3  preset: diagnostic
4  level: debug
5  channels:
6    engine: true

1{
2  "logging": {
3    "enabled": true,
4    "preset": "diagnostic",
5    "level": "debug",
6    "channels": {
7      "engine": true
8    }
9  }
10}

1EvincedOptions options = EvincedOptions.create()
2    .logging(l -> l
3        .enabled(true)
4        .level("debug")
5        .engineChannel(true));
6
7EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1LoggingConfiguration loggingConfig = LoggingConfiguration.builder()
2    .loggingEnabled(true)
3    .loggingLevel("DEBUG")
4    .engineLoggingEnabled(true)
5    .build();
6
7EvincedConfiguration configuration = new EvincedConfiguration();
8configuration.setLoggingConfiguration(loggingConfig);
9
10EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Valid values for level/loggingLevel are "error", "warn", "info", "debug", and "trace" (case-insensitive).

Reports Screenshots

When true, the Evinced SDK will include screenshots in its reports that highlight elements with accessibility issues.

Default: false.

Note: Enabling screenshots may affect test run performance.

Screenshots have two independent settings: whether they're captured at all (scan.screenshots.enabled), and — once enabled — who captures them (scan.screenshots.mode).

1scan:
2  screenshots:
3    enabled: true
4    mode: sdk

1{
2  "scan": {
3    "screenshots": {
4      "enabled": true,
5      "mode": "sdk"
6    }
7  }
8}

1import com.evinced.common.dto.config.ScreenshotMode;
2
3EvincedOptions options = EvincedOptions.create()
4    .scan(s -> s.screenshots(sc -> sc.enabled(true).mode(ScreenshotMode.SDK)));
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedOptions options = EvincedOptions.create()
2    .scan(s -> s.screenshots(sc -> sc
3        .enabled(true)
4        .mode(ScreenshotMode.SDK)
5        .quality(90)   // JPEG quality 1-100 (default 85)
6        .timeout(8000) // per-capture timeout in ms (default 5000)
7    ));

1import com.evinced.common.dto.config.ScreenshotMode;
2
3EvincedConfiguration configuration = new EvincedConfiguration();
4configuration.setScreenshotMode(ScreenshotMode.SDK);
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Toggles

Enables experimental features. Feature names and values may vary from release to release.

Example:

1analysis:
2  TOGGLES:
3    USE_AXE_NEEDS_REVIEW: true
4    USE_AXE_BEST_PRACTICES: true

1{
2  "analysis": {
3    "TOGGLES": {
4      "USE_AXE_NEEDS_REVIEW": true,
5      "USE_AXE_BEST_PRACTICES": true
6    }
7  }
8}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a
3        .toggle("USE_AXE_NEEDS_REVIEW", true)
4        .toggle("USE_AXE_BEST_PRACTICES", true));
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.addExperimentalFlag("USE_AXE_NEEDS_REVIEW", true);
3configuration.addExperimentalFlag("USE_AXE_BEST_PRACTICES", true);
4
5EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

1Map<String, Boolean> toggles = new HashMap<>();
2toggles.put("USE_AXE_NEEDS_REVIEW", true);
3toggles.put("USE_AXE_BEST_PRACTICES", true);
4
5EvincedConfiguration configuration = new EvincedConfiguration();
6configuration.setExperimentalFlags(toggles);

Skip Validations

Sets validation types to be skipped for specified URL pattern and CSS selector. Issue type IDs can be found by inspecting a JSON report as described in Web Reports.

Default: no validations skipped.

1analysis:
2  SKIP_VALIDATIONS:
3    - selector: 'test.1--selector'
4      urlRegex: 'http://url.to.skip/path1'
5      validationTypes: ['NO_DESCRIPTIVE_TEXT', 'NOT_FOCUSABLE']
6    - selector: 'test.2--selector'
7      urlRegex: 'http://url.to.skip/path2'
8      validationTypes: ['NOT_FOCUSABLE', 'ONE_MORE_TYPE_TO_EXCLUDE', 'NO_DESCRIPTIVE_TEXT']

1{
2  "analysis": {
3    "SKIP_VALIDATIONS": [
4      {
5        "selector": "test.1--selector",
6        "urlRegex": "http://url.to.skip/path1",
7        "validationTypes": ["NO_DESCRIPTIVE_TEXT", "NOT_FOCUSABLE"]
8      },
9      {
10        "selector": "test.2--selector",
11        "urlRegex": "http://url.to.skip/path2",
12        "validationTypes": ["NOT_FOCUSABLE", "ONE_MORE_TYPE_TO_EXCLUDE", "NO_DESCRIPTIVE_TEXT"]
13      }
14    ]
15  }
16}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a
3        .skipValidation("test.1--selector", "http://url.to.skip/path1",
4            "NO_DESCRIPTIVE_TEXT", "NOT_FOCUSABLE")
5        .skipValidation("test.2--selector", "http://url.to.skip/path2",
6            "NOT_FOCUSABLE", "ONE_MORE_TYPE_TO_EXCLUDE", "NO_DESCRIPTIVE_TEXT"));
7
8EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration globalConfig = new EvincedConfiguration();
2
3globalConfig.skipValidation("test.1--selector", "http://url.to.skip/path1",
4        "NO_DESCRIPTIVE_TEXT", "NOT_FOCUSABLE");
5globalConfig.skipValidation("test.2--selector", "http://url.to.skip/path2",
6        "NOT_FOCUSABLE", "ONE_MORE_TYPE_TO_EXCLUDE", "NO_DESCRIPTIVE_TEXT");
7
8EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), globalConfig);

Skipping every validation type

To suppress all validation types for a selector, pass the wildcard * in place of a list of type names.

The wildcard must be the only value. Listed alongside concrete type names it is not treated as a wildcard — the wildcard entry is ignored and only the concrete types given with it are skipped.

1analysis:
2  SKIP_VALIDATIONS:
3    - selector: '#parent, #parent *'
4      urlRegex: 'http://url.to.skip/path1'
5      validationTypes: '*'

1{
2  "analysis": {
3    "SKIP_VALIDATIONS": [
4      {
5        "selector": "#parent, #parent *",
6        "urlRegex": "http://url.to.skip/path1",
7        "validationTypes": "*"
8      }
9    ]
10  }
11}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a.skipAllValidations("#parent, #parent *", "http://url.to.skip/path1"));
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration globalConfig = new EvincedConfiguration();
2
3// Skip every validation type on #parent and everything inside it
4globalConfig.skipValidation("#parent, #parent *", "http://url.to.skip/path1", "*");
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), globalConfig);

A selector matches elements, not subtrees

Skip rules are evaluated against each reported element on its own, so a selector suppresses issues only on the elements it matches — not on anything nested inside them. To cover a container and its contents, list both the container and its descendants:

1#parent, #parent *

#parent alone suppresses only issues reported on #parent itself.

Recording Service

This setting controls how frequently event-triggered functions are executed, helping to optimize performance and responsiveness. The option does not enable or disable the event-handling service itself but determines how frequently events are processed based on the selected mode.

Available modes:

• debounce - Delays execution until a set time has passed since the last event. Useful for actions triggered by continuous input, such as typing in a search box, to avoid excessive function calls.
• throttle - Ensures execution at fixed intervals, regardless of event frequency. Ideal for scenarios like handling window resize events or scroll tracking, where limiting execution prevents performance degradation.

Default: Functions execute as triggering events occur.

An example of how to modify settings:

1analysis:
2  RECORDING_SERVICE:
3    ENABLE_DEBOUNCE_NEW_SELECTORS: true
4    DEBOUNCE_NEW_SELECTORS_MS: 1000
5    DELAY_MODE: throttle

1{
2  "analysis": {
3    "RECORDING_SERVICE": {
4      "ENABLE_DEBOUNCE_NEW_SELECTORS": true,
5      "DEBOUNCE_NEW_SELECTORS_MS": 1000,
6      "DELAY_MODE": "throttle"
7    }
8  }
9}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a
3        .raw("RECORDING_SERVICE.ENABLE_DEBOUNCE_NEW_SELECTORS", true)
4        .raw("RECORDING_SERVICE.DEBOUNCE_NEW_SELECTORS_MS", 1000)
5        .raw("RECORDING_SERVICE.DELAY_MODE", "throttle"));
6
7EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1RecordingServiceConfiguration recordingConfiguration = new RecordingServiceConfiguration();
2recordingConfiguration.setEnableDebounceNewSelectors(true);
3recordingConfiguration.setDebounceNewSelectorsMs(1000);
4recordingConfiguration.setDelayMode("throttle");
5
6EvincedConfiguration configuration = new EvincedConfiguration();
7configuration.setRecordingServiceConfiguration(recordingConfiguration);
8
9EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Performance

Settings under performance that reduce the SDK's per-interaction and per-test overhead.

Script Batching

Groups the small scripts the SDK injects into the page into fewer round-trips to the browser, reducing per-interaction overhead.

Default: true.

1performance:
2  scriptBatching: false

1{
2  "performance": {
3    "scriptBatching": false
4  }
5}

1EvincedOptions options = EvincedOptions.create()
2    .performance(p -> p.scriptBatching(false));
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setEnableScriptBatching(false);
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Script batching is enabled by default. Disable it only if you're diagnosing an issue and want to isolate individual script executions.

Bundle Cache

Caches the Evinced engine bundle across test runs instead of fetching and re-initializing it every time, reducing per-test startup overhead.

Default: false.

1performance:
2  bundleCache: true

1{
2  "performance": {
3    "bundleCache": true
4  }
5}

1EvincedOptions options = EvincedOptions.create()
2    .performance(p -> p.bundleCache(true));
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setBundleCacheEnabled(true);
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Turn this on for test suites that create many short-lived driver instances against the same application, so repeat test runs skip re-fetching and re-initializing the engine bundle.

Settled Analysis

This setting controls accessibility analysis after user interactions like clicks and actions. It ensures that accessibility issues in dynamic content that appears after user actions are properly captured and reported.

Why you need this configuration:

Settled analysis automatically captures accessibility issues that appear after user interactions such as clicks, form submissions, or other dynamic changes. When users interact with your application, new content may be revealed (dropdowns, modals, dynamically loaded sections) that contains accessibility violations. Without settled analysis, these issues would only be detected during the final evStop() call, potentially missing critical accessibility problems that occur during the user journey.

Key benefits:

• Complete coverage: Captures accessibility issues in dynamically revealed content
• Real-time detection: Issues are found immediately after user interactions
• Better debugging: Issues are associated with specific user actions that triggered them
• Comprehensive reporting: Provides a complete picture of accessibility state throughout the test

When to disable: You may want to disable settled analysis in performance-critical test scenarios where the additional analysis calls impact test execution time, or when testing static pages with no dynamic content.

Throttling mechanism:

The throttling feature prevents excessive analysis calls when users perform rapid interactions (like multiple quick clicks or form field changes). Without throttling, each user action could trigger a separate analysis, leading to:

• Performance degradation: Multiple concurrent analysis calls can slow down test execution
• Resource consumption: Excessive CPU and memory usage from frequent DOM analysis

Why you need throttling configuration:

• Optimize performance: Reduce the frequency of analysis calls during rapid user interactions
• Prevent resource exhaustion: Control CPU and memory usage in complex test scenarios
• Maintain test stability: Avoid conflicts between multiple simultaneous analysis operations
• Customize timing: Adjust delay based on your application's response characteristics

Default:

• Settled analysis: Enabled.
• Throttling: Disabled (immediate execution).
• Throttle delay: 200ms when enabled.

An example of how to modify settings:

1scan:
2  settle:
3    enabled: true
4    throttle:
5      enabled: true
6      delay: 500

1{
2  "scan": {
3    "settle": {
4      "enabled": true,
5      "throttle": {
6        "enabled": true,
7        "delay": 500
8      }
9    }
10  }
11}

1EvincedOptions options = EvincedOptions.create()
2    .scan(s -> s.settle(st -> st
3        .enabled(true)
4        .throttle(t -> t.enabled(true).delay(500))));
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1// Configure throttling: 500ms delay, throttling enabled
2ThrottleOptions throttleOptions = new ThrottleOptions(500, true);
3
4SettledAnalysisConfiguration settledConfig = new SettledAnalysisConfiguration();
5settledConfig.setDisabled(false);            // Enable settled analysis after user interactions
6settledConfig.setThrottleConfig(throttleOptions);  // Apply throttling to prevent excessive analysis calls
7
8EvincedConfiguration configuration = new EvincedConfiguration();
9configuration.setSettledAnalysisConfiguration(settledConfig);
10
11EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Knowledge-Base Link Overrides

Sets customized knowledge-base links in the reports. The links are displayed in the reports “Issue Type” column, as shown in the following screenshot:

The knowledge base link can be overridden for every issue type ID. Issue type IDs can be found by inspecting a JSON report as described in Web Reports. For example, the issue with name Interactable Role has ID WRONG_SEMANTIC_ROLE.

Knowledge-base links can be overridden per Evinced issue type ID or per axe-core rule ID. Both are now also configurable via evConfig.yaml/.json and EvincedOptions, in addition to the existing EvincedConfiguration setters.

1analysis:
2  ISSUE_CONTENT_PER_TYPE:
3    WRONG_SEMANTIC_ROLE:
4      knowledgeBaseLink: 'https://kb.example.com/wrong-semantic-role'
5  AXE_ISSUE_CONTENT_PER_TYPE:
6    color-contrast:
7      knowledgeBaseLink: 'https://kb.example.com/color-contrast'

1{
2  "analysis": {
3    "ISSUE_CONTENT_PER_TYPE": {
4      "WRONG_SEMANTIC_ROLE": {
5        "knowledgeBaseLink": "https://kb.example.com/wrong-semantic-role"
6      }
7    },
8    "AXE_ISSUE_CONTENT_PER_TYPE": {
9      "color-contrast": {
10        "knowledgeBaseLink": "https://kb.example.com/color-contrast"
11      }
12    }
13  }
14}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a
3        .knowledgeBaseLink("WRONG_SEMANTIC_ROLE", "https://kb.example.com/wrong-semantic-role")
4        .axeKnowledgeBaseLink("color-contrast", "https://kb.example.com/color-contrast"));
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration
3    .setKnowledgeBaseLink("WRONG_SEMANTIC_ROLE", "https://kb.example.com/wrong-semantic-role")
4    .setAxeKnowledgeBaseLink("color-contrast", "https://kb.example.com/color-contrast");
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

knowledgeBaseLink(issueType, url) overrides the link for an Evinced-engine issue type ID, the same IDs described in Knowledge-Base Link Overrides above. axeKnowledgeBaseLink(ruleId, url) overrides the link for an axe-core rule ID directly (for example color-contrast).

Shadow DOM Support

Shadow DOM is now supported by default. No additional configuration is needed.

If using an earlier release, configure shadow DOM support as follows: There is no dedicated scan.shadowDom setting — shadow DOM support is always on. To turn it off (matching the pre-default-support behavior), use the same engine toggle mechanism as Toggles:

1analysis:
2  TOGGLES:
3    SUPPORT_SHADOW_DOM: false

1{
2  "analysis": {
3    "TOGGLES": {
4      "SUPPORT_SHADOW_DOM": false
5    }
6  }
7}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a.toggle("SUPPORT_SHADOW_DOM", false));
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setIncludeShadowDOM(false);
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

IFrames Support

When true, accessibility analysis includes iframe that exist inside the page.

Default: true.

1scan:
2  iframes: false

1{
2  "scan": {
3    "iframes": false
4  }
5}

1EvincedOptions options = EvincedOptions.create().scan(s -> s.iframes(false));
2
3EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setIncludeIframes(false);
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Include Hidden IFrames Domain

Configures which hidden iframe domains are included in accessibility analysis. By default, hidden iframes are excluded for performance and security reasons.

This setting allows you to specify a list of domains to analyze even when the iframe is hidden.

1scan:
2  iframes: true
3  iframeDomains:
4    - example.com
5    - test.com

1{
2  "scan": {
3    "iframes": true,
4    "iframeDomains": ["example.com", "test.com"]
5  }
6}

1EvincedOptions options = EvincedOptions.create()
2    .scan(s -> s
3        .iframes(true)
4        .iframeDomains(Arrays.asList("example.com", "test.com")));
5
6EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setIncludeIframes(true);
3configuration.setIncludeHiddenIframeDomains(Arrays.asList("example.com", "test.com"));
4
5EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);

Passed Validations

By default, the Evinced SDK only reports accessibility issues that have failed validation. However, you can also configure the SDK to include passed validations in your reports. Passed validations represent accessibility checks that were successfully completed without any issues found.

Why include passed validations?

Including passed validations in your reports provides several benefits:

• Comprehensive Coverage: Get a complete picture of all accessibility checks performed, not just the failures
• Compliance Documentation: Demonstrate which accessibility standards your application successfully meets
• Trend Analysis: Track improvements over time by monitoring both failed and passed validation counts
• Quality Assurance: Verify that accessibility checks are running as expected across your entire application
• Regulatory Reporting: Provide evidence of accessibility testing coverage for compliance audits

Report Structure

When passed validations are enabled, your reports will include both:

• failedValidations: Array of accessibility issues that need to be fixed
• passedValidations: Array of accessibility checks that passed successfully

Default: false (passed validations are not included)

1scan:
2  withPasses: true

1{
2  "scan": {
3    "withPasses": true
4  }
5}

1EvincedOptions options = EvincedOptions.create().scan(s -> s.withPasses(true));
2
3EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);
4Report report = driver.evAnalyze();
5
6List<Issue> failedValidations = report.getFailedValidations();
7List<Issue> passedValidations = report.getPassedValidations();

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setIncludePassedValidations(true);
3
4EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), configuration);
5Report report = driver.evAnalyze();
6
7List<Issue> failedValidations = report.getFailedValidations();
8List<Issue> passedValidations = report.getPassedValidations();

Passed validations are included only in JSON format reports saved via evSaveFile(destination, issues, format).

Proxy

Configures proxy server access settings. Needed to enable outbound communication to the Evinced Platform through a proxy server.

1...
2String proxyString = "ip:port";
3//Or if you have credentials
4String proxyString = "user:password@ip:port";
5Proxy proxy = new Proxy();
6proxy.setHttpProxy(proxyString)
7        .setSslProxy(proxyString);
8ChromeOptions chromeOptions = new ChromeOptions();
9chromeOptions.setProxy(proxy);
10EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(chromeOptions));
11...

SPA Navigation Tracking

Automatically detects client-side navigation in Single Page Applications (SPAs) and restarts accessibility analysis to capture issues in dynamically loaded content.

Why you need this feature:

Modern web applications built with frameworks like React, Angular, or Vue.js use client-side routing where content changes without full page reloads. Without SPA navigation tracking, accessibility issues in these dynamically loaded views would be missed.

What it monitors:

• URL changes via browser history API (pushState, replaceState)
• Browser back/forward navigation (popstate)
• Hash-based routing changes (#/page)

Default: false (disabled)

Note: This feature works with Selenium BiDi for enhanced performance. Enable BiDi to activate this functionality.

1scan:
2  navigation:
3    spaTracking: true

1{
2  "scan": {
3    "navigation": {
4      "spaTracking": true
5    }
6  }
7}

1EvincedOptions options = EvincedOptions.create()
2    .navigation(n -> n.spaTracking(true))
3    .scan(s -> s.iframes(true));
4
5ChromeOptions chromeOptions = new ChromeOptions();
6chromeOptions.setCapability("webSocketUrl", true); // enables Selenium BiDi
7ChromeDriver chromeDriver = new ChromeDriver(chromeOptions);
8
9EvincedWebDriver driver = new EvincedWebDriver(chromeDriver, options);
10driver.get("https://your-spa-app.com");
11driver.evStart();
12
13// ...interact with your application; the SDK tracks SPA navigation automatically...
14
15Report report = driver.evStop();

1EvincedConfiguration configuration = new EvincedConfiguration();
2configuration.setEnableSPANavigationTracking(true);
3configuration.setIncludeIframes(true);
4
5ChromeOptions chromeOptions = new ChromeOptions();
6chromeOptions.setCapability("webSocketUrl", true); // enables Selenium BiDi
7ChromeDriver chromeDriver = new ChromeDriver(chromeOptions);
8
9EvincedWebDriver driver = new EvincedWebDriver(chromeDriver, configuration);
10driver.get("https://your-spa-app.com");
11driver.evStart(configuration);
12
13Report report = driver.evStop();

This feature works with Selenium BiDi for enhanced performance — enable BiDi on your driver (as shown above) to activate it, and combine it with Continuous Mode (evStart()/evStop()) to capture every navigation event.

Network Idle Detection

The networkIdle configuration enables the SDK to wait for all network requests to complete before running accessibility analysis. This is particularly useful for modern web applications that load content dynamically after the initial page load.

Why use Network Idle Detection?

When testing modern web applications, accessibility analysis may run before all content has loaded, resulting in:

• Incomplete results: Dynamic content not yet rendered won't be analyzed
• False negatives: Accessibility issues in delayed content won't be detected
• Inconsistent results: Analysis timing may vary between test runs

Network idle detection solves this by ensuring all network activity has settled before analysis begins.

Configuration Options:

Network idle detection can be configured globally during SDK initialization or per-command for granular control.

1network:
2  idle:
3    enabled: true
4    timeout: 300
5    maxWait: 7500

1{
2  "network": {
3    "idle": {
4      "enabled": true,
5      "timeout": 300,
6      "maxWait": 7500
7    }
8  }
9}

1EvincedOptions options = EvincedOptions.create()
2    .network(n -> n.idle(i -> i
3        .enabled(true)
4        .timeout(300)
5        .maxWait(7500)));
6
7EvincedWebDriver driver = new EvincedWebDriver(new ChromeDriver(), options);

1driver.evStart(EvincedOptions.create().network(n -> n.idle(i -> i.enabled(true).maxWait(10000))));