Playwright Java SDK

The Evinced Playwright Java SDK integrates with new or existing Playwright tests to automatically detect accessibility issues. By adding a few lines of code to your Playwright 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

• Playwright version 1.29 or higher

Get started

Installation

To install Playwright 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 Playwright 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 java-playwright-sdk.zip to any desirable location.
3. Add the following dependencies entries pointing to java-playwright-sdk-version.jar
   1. Gradle:

      1 implementation files('/Users/<path-to-your-unpacked-folder>/java-playwright-sdk-<version>.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 \
         2    -Dfile=java-playwright-sdk-<version>.jar \
         3    -DpomFile=java-playwright-sdk-<version>.pom

         Example:

         1mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file \
         2    -Dfile=java-playwright-sdk-1.6.1.jar \
         3    -DpomFile=java-playwright-sdk-1.6.1.pom

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

         1 <dependency>
         2     <groupId>com.evinced</groupId>
         3     <artifactId>java-playwright-sdk</artifactId>
         4     <version>1.6.1</version>
         5 </dependency>

Installation from a remote repository

Evinced Customers have the option of accessing Playwright 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, Playwright Java SDK is available at
https://evinced.jfrog.io/artifactory/restricted-maven/com/evinced/java-playwright-sdk.

Authentication

To launch Playwright 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:

1using Evinced.SDK;
2
3// Offline mode
4EvincedSDK.SetOfflineCredentials(Environment.GetEnvironmentVariable("EVINCED_SERVICE_ID"), Environment.GetEnvironmentVariable("EVINCED_AUTH_TOKEN"));
5
6// Online mode
7EvincedSDK.SetCredentials(Environment.GetEnvironmentVariable("EVINCED_SERVICE_ID"), Environment.GetEnvironmentVariable("EVINCED_API_KEY"));

Your First Test

SDK Initialization

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

The only command you need to add is to wrap the existing WebDriver object.

1Playwright playwright = Playwright.create();
2Browser browser = playwright.chromium().launch();
3EvPage page = EvPageFactory.create(browser.newPage());

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.

1@Test
2public void evAnalyzeTest() {
3    Playwright playwright = Playwright.create();
4    Browser browser = playwright.chromium().launch();
5    EvPage page = EvPageFactory.create(browser.newPage());
6
7    try{
8        page.navigate("https://demo.evinced.com");
9        Report report = page.evAnalyze();
10        List<Issue> issues = report.getIssues();
11        assertEquals(6, issues.size());
12    } finally {
13        playwright.close();
14    }
15}

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.

1@Test
2public void evAnalyzeTest() {
3    Playwright playwright = Playwright.create();
4    Browser browser = playwright.chromium().launch();
5    EvPage page = EvPageFactory.create(browser.mewPage());
6
7    try{
8        page.navigate("https://demo.evinced.com");
9        page.evStart();
10
11        // More test code to interact with the page
12
13        Report report = page.evStop();
14        List<Issue> issues = report.getIssues();
15        assertEquals(6, issues.size());
16    } finally {
17        playwright.close();
18    }
19}

API

EvPageFactory.create()

Prepares the Evinced object for use in the project.

1EvPage page = EvPageFactory.create(browser.newPage());

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.

1EvPage page = EvPageFactory.create(browser.newPage());
2Report report = page.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.

1EvPage page = EvPageFactory.create(browser.newPage());
2page.evStart();

Returns void.

evStop(options)

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

1EvPage page = EvPageFactory.create(browser.newPage());
2page.evStart();
3Report report = page.evStop();

Returns Report.

The returned report object includes all accessibility issues detected between the evStart() and evStop() method calls.

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

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 = page.evStop();
2// OR
3Report report = page.evAnalyze();
4
5// create a JSON file named jsonReport.json
6EvincedSDK.evSaveFile("jsonReport", report, FileFormat.JSON);
7
8// create an HTML file named htmlReport.html
9EvincedSDK.evSaveFile("htmlReport", report, FileFormat.HTML);
10
11// create an SARIF file named sarifReport.html
12EvincedSDK.evSaveFile("sarifReport", report, FileFormat.SARIF);
13
14// create an CSV file named csvReport.csv
15EvincedSDK.evSaveFile("csvReport", report, FileFormat.CSV);

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 = EvincedSDK.evSaveFile("evinced-html-report", FileFormat.HTML);

Configuration

The same configuration options can be used when initializing the Evinced object using Global.config 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 Playwright 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 EvPageFactory.create(), or the deprecated Global.config 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  };
24  analysis?: {
25    [key: string]: unknown;
26  };
27  logging?: {
28    enabled?: boolean;
29    preset?: 'errors' | 'standard' | 'diagnostic';
30    level?: 'error' | 'warn' | 'info' | 'debug' | 'trace';
31    outputDir?: string;
32    maxEntryLength?: number;
33    consoleLogger?: boolean;
34    systemInfo?: boolean;
35    configurationFile?: string;
36    channels?: {
37      sdk?: boolean;
38      engine?: boolean;
39      browserConsole?: boolean;
40      httpClient?: boolean;
41      performance?: boolean;
42      scanInsights?: boolean;
43    };
44  };
45  network?: {
46    enabled?: boolean;
47    maxRetries?: number;
48    retryDelay?: number;
49    idle?: { enabled?: boolean; timeout?: number; maxWait?: number };
50  };
51  platform?: {
52    upload?: { enabled?: boolean; autoUpload?: boolean };
53  };
54  telemetry?: {
55    enabled?: boolean;
56    channels?: { sdk?: boolean; engine?: boolean };
57  };
58};

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
8EvPage evPage = EvPageFactory.create(page, options);

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

1EvConfig configuration = new EvConfig();
2configuration.setRootSelector("#main");
3configuration.setIFramesIncluded(true);
4configuration.setEnableScreenshots(true);
5
6EvPage evPage = EvPageFactory.create(page, configuration);

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

1Global.config.setRootSelector("#some-selector");

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
3EvPage evPage = EvPageFactory.create(page, options);

1EvConfig configuration = new EvConfig();
2configuration.setRootSelector(".some-selector");
3
4EvPage evPage = EvPageFactory.create(page, configuration);

1Global.config.setRootSelector(".some-selector");

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
4EvPage evPage = EvPageFactory.create(page, 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
7EvPage evPage = EvPageFactory.create(page, options);

1EvConfig configuration = new EvConfig();
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
8EvPage evPage = EvPageFactory.create(page, 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
7EvPage evPage = EvPageFactory.create(page, options);

1LoggingConfiguration loggingConfig = LoggingConfiguration.builder()
2    .loggingEnabled(true)
3    .loggingLevel("DEBUG")
4    .engineLoggingEnabled(true)
5    .build();
6
7EvConfig configuration = new EvConfig();
8configuration.setLoggingConfiguration(loggingConfig);
9
10EvPage evPage = EvPageFactory.create(page, 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
6EvPage evPage = EvPageFactory.create(page, options);

1EvConfig config = new EvConfig();
2config.setScreenshotMode(ScreenshotMode.PLAYWRIGHT); // full-page, SDK-managed screenshots
3
4EvPage evPage = EvPageFactory.create(page, config);

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
6EvPage evPage = EvPageFactory.create(page, options);

1Map<String, Boolean> toggles = new HashMap<>();
2toggles.put("USE_AXE_NEEDS_REVIEW", true);
3toggles.put("USE_AXE_BEST_PRACTICES", true);
4
5Global.config.setToggles(toggles);

1EvConfig config = new EvConfig();
2config.addToggle("USE_AXE_NEEDS_REVIEW", true);

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
8EvPage evPage = EvPageFactory.create(page, options);

1EvConfig localConfig = new EvConfig();
2localConfig.skipValidation("test.1--selector", "http://url.to.skip/path1",
3        "NO_DESCRIPTIVE_TEXT", "NOT_FOCUSABLE");
4localConfig.skipValidation("test.2--selector", "http://url.to.skip/path2",
5        "NOT_FOCUSABLE", "ONE_MORE_TYPE_TO_EXCLUDE", "NO_DESCRIPTIVE_TEXT");
6
7evPage.evAnalyze(localConfig);

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
4EvPage evPage = EvPageFactory.create(page, options);

1EvConfig localConfig = new EvConfig();
2
3// Skip every validation type on #parent and everything inside it
4localConfig.skipValidation("#parent, #parent *", "http://url.to.skip/path1", "*");
5
6evPage.evAnalyze(localConfig);

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.

Include Validations

Reports only the validation types listed, and drops everything else. This is the allowlist counterpart of Skip Validations: skip removes selected types from an otherwise full report, while include restricts the report to selected types.

Use it to focus a test run on one area, such as color contrast or missing labels, without listing every other type to exclude.

Issue type IDs can be found by inspecting a JSON report as described in Web Reports.

Default: every validation type is reported.

The setting is global. Unlike Skip Validations it takes no URL pattern and no CSS selector, and it applies to the whole scan. It is available only through the modern analysis configuration schema shown below; there is no legacy flat spelling for it.

1analysis:
2  INCLUDE_VALIDATIONS:
3    - 'NO_DESCRIPTIVE_TEXT'
4    - 'WRONG_SEMANTIC_ROLE'

1{
2  "analysis": {
3    "INCLUDE_VALIDATIONS": ["NO_DESCRIPTIVE_TEXT", "WRONG_SEMANTIC_ROLE"]
4  }
5}

1EvincedOptions options = EvincedOptions.create()
2    .analysis(a -> a
3        .raw("INCLUDE_VALIDATIONS", List.of("NO_DESCRIPTIVE_TEXT", "WRONG_SEMANTIC_ROLE")));
4
5EvPage evPage = EvPageFactory.create(page, options);

Reporting every validation type

Leaving the setting out reports every validation type. So does the wildcard *, on its own or as a single-item list, and so does an empty list.

A wildcard listed next to concrete type names is not a wildcard. ['NOT_FOCUSABLE', '*'] reports only NOT_FOCUSABLE; the * entry is treated as a type name that matches nothing. This mirrors the behavior of Skip Validations.

Combining with Skip Validations

The two settings apply together, and a result is reported only if it passes both. Include narrows the set of types; skip can still suppress individual elements within the types that remain. A type named in both is reported only on the elements its skip rule does not match.

Effect on passed validations

The setting narrows passed results as well as failed ones. Passed results appear in a report only when Passed Validations is enabled. When it is enabled, they are restricted to the same list of types.

Type names are not validated

Type names are not checked against the engine's list of issue types, so a name that is not a real type ID matches nothing.

Note: an empty list and a list of names that match nothing produce opposite results. An empty list reports every validation type. A list such as ['NOT_FOCUSABL'] reports no issues at all. If a run returns zero issues unexpectedly, check the type names in the list against a JSON report.

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
7EvPage evPage = EvPageFactory.create(page, options);

1RecordingServiceConfiguration recordingConfiguration = new RecordingServiceConfiguration();
2recordingConfiguration.setEnableDebounceNewSelectors(true);
3recordingConfiguration.setDebounceNewSelectorsMs(1000);
4recordingConfiguration.setDelayMode("throttle");
5
6EvConfig evincedConfiguration = new EvConfig();
7evincedConfiguration.setRecordingConfiguration(recordingConfiguration);
8
9EvPage evPage = EvPageFactory.create(page, evincedConfiguration);

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, and — new in this release — per axe-core rule ID, so overrides for aXe-sourced issues no longer need to go through the Evinced issue type.

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
6EvPage evPage = EvPageFactory.create(page, options);

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), which previously had no dedicated override in Playwright Java SDK.

Shadow DOM Support

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

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
3EvPage evPage = EvPageFactory.create(page, options);

1EvConfig configuration = new EvConfig();
2configuration.setIFramesIncluded(false);
3
4EvPage evPage = EvPageFactory.create(page, 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
6EvPage evPage = EvPageFactory.create(page, options);

1EvConfig config = new EvConfig();
2config.setIFramesIncluded(true);
3config.setIncludeHiddenIframeDomains(Arrays.asList("example.com", "test.com"));
4
5EvPage evPage = EvPageFactory.create(page, config);

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
3EvPage evPage = EvPageFactory.create(page, options);
4Report report = evPage.evAnalyze();
5
6List<Issue> failedValidations = report.getFailedValidations();
7List<Issue> passedValidations = report.getPassedValidations();

1EvConfig config = new EvConfig();
2config.setIncludePassedValidations(true);
3
4EvPage evPage = EvPageFactory.create(page, config);
5Report report = evPage.evAnalyze();
6
7List<Issue> failedValidations = report.getFailedValidations();
8List<Issue> passedValidations = report.getPassedValidations();

Proxy

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

1...
2BrowserType.LaunchOptions launchOptions = new BrowserType.LaunchOptions();
3launchOptions.setProxy(new Proxy("ip:port").setUsername("user").setPassword("password"));
4Browser browser = browserType.launch(launchOptions);
5EvPage evPage = EvPageFactory.create(browser.newPage());
6//if you want to use online authentication
7EvincedSDK.setCredentials("serviceId", "secret");
8...

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    maxWait: 7500

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

1EvincedOptions options = EvincedOptions.create()
2    .network(n -> n.idle(i -> i
3        .enabled(true)
4        .maxWait(7500)));
5
6EvPage evPage = EvPageFactory.create(page, options);

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

1NetworkIdleConfiguration idleConfig = new NetworkIdleConfiguration()
2    .setEnabled(true)
3    .setMaxWait(7500);
4
5EvConfig configuration = new EvConfig();
6configuration.setNetworkIdleConfiguration(idleConfig);
7
8EvPage evPage = EvPageFactory.create(page, configuration);

Implementation note: on Playwright Java SDK, network-idle detection is built on Playwright's own network-idle wait. The timeout setting has no effect here — Playwright's internal idle window is fixed — only enabled and maxWait change behavior.

How It Works:

The SDK monitors all network requests and waits for the network to become idle before proceeding with analysis:

1. Network is considered "idle" when no requests are active for at least idleTimeout milliseconds
2. Analysis waits for idle state or maxWaitTime, whichever comes first
3. Configuration from evStart() automatically applies to subsequent page navigations and evStop()

Best Practices:

• Start with defaults: Enable with default settings and adjust only if needed
• Increase timeout for slow APIs: If your backend is slow, increase maxWaitTime
• Use per-command for specific pages: Enable only for pages with dynamic content

Important Notes:

• Disabled by default: The feature is opt-in to maintain backward compatibility
• No overhead when disabled: When not enabled, there is zero performance impact
• Automatic timeout extension: Command timeouts are automatically adjusted based on maxWaitTime
• Warning on timeout: If maxWaitTime is exceeded, the SDK logs a warning and proceeds with analysis

Custom SSL Trust Store

Some enterprise environments route outbound HTTPS traffic through a corporate proxy that performs TLS inspection. The proxy re-signs every connection with an internal Certificate Authority (CA) that the JVM does not recognise out of the box, and SDK network calls fail with PKIX path building failed: unable to find valid certification path to requested target.

The SDK funnels every outbound HTTPS call through a single network layer, so this affects all SDK traffic — license validation, anonymized telemetry, component-recognition backends, and uploading reports to the Evinced Platform. Depending on which destinations your proxy intercepts you may see some or all of these failures in the SDK log.

The fix is a configuration option on the SDK: you build an SSLContext that trusts your internal root CA, attach it to the SDK's configuration object, and pass that configuration to the SDK entry point. The SDK takes care of the rest. The JVM-wide truststore is not modified, and the rest of your application's HTTPS traffic is untouched. You never need to call internal SDK APIs directly.

Default: no value — the SDK falls back to the JVM default truststore and honours -Djavax.net.ssl.trustStore=... when set.

Trust an internal Certificate Authority from a PEM/DER file

Most environments only need to trust one extra root CA — the one used by the corporate proxy. The bundled SslContextFactory builds an SSLContext that combines the JVM defaults with your additional certificate(s).

An SSLContext instance can't be expressed in an evConfig file or an environment variable, so this setting is programmatic-only, either through EvincedOptions or the deprecated configuration object:

1import com.evinced.EvPage;
2import com.evinced.EvPageFactory;
3import com.evinced.common.network.SslContextFactory;
4import com.evinced.dto.configuration.EvincedOptions;
5
6import com.microsoft.playwright.Browser;
7import com.microsoft.playwright.Playwright;
8
9import javax.net.ssl.SSLContext;
10import java.io.InputStream;
11
12EvincedOptions options;
13try (InputStream rootCa = MyTest.class.getResourceAsStream("/corp-root.pem")) {
14    SSLContext sslContext = SslContextFactory.composedWithDefaults(rootCa);
15    options = EvincedOptions.create().network(n -> n.sslContext(sslContext));
16}
17
18// The SDK uses the supplied SSLContext for every outbound HTTPS call —
19// license validation, telemetry, component-recognition backends, and
20// uploads to the Evinced Platform.
21Playwright playwright = Playwright.create();
22Browser browser = playwright.chromium().launch();
23EvPage page = EvPageFactory.create(browser.newPage(), options);

1import com.evinced.EvPage;
2import com.evinced.EvPageFactory;
3import com.evinced.common.network.NetworkManagerConfig;
4import com.evinced.common.network.SslContextFactory;
5import com.evinced.impl.config.EvConfig;
6
7import com.microsoft.playwright.Browser;
8import com.microsoft.playwright.Playwright;
9
10import javax.net.ssl.SSLContext;
11import java.io.InputStream;
12
13EvConfig config = new EvConfig();
14try (InputStream rootCa = MyTest.class.getResourceAsStream("/corp-root.pem")) {
15    SSLContext sslContext = SslContextFactory.composedWithDefaults(rootCa);
16    config.setNetworkConfiguration(new NetworkManagerConfig().withSslContext(sslContext));
17}
18
19Playwright playwright = Playwright.create();
20Browser browser = playwright.chromium().launch();
21EvPage page = EvPageFactory.create(browser.newPage(), config);

Both PEM (-----BEGIN CERTIFICATE----- / -----END CERTIFICATE-----) and DER (binary) inputs are accepted. You can pass several streams in one call if your proxy chains multiple internal CAs.

Re-use an SSLContext you already have

If your application already builds an SSLContext (for example via Spring's SslBundles or your own keystore loader), pass it in directly — there is no requirement to use SslContextFactory:

1SSLContext myContext = ...; // already configured elsewhere
2
3EvincedOptions options = EvincedOptions.create().network(n -> n.sslContext(myContext));
4
5EvPage page = EvPageFactory.create(browser.newPage(), options);

Verify it worked

If the trust chain is still broken, the SDK short-circuits each affected network call instead of retrying three times. Look for this WARN line in the SDK log — it can appear against any *.evinced.com host the SDK contacts:

1[NetworkManager] TLS trust failure for https://host.evinced.com/... —
2PKIX path building failed: ...

If you see it, the certificate you supplied does not match the chain the proxy presents — re-export the proxy's root CA from the browser and try again. If SDK network calls succeed, no TLS-related warnings appear at all.

Global Switch

When false, disables Evinced functionality. Enabled by default, use this setting to disable Evinced accessibility analysis when not needed during test development or when running CI jobs where accessibility testing is not intended.

Default: true.

When switched off:

• evStart() and evSaveFile() will be bypassed.
• evStop() and evAnalyze() will return an empty report.

Switching Evinced Functionality Off in Configuration

1switchOn: false

1{
2  "switchOn": false
3}

1EvincedOptions options = EvincedOptions.create().switchOn(false);
2
3EvPage evPage = EvPageFactory.create(page, options);

1EvincedSDK.switchOn(false);

Important! Global Switch environment variable overrides the global configuration option.

Switching Evinced Functionality Off in Environment

1export EV_SWITCH_ON=false

Uploading Reports to Evinced Platform

Introduction

Evinced Platform allows you to seamlessly collect, organize, visualize and monitor Evinced accessibility reports in one place. In this section, we will guide you through the key functionalities of the upload methods of the accessibility reports from the Evinced SDK to the Evinced Platform, which was introduced in version 2.3.2. This upload method is fully compatible with the previous versions of the Evinced SDK API, and is disabled by default.

Enable Upload Report to Platform

To enable the uploading functionality of accessibility reports to the Evinced Platform you will need to set the enableUploadToPlatform method to "true":

1EvincedSDK.enableUploadToPlatform(true);

Note: Using PlatformUpload.ENABLED in method parameters (e.g., evPage.evAnalyze(PlatformUpload.ENABLED)) is not sufficient on its own. You must first enable the feature by calling EvincedSDK.enableUploadToPlatform(true). The method parameter only controls whether a specific report uploads when the feature is already enabled.

Automatic Report Upload

Once the enableUploadToPlatform method is set to true and setUploadToPlatformDefault is true (which is the default), all generated reports will be automatically uploaded to the Platform immediately upon calling the evStop() or evAnalyze() command.

How it works:

• When enableUploadToPlatform: true and setUploadToPlatformDefault: true (default), upload happens automatically
• No additional code is needed - just call evAnalyze() or evStop() and the report uploads
• Upload occurs synchronously as part of the command execution

If you want to change this behavior and control uploads manually, set the setUploadToPlatformDefault feature flag to false.

1EvincedSDK.setUploadToPlatformDefault(false);

If the setUploadToPlatformDefault is disabled, you can still upload selected reports to the platform. For that, use the following parameter in the evStop() command:

1...
2evPage.evStop(PlatformUpload.ENABLED);

Or, in the evAnalyze() command:

1evPage.evAnalyze(PlatformUpload.ENABLED);

Test Names

To facilitate report management and be able to distinguish between different reports on the Platform, use the setTestInfo method to inform the test name and test class. It’s recommended to do that in the “beforeEach” hook.

TestNG:

1@BeforeEach
2public void platformUploadingTestSetup(TestInfo testInfo){
3    evPage.setTestInfo(testInfo.getDisplayName(), this.getClass().getCanonicalName());
4}

Labels and Custom Fields

You can attach labels and custom fields to your report to enhance readability and organization in the platform. Labels help you filter, search, and organize reports on the Evinced Platform.

There are two types of labels:

Built-in Labels: Pre-defined labels that can be set using the addLabel method. Available built-in labels include:

• testName - The name of the test
• testFile - The file path of the test
• environment - The environment where the test runs (e.g., "Development", "Staging", "Production")
• flow - The test flow identifier
• gitBranch - The Git branch name
• gitUserName - The Git user name
• gitVersion - The Git commit version

Custom Labels: Flexible key-value pairs that can be set using the customLabel method. You can use any custom key-value pairs, including:

• Single values: { productVersion: '1.0.0' }
• Multiple values (arrays): { browsers: ['Chrome', 'Firefox'] }
• Special label unitId: Use this to tag tests for relevant units within your organization

See the following code examples of how to set up labels:

1EvincedSDK.getTestRunInfo()
2        .addLabel(Parameter.GIT_USER_NAME, "git")
3        .addLabel(Parameter.GIT_BRANCH, "main")
4        .addLabel(Parameter.USER_AGENT, "agent007")
5        .addLabel(Parameter.ENVIRONMENT, "production")
6        .addLabel(Parameter.FLOW, "standard")
7        .customLabel("Product version", "1.2.3")
8        .customLabel("OS Type", "Linux")
9        .customLabel("OS Name", "openSuse");

Use of beforeEach and afterEach Hooks

We recommend using the beforeEach and afterEach hooks to control analysis sessions and upload reports to the platform. This way, each test will be uploaded separately with its own report.

In beforeEach hook use evStart() to start Evinced analysis and set any labels you want for the report to contain when uploading to the platform. In the afterEach hook call evStop() to stop analysis and upload reports to the platform. See this code example:

1@BeforeMethod
2protected void evStartBeforeMethod(ITestContext context, ITestResult result) {
3    evPage.setTestInfo(testInfo.getDisplayName(), this.getClass().getCanonicalName());
4    evPage.evStart();
5}
6
7@AfterMethod
8protected void evStopAfterMethod(ITestContext context, ITestResult result) {
9    evPage.evStop();
10}

Putting All of This Together

Here is a complete code snippet of how to perform uploads to the platform on a per-test basis.

1package com.evinced.example;
2
3import com.evinced.EvPage;
4import com.evinced.EvPageFactory;
5import com.evinced.EvincedSDK;
6import com.evinced.impl.resultsUpload.TestRunInfo;
7import com.microsoft.playwright.Browser;
8import com.microsoft.playwright.Playwright;
9import org.testng.annotations.*;
10import org.testng.ITestContext;
11import org.testng.ITestResult;
12
13
14public class TestExample {
15    private static Playwright playwright;
16    protected Browser browser;
17    protected EvPage evPage;
18
19    @BeforeSuite
20    protected void beforeSuite() {
21        EvincedSDK.setOfflineCredentials(System.getenv("AUTH_SERVICE_ID"), System.getenv("AUTH_TOKEN"));
22        EvincedSDK.enableUploadToPlatform(true);
23
24        EvincedSDK.getTestRunInfo()
25                .addLabel(TestRunInfo.Parameter.GIT_USER_NAME, "git")
26                .addLabel(TestRunInfo.Parameter.GIT_BRANCH, "master")
27                .customLabel("Testing purpose", "Test platform uploading feature");
28    }
29
30    @BeforeTest
31    protected void beforeTest() {
32        browser = getBrowser();
33        evPage = EvPageFactory.create(browser.newPage());
34    }
35
36    @AfterTest
37    protected void afterTest() {
38        playwright.close();
39    }
40
41    @BeforeMethod
42    protected void evStartBeforeMethod(ITestContext context, ITestResult result) {
43        evPage.setTestInfo(result.getMethod().getMethodName(), result.getTestClass().getName());
44        evPage.evStart();
45    }
46
47    @AfterMethod
48    protected void evStopAfterMethod(ITestContext context, ITestResult result) {
49        evPage.evStop();
50    }
51
52    public static Browser getBrowser() {
53        playwright = Playwright.create();
54        return playwright.chromium().launch();
55    }
56
57
58    @Test(testName = "Test url")
59    public void testUrl() {
60        evPage.navigate("https://demo.evinced.com");
61    }
62}
63

Tutorials

You can find fully functional example projects on our GitHub.

Step-by-step adding Evinced to existing test suite.

Preface: Existing test suite

1package tutorial;
2
3import com.microsoft.playwright.Browser;
4import com.microsoft.playwright.Page;
5import com.microsoft.playwright.Playwright;
6import org.junit.jupiter.api.*;
7
8import static org.junit.jupiter.api.Assertions.assertTrue;
9
10
11public class TutorialTest1 {
12    private static Playwright playwright;
13    private static Browser browser;
14    private Page page;
15
16    private interface Selectors {
17            String HOUSE_DROPDOWN = "#gatsby-focus-wrapper > main > div.wrapper-banner > div.filter-container > div:nth-child(1) > div > div.dropdown.line";
18            String TENT_OPTION = "#gatsby-focus-wrapper > main > div.wrapper-banner > div.filter-container > div:nth-child(1) > div > ul > li:nth-child(4)";
19            String LOCATION_DROPDOWN = "#gatsby-focus-wrapper > main > div.wrapper-banner > div.filter-container > div:nth-child(2) > div > div.dropdown.line";
20            String CANADA_OPTION = "#gatsby-focus-wrapper > main > div.wrapper-banner > div.filter-container > div:nth-child(2) > div > ul > li:nth-child(1)";
21            String SEARCH_BUTTON = "#gatsby-focus-wrapper > main > div.wrapper-banner > div.filter-container > a";
22            String SEARCH_RESULTS = "#gatsby-focus-wrapper > main > h1";
23    }
24
25
26    @BeforeAll
27    private static void launchBrowser() {
28        playwright = Playwright.create();
29        browser = playwright.chromium().launch();
30    }
31
32    @AfterAll
33    private static void closeBrowser() {
34        playwright.close();
35    }
36
37    @BeforeEach
38    private void setUp(){
39        page = browser.newPage();
40    }
41
42    @AfterEach
43    private void tearDown(){
44        page.close();
45    }
46
47    @Test
48    public void tutorialTest1(){
49        page.navigate("https://demo.evinced.com");
50        assertTrue(page.isVisible(Selectors.SEARCH_BUTTON));
51    }
52
53    @Test
54    public void tutorialTest2(){
55        page.navigate("https://demo.evinced.com");
56        page.click(Selectors.HOUSE_DROPDOWN);
57        page.click(Selectors.TENT_OPTION);
58        page.click(Selectors.LOCATION_DROPDOWN);
59        page.click(Selectors.CANADA_OPTION);
60        page.click(Selectors.SEARCH_BUTTON);
61        page.waitForLoadState();
62        assertTrue(page.isVisible(Selectors.SEARCH_RESULTS));
63    }
64}