Supported versions / frameworks

Evinced WDIO mobile SDK supports the following values for Appium's automationName desired capability:

• XCUITest
• Espresso
• UIAutomator2

Older versions of automation drivers (e.g deprecated Appium iOS driver based on UIAutomation) are not supported.

Prerequisites

• Node.js 12.x or higher
• Appium Server version 1.21 or higher
• Any Webdriver IO version compatible with the versions of Node.js and Appium outlined above

Get Started

Setup

AI Skills available: An Evinced AI Skills plugin can walk your AI coding assistant through this setup, and later help configure or debug the scan. See Mobile AI Skills for installation and details.

In order to use any of the Evinced Mobile SDKs you first need to create an Evinced account. Once your account is created, you will get your apiKey and a matching serviceAccountId. Pass these tokens using the setupCredentials() method and Evinced will validate access upon test execution. If an outbound internet connection is not available in your running environment - contact us at support@evinced.com to get an offline API key.

Install Evinced WDIO SDK from the remote registry

Installation using NPM

To install the package, first configure npm to authenticate with the Evinced JFrog Artifactory, then run the install command.

Configure npm registry:

Create or update the .npmrc file in your project root (or your home directory for global configuration):

1@evinced:registry=https://evinced.jfrog.io/artifactory/api/npm/restricted-npm/
2//evinced.jfrog.io/artifactory/api/npm/restricted-npm/:_authToken=<your-auth-token>
3//evinced.jfrog.io/artifactory/api/npm/restricted-npm/:always-auth=true

Replace <your-auth-token> with your JFrog authentication token. If you don't have access, contact Evinced support.

The SDK can be added to your project as a regular NPM dependency by executing the following command:

1npm install --save @evinced/wdio-mobile-sdk

or with Yarn:

1yarn add @evinced/wdio-mobile-sdk

Install Evinced WDIO SDK from a local ZIP archive

You can also perform installation right from the standalone .tar.gz distribution file. Simply add the following entry to your package.json and perform installation by executing the npm install command.

1"dependencies": {
2//... your project dependencies
3"@evinced/wdio-mobile-sdk": "path/to/the/archive"
4}

Install with potentially incompatible peer dependencies

The SDK package enforces a check for compatible peer dependencies during the package installation. In order to ensure successful accessibility testing it is recommended to have only those major versions of the packages installed in the test environment which are compatible with the SDK. For details please refer to the peerDependencies section of the SDK's package.json file. If for any reason you have to use particular package versions which are not compatible peer dependencies of the SDK and you want to suppress related NPM errors during the SDK installation you may add the --force flag to the installation command to proceed with the installation:

1npm install --save --force @evinced/wdio-mobile-sdk

The SDK will still be installed and will be usable, however in such scenario unpredictable compatibility issues may occur.

Your first test

Initialize the SDK object

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

1import { EvincedWdioMobileSdk } from '@evinced/wdio-mobile-sdk';

Create a new instance of the SDK by using the new keyword:

1const evincedWdioSdk = new EvincedWdioMobileSdk();

This will create a new instance of the Evinced WDIO mobile SDK with the default configuration.

Provide your license information

The Evinced WDIO SDK requires authentication credentials which consist of two string values mentioned above: apiKey and serviceAccountId. These values can be found by logging in to the Evinced Product Hub.

For this purpose use the method evincedWdioSdk.setupCredentials(serviceAccountId, apiKey) as shown:

1let evincedWdioSdk: EvincedWdioMobileSdk;
2
3before(() =\> {
4    evincedWdioSdk = new EvincedWdioMobileSdk();
5const isLicenseValid = evincedWdioSdk.setupCredentials(
6    process.env.EVINCED_SERVICE_ACCOUNT_ID,
7    process.env.EVINCED_API_KEY
8);
9if (!isLicenseValid) {
10    //... something went wrong with your credentials, check logs for details
11    }
12});

In this example we put Evinced credentials into environment variables called EVINCED_SERVICE_ACCOUNT_ID and EVINCED_API_KEY. If the isLicenseValid variable is set to true, you are ready to proceed adding accessibility checks into your tests.

Add an Evinced accessibility check

Simply add the .report() method to check the current state for accessibility issues.

1it('should open a radio station no. 1', async () =\> {
2    const stationsScreen = await stationsScreen.show();
3    await stationsScreen.selectStation(0);
4    const screenTitle = await nowPlayingScreen.getTitle();
5    expect(screenTitle).toContain('Absolute country hits');
6    // Add an accessibility check
7    await evincedWdioSdk.report();
8});

Regardless of the test result, the report method will always output JSON and HTML report files. By default the files will be located in the local folder called evinced-reports. For more information regarding the HTML and JSON reports as well as the Report object itself, please see our detailed Mobile Reports page.

Adding multiple accessibility checks

If you would like to scan multiple states within a test simply add the .analyze() method at each appropriate point followed by the .reportStored() at the end of the test. This will consolidate all of the scans into a single set of report files (HTML and JSON).

1it('should open a radio station no. 1', async () =\> {
2    // Add an accessibility check
3    evincedWdioSdk.analyze();
4    const stationsScreen = await stationsScreen.show();
5    await stationsScreen.selectStation(0);
6    // Add an accessibility check
7    evincedWdioSdk.analyze();
8    const screenTitle = await nowPlayingScreen.getTitle();
9    expect(screenTitle).toContain('Absolute country hits');
10    // Add an accessibility check
11    evincedWdioSdk.analyze();
12    //Create the Evinced HTML and JSON reports
13    await evincedWdioSdk.reportStored();
14});

Baseline Comparison

Baseline Comparison compares accessibility reports against previously recorded baselines, tracking Persistent (existing), New (introduced), and Ignored (suppressed) issues.

How it works

The SDK matches baseline files by test suite, test method, operating system, screen resolution, and (on Android) optionally the device API level. Files are stored in <test-file-directory>/evinced/baselines/ with the naming pattern:

• iOS: {TestSuite}.{testMethod}.iOS.{width}x{height}.baseline.json
• Android: {TestSuite}.{testMethod}.Android[.api{level}].{width}x{height}.baseline.json — the .api{level} segment is included when the SDK can resolve the device API level.

Examples:

• iOS: LoginTests.testSuccessfulLogin.iOS.1920x1080.baseline.json
• Android: LoginTests.testSuccessfulLogin.Android.api29.1920x1080.baseline.json

OS values: iOS or Android

Quick Start

Enable baseline comparison globally or per method call:

Global configuration:

1const wdioSdk = new EvincedWdioMobileSdk({
2    baselineConfig: {
3        isEnabled: true,
4        mode: 'compare'
5    }
6});

Method-level (recommended):

1import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3const report = await wdioSdk.report(
4    new ReportOptionsBuilder()
5        .enableBaseline(BaselineMode.COMPARE)
6        .build()
7);

For full API details, see ReportOptionsBuilder API and BaselineIgnoreFilterBuilder API. For deprecated API migration, see Deprecated API.

Modes

Record mode - Creates baseline files for future comparisons:

1await wdioSdk.report(
2    new ReportOptionsBuilder()
3        .enableBaseline(BaselineMode.RECORD)
4        .build()
5);

Compare mode (default) - Compares against existing baselines:

1await wdioSdk.report(
2    new ReportOptionsBuilder()
3        .enableBaseline(BaselineMode.COMPARE)
4        .failTestOnNewIssues(true) // Fail test if new issues detected
5        .build()
6);

For complete workflow examples, see Workflow Examples.

Configuration Options

Common options:

• failTestOnNewIssues (default: true) - Fail test if new issues are detected
• failTestOnBaselineComparisonError (default: true) - Fail test on comparison errors

Method-level overrides global configuration:

1// Global
2const wdioSdk = new EvincedWdioMobileSdk({
3    baselineConfig: { isEnabled: true, mode: 'compare', failTestOnNewIssues: true }
4});
5
6// Override per test
7await wdioSdk.report(
8    new ReportOptionsBuilder()
9        .enableBaseline(BaselineMode.COMPARE)
10        .failTestOnNewIssues(false) // Override global setting
11        .build()
12);

Ignore Filters

Exclude specific issues from baseline comparison using BaselineIgnoreFilterBuilder:

1await wdioSdk.report(
2    new ReportOptionsBuilder()
3        .enableBaseline(BaselineMode.COMPARE)
4        .withBaselineConfig({
5            ignoreFilters: [
6                new BaselineIgnoreFilterBuilder()
7                    .withComment('Known issue - JIRA-1234')
8                    .withIssueTypes(['COLOR_CONTRAST'])
9                    .build()
10            ]
11        })
12        .build()
13);

For full API details, see BaselineIgnoreFilterBuilder API.

Additional Resources

• Workflow Examples - Complete step-by-step tutorials
• ReportOptionsBuilder API - Full builder API reference
• BaselineIgnoreFilterBuilder API - Filter builder reference
• Accessing Comparison Data - Working with ReportBaselineUtils
• Environment Variables - CI/CD configuration
• Troubleshooting - Common issues and solutions
• Windows limitations - Long paths and baseline file naming on Windows

Environment Variables

Configure baseline via environment variables for CI/CD.

Available variables:

• EVINCED_USE_BASELINE_FEATURE - Enable/disable baseline (default: false)
• EVINCED_BASELINE_MODE - Set mode: record or compare (default: compare)
• EVINCED_BASELINE_FORCE_DISABLE - Force disable (cannot be overridden)
• EVINCED_BASELINE_FAIL_ON_COMPARISON_ERROR - Fail on errors (default: true)
• EVINCED_BASELINE_FAIL_ON_NEW_ISSUES - Fail on new issues (default: true)

Configuration priority: Method-level > SDK-level > Environment variables > Defaults

Best Practices

1. Store baselines in version control
2. Use withCustomBaselineFileName when calling from lifecycle hooks (e.g. after()) so the baseline file name is explicit
3. Set CI/CD to use COMPARE mode
4. Use RECORD mode only when intentionally updating baselines
5. Use descriptive filter comments

Troubleshooting

Baseline File Not Found

• Verify the file exists in <test-file-directory>/evinced/baselines/
• Check that the file name matches the pattern: {TestSuite}.{testMethod}.{OS}[.api{level}].{width}x{height}.baseline.json
• Ensure operating system and screen resolution match (or use withCustomBaselineFileName to specify a custom file)

Multiple Baseline Files

• Ensure only one baseline file exists per test method, operating system, and resolution
• Use withCustomBaselineFileName to specify the exact file to use

Test Fails on New Issues

• Review the new issues in the HTML/JSON report
• Either fix the issues or update the baseline in record mode
• Use ignore filters for known acceptable issues

Windows limitations

Long path support

Baseline file paths can exceed Windows' default path limit (260 characters). If baseline files are missing or paths fail on Windows:

1. Git (per repo): git config core.longpaths true
2. Windows (system-wide): Set LongPathsEnabled = 1 in HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem (requires admin and reboot), or via PowerShell:

   1New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Alternatively, use shorter baseline file names (e.g. withCustomBaselineFileName with a short name) to stay under the limit.

Missing testSuite on Windows

When tests do not pass explicit context (e.g. via addReportCallInfo), WDIO may not provide testSuite in runner metadata on Windows. The SDK then uses UnknownSuite for baseline file names, while on macOS/Linux the same test gets the suite name (e.g. from the spec file path). Baseline file names can therefore differ across platforms for the same test, which breaks cross-platform baseline sharing (e.g. baselines recorded on Mac won't match when comparing on Windows).

Workaround: If tests may run on Windows, make baseline file names deterministic: pass explicit context via addReportCallInfo(...) or use withCustomBaselineFileName so the baseline file name is the same on all platforms.

Workflow Examples

Complete Workflow: Record → Compare

Step 1: Record Baseline

1import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3it("should record baseline for login screen", async () => {
4    await loginScreen.show();
5
6    const report = await wdioSdk.report(
7        new ReportOptionsBuilder()
8            .enableBaseline(BaselineMode.RECORD)
9            .build()
10    );
11});

Step 2: Baseline Files Ready

Baseline files are automatically created in <test-file-directory>/evinced/baselines/ directory. No copying is needed - they're ready to use for future comparisons.

Step 3: Compare Against Baseline

1import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3it("should compare against baseline", async () => {
4    await loginScreen.show();
5
6    const report = await wdioSdk.report(
7        new ReportOptionsBuilder()
8            .enableBaseline(BaselineMode.COMPARE)
9            .failTestOnNewIssues(true)
10            .build()
11    );
12
13    // Test will fail if new issues are detected
14});

Continuous Mode with Baseline

1import { ReportStoredOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3it("should track issues across navigation", async () => {
4    await homeScreen.show();
5
6    await wdioSdk.startAnalyze();
7
8    await loginScreen.show();
9    await usernameField.setValue("user");
10    await passwordField.setValue("pass");
11    await submitButton.click();
12
13    const reports = await wdioSdk.stopAnalyze(
14        new ReportStoredOptionsBuilder()
15            .enableBaseline(BaselineMode.COMPARE)
16            .build()
17    );
18});

Using baseline from lifecycle hooks

When calling reportStored() or stopAnalyze() from lifecycle hooks (e.g. after(), afterAll()), the test method name may not be available for baseline file naming. Use withCustomBaselineFileName to specify the baseline file name or path:

1import { ReportStoredOptionsBuilder } from '@evinced/wdio-mobile-sdk';
2
3after(async () => {
4    const reports = await wdioSdk.reportStored(
5        new ReportStoredOptionsBuilder()
6            .enableBaseline()
7            .withCustomBaselineFileName('SuiteComplete.iOS.1920x1080.baseline.json')
8            .build()
9    );
10});

Accessing Comparison Data

Report Object

Access baseline comparison information from the Report object:

1import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3const report = await wdioSdk.report(
4    new ReportOptionsBuilder()
5        .enableBaseline(BaselineMode.COMPARE)
6        .build()
7);
8
9if (report.baselineCompareInfo) {
10    console.log('Baseline status:', report.baselineCompareInfo.status);
11    console.log('Baseline file:', report.baselineCompareInfo.baselineReportFileName);
12
13    if (report.baselineCompareInfo.summary) {
14        console.log('New issues:', report.baselineCompareInfo.summary.newIssues);
15        console.log('Persistent issues:', report.baselineCompareInfo.summary.persistentIssues);
16        console.log('Resolved issues:', report.baselineCompareInfo.summary.resolvedIssues);
17    }
18}

ReportBaselineUtils

The ReportBaselineUtils utility class provides helper methods for working with baseline comparison data. Create an instance with the report, then call methods on it:

• getBaselineCompareInfo() – Returns the report's baselineCompareInfo (status, summary, baseline file name), or undefined if baseline comparison was not run.
• hasNewIssues() – Returns whether the report has new issues (uses baselineCompareInfo.summary.newIssues).
• hasPersistentIssues() – Returns whether the report has persistent issues (uses baselineCompareInfo.summary.persistentIssues).
• getNewIssues() – Returns all issues with baselineInfo.status === BaselineStatus.NEW.
• getNewIssuesFiltered(filterType, filter) – Returns new issues filtered by a BaselineIgnoreFilter (use BaselineIgnoreFilterBuilder to build the filter). filterType is IssueFilterType.INCLUDE or IssueFilterType.EXCLUDE.

Example:

1import { ReportBaselineUtils, ReportOptionsBuilder, BaselineMode, IssueFilterType, BaselineIgnoreFilterBuilder, SeverityId } from '@evinced/wdio-mobile-sdk';
2
3const report = await wdioSdk.report(
4    new ReportOptionsBuilder()
5        .enableBaseline(BaselineMode.COMPARE)
6        .build()
7);
8
9const utils = new ReportBaselineUtils(report);
10
11// Get baseline comparison info
12const info = utils.getBaselineCompareInfo();
13
14// Check if report has new issues
15if (utils.hasNewIssues()) {
16    console.log('Report contains new issues');
17}
18
19// Get all new issues
20const newIssues = utils.getNewIssues();
21console.log(`Found ${newIssues.length} new issues`);
22
23// Get filtered new issues (e.g. only critical severity)
24const filter = new BaselineIgnoreFilterBuilder()
25    .withSeverities([SeverityId.CRITICAL])
26    .build();
27const criticalNewIssues = utils.getNewIssuesFiltered(IssueFilterType.INCLUDE, filter);

Issue Object

When baseline comparison is enabled, each issue has baselineInfo.status (BaselineStatus: 'New', 'Persistent', or 'Ignored'). Issues are on report elements, not on the report root:

1import { BaselineStatus } from '@evinced/wdio-mobile-sdk';
2
3report.elements.forEach(element => {
4    (element.issues ?? []).forEach(issue => {
5        if (issue.baselineInfo?.status === BaselineStatus.NEW) {
6            console.log('New issue:', issue.issueType?.name);
7        } else if (issue.baselineInfo?.status === BaselineStatus.PERSISTENT) {
8            console.log('Persistent issue:', issue.issueType?.name);
9        } else if (issue.baselineInfo?.status === BaselineStatus.IGNORED) {
10            console.log('Ignored issue:', issue.issueType?.name);
11        }
12    });
13});

Cloud-Based Validations

Cloud-based validations extend on-device accessibility scanning with server-side AI/LLM-powered checks. When enabled, the SDK sends UI data to Evinced's secure cloud services, runs advanced models, and merges the results back into the standard accessibility report — the same HTML, JSON, and CSV outputs you already use.

Key design principles:

• Opt-in only. Cloud validations are disabled by default. You must explicitly enable them.
• Fail-open by default. If the cloud call fails (timeout, network issue), the SDK falls back to local-only results. Tests do not fail unless you explicitly configure failOnError = true.
• Unified reports. Cloud and local findings appear together in every report format (HTML, JSON, CSV).
• Synchronous processing. Cloud validation blocks the scan until a response is received or the configured timeout elapses.

Meaningful Heading

Meaningful Heading checks whether on-screen headings meaningfully describe their sections (aligned with WCAG-style guidance on headings and labels). It runs inside the Evinced validation pipeline and surfaces findings as normal accessibility issues — unlike Export accessibility labels of buttons and images for manual review, which is a separate JSON export of button and image labels.

• Issue type: IssueTypeId.MEANINGFUL_HEADING
• The needsReview flag is set on these issues (LLM results have inherent variance)

AI validation and stability

Meaningful Heading is LLM-assisted: an LLM evaluates each heading together with its surrounding section content.

The needsReview flag is set to true on LLM-generated issues. Use getNeedsReviewIssues(report) / hasNeedsReviewIssues(report) to query these issues separately from deterministic findings.

Requirements

1. Online credentials: call wdioSdk.setupCredentials(serviceAccountId, apiKey) before running cloud-enabled scans. Offline credentials (setupOfflineCredentials) are not supported for cloud validation flows.
2. Outbound HTTPS access from your test environment to Evinced cloud validation services. No custom endpoints or on-premises hosting are available.
3. Minimum SDK version: requires WDIO Mobile SDK 1.31.0 or higher.
4. CI timeout budget: each scan call adds a cloud round-trip — typically 2-4 seconds, up to the configured timeout (25 s by default) in worst case. Consider a separate CI job for cloud-enabled scans.
5. iOS environment: Meaningful Heading requires a minimum WebDriverAgent (WDA) version bundled with XCUITest driver v9.7+. See iOS environment requirements below.
6. Android environment: Meaningful Heading requires the heading attribute in the UIAutomator2 page source (appium-uiautomator2-driver v4.0.1+ and appium-uiautomator2-server v7.2.0+). See Android environment requirements below.

iOS environment requirements

Local runs (recommended):

• Use XCUITest driver v9.7 or higher (compatible with Appium Server 2.0.0+). This is the simplest and most reliable option.

Local runs (fallback — outdated XCUITest driver):

• If upgrading XCUITest is not possible, use a prebuilt WDA (v11.2.0+) via Appium capabilities:

1capabilities: {
2    'appium:usePreinstalledWDA': true,
3    'appium:prebuiltWDAPath': '/path/to/WebDriverAgentRunner-Runner.app'
4}

• This approach is more fragile and harder to maintain. Upgrade XCUITest when possible.

SauceLabs physical devices:

• Use Appium version appium3-2026-01 (or later when available) in the SauceLabs capability configuration.
• Older hosted Appium versions do not include a compatible WDA; custom/prebuilt WDA is not supported on SauceLabs physical devices.

SauceLabs simulators:

• Please use appium3-2026-01 or higher.

Android environment requirements

Meaningful Heading on Android depends on the heading attribute in the UIAutomator2 page source (AccessibilityNodeInfo.isHeading()). That attribute is present starting with:

• appium-uiautomator2-driver v4.0.1 or higher
• appium-uiautomator2-server v7.2.0 or higher (bundled with those driver versions)

Older UIAutomator2 stacks omit this field. The SDK then treats every node as a non-heading, so Meaningful Heading finds nothing (silent false negatives). Confirm a known heading in await driver.getPageSource() includes heading="true".

Local runs:

• Install UIAutomator2 driver v4.0.1 or higher (current 6.x / 7.x / 8.x drivers are fine). Compatible with Appium Server 2.0.0+.

SauceLabs physical devices:

• Use Appium version appium3-2026-01, appium3-2026-04, or appium3-2026-07 (or a later dated Appium 3 image) in sauce:options:

1capabilities: {
2    'sauce:options': {
3        appiumVersion: 'appium3-2026-01'
4    }
5}

• Do not use Sauce latest or older Appium 2 images such as appium2-20250101. Those ship UIAutomator2 driver v3.9.x, which does not expose heading.

SauceLabs Android emulators:

• Not supported for Meaningful Heading. Sauce virtual Android devices currently offer Appium 2.x only (for example 2.11.0 with UIAutomator2 driver v3.7.0). Android 16+ AVDs are limited to that stack and cannot provide heading. Use a Sauce real device, a local emulator with a current UIAutomator2 driver, or another farm that ships driver v4.0.1+.

Other device farms:

• Any host is fine if it provides UIAutomator2 driver v4.0.1+ and server v7.2.0+.

Environment quick reference

Configuration

Global configuration (init options)

Set cloud validations once for the entire test session via constructor options or setOptions(). All subsequent report(), reportStored(), and stopAnalyze() calls inherit this configuration unless overridden per-call. analyze() only collects snapshots; cloud validations run when reports are generated.

1import { CloudValidationsConfig } from '@evinced/wdio-mobile-sdk';
2
3// Enable with defaults (25 s timeout, fail-open)
4wdioSdk.setOptions({
5    cloudValidations: CloudValidationsConfig.enabled()
6});

CloudValidationsConfig methods:

Configuration parameters:

Per-scan override

Override cloud validation settings for a single scan call by passing cloudValidations on ReportOptions / ReportStoredOptions, or via ReportOptionsBuilder.withCloudValidations(...) / ReportStoredOptionsBuilder.withCloudValidations(...).

Important: A per-call cloudValidations object fully replaces the init configuration for that call. Fields are not merged with the global config. Omit the override to use init defaults; pass a complete config when you need different settings for one call.

1import { CloudValidationsConfig, ReportOptionsBuilder } from '@evinced/wdio-mobile-sdk';
2
3// Full replace for this report call (custom timeout + fail-open):
4const report = await wdioSdk.report(
5    new ReportOptionsBuilder()
6        .shouldAssert(false)
7        .withCloudValidations(CloudValidationsConfig.enabled(120))
8        .build()
9);
10
11// Disable cloud for one specific scan (e.g. a flaky screen):
12const reportNoCloud = await wdioSdk.report({
13    cloudValidations: new CloudValidationsConfig().setEnabled(false)
14});

Note: analyze() does not accept cloud overrides. For continuous-mode scans using startAnalyze() / stopAnalyze(), configure cloud globally via init options or pass options to stopAnalyze().

API reference — all scan modes

Cloud validations are supported in single scan, selected flow, and continuous modes.

Single scan

A single report() call validates the current screen and returns a Report.

1import {
2    CloudValidationsConfig,
3    IssueTypeId
4} from '@evinced/wdio-mobile-sdk';
5
6// 1. Set up credentials (online credentials required)
7wdioSdk.setupCredentials('your-service-account-id', 'your-api-key');
8
9// 2. Enable cloud validations globally
10wdioSdk.setOptions({
11    cloudValidations: CloudValidationsConfig.enabled()
12});
13
14// 3. Run a single-scan report on the current screen
15const report = await wdioSdk.report();
16
17// 4. Check for Meaningful Heading issues
18const meaningfulHeadingIssues = report.elements.flatMap((element) =>
19    (element.issues ?? []).filter(
20        (issue) => issue.issueType?.id === IssueTypeId.MEANINGFUL_HEADING
21    )
22);

Per-call override:

1import { CloudValidationsConfig, ReportOptionsBuilder } from '@evinced/wdio-mobile-sdk';
2
3// Override for this specific report call:
4const report = await wdioSdk.report(
5    new ReportOptionsBuilder()
6        .shouldAssert(false)
7        .withCloudValidations(CloudValidationsConfig.enabled(60))
8        .build()
9);

Selected Flow Scan (reportStored)

analyze() records multiple screens; reportStored() runs validation across all of them.

1import { CloudValidationsConfig, ReportStoredOptionsBuilder } from '@evinced/wdio-mobile-sdk';
2
3// 1. Enable cloud globally (applies to the full flow):
4wdioSdk.setOptions({
5    cloudValidations: CloudValidationsConfig.enabled()
6});
7
8// 2. Collect snapshots
9await wdioSdk.analyze();
10// navigate to screen 1...
11await wdioSdk.analyze();
12// navigate to screen 2...
13
14// 3. Validate all stored snapshots with cloud enabled:
15const reports = await wdioSdk.reportStored();
16
17// Or finalize with a per-call override (e.g. custom timeout):
18const reportsWithOverride = await wdioSdk.reportStored(
19    new ReportStoredOptionsBuilder()
20        .withCloudValidations(CloudValidationsConfig.enabled(120))
21        .build()
22);

Continuous Mode (stopAnalyze)

startAnalyze() collects accessibility snapshots as your test navigates. Cloud validations run when reports are generated via stopAnalyze(), using the global init configuration or a per-call override on stopAnalyze().

1import { CloudValidationsConfig, ReportStoredOptionsBuilder } from '@evinced/wdio-mobile-sdk';
2
3// 1. Enable cloud globally:
4wdioSdk.setOptions({
5    cloudValidations: CloudValidationsConfig.enabled()
6});
7
8// 2. Start continuous analysis
9await wdioSdk.startAnalyze();
10
11// 3. Navigate your app...
12// ...interactions...
13
14// 4. Stop and collect all reports (cloud enabled per global config):
15const reports = await wdioSdk.stopAnalyze();
16
17// Or stop with a per-call override:
18const reportsWithOverride = await wdioSdk.stopAnalyze(
19    new ReportStoredOptionsBuilder()
20        .withCloudValidations(CloudValidationsConfig.enabled())
21        .build()
22);

Reading cloud validation results

Identifying Meaningful Heading issues

Cloud-based issues appear in the report alongside local issues. Filter by type:

1import { IssueTypeId } from '@evinced/wdio-mobile-sdk';
2
3const meaningfulHeadingIssues = report.elements.flatMap((element) =>
4    (element.issues ?? []).filter(
5        (issue) => issue.issueType?.id === IssueTypeId.MEANINGFUL_HEADING
6    )
7);

The needsReview flag

AI-generated findings set needsReview = true on the issue. Query them with getNeedsReviewIssues(report) and hasNeedsReviewIssues(report). getIssues(report) and hasIssues(report) return the issues that count for automation, including shouldAssert.

1import { getIssues, getNeedsReviewIssues, hasNeedsReviewIssues } from '@evinced/wdio-mobile-sdk';
2
3const reviewIssues = getNeedsReviewIssues(report);
4const includesReviewIssues = hasNeedsReviewIssues(report);
5
6const deterministicIssues = getIssues(report).filter((issue) => issue.needsReview !== true);

Needs Review mode

Set needsReviewConfig.mode on init options or setOptions(). The default is NeedsReviewMode.ENABLED.

1import { NeedsReviewMode } from '@evinced/wdio-mobile-sdk';
2
3wdioSdk.setOptions({
4    needsReviewConfig: { mode: NeedsReviewMode.REPORT_ONLY }
5});

shouldAssert defaults to false. When it is true and the mode is ENABLED, Meaningful Heading issues fail the scan.

Per-validation status in JSON reports

The JSON report includes a validationStatuses array showing whether each validation ran or produced an error:

1{
2  "validationStatuses": [
3    {
4      "name": "Meaningful Heading",
5      "ai": true,
6      "status": "ran"
7    }
8  ]
9}

When a cloud error occurs, the entry shows the error code and message instead:

1{
2  "validationStatuses": [
3    {
4      "name": "Meaningful Heading",
5      "ai": true,
6      "status": "error",
7      "errorCode": "cloudValidationsTimeout",
8      "errorMessage": "A cloud validation run timed out."
9    }
10  ]
11}

Error codes and statuses

Cloud validation errors surface in two distinct ways depending on your failOnError setting.

When failOnError = false (Default)

The test does not throw an exception. Instead, the error is recorded in the validationStatuses array of the JSON report, with a camelCase errorCode string value. These codes exist only as strings in the report file.

When failOnError = true (strict mode)

The SDK throws a generic Error. The message is prefixed with [Evinced SDK] Validation failed: and contains the engine text. Typical messages include:

• "[Evinced SDK] Validation failed: Authentication failed for cloud validations. Please check your credentials."
• "[Evinced SDK] Validation failed: Could not connect to the cloud validations backend."
• "[Evinced SDK] Validation failed: A cloud validation run timed out."
• "[Evinced SDK] Validation failed: Access denied for cloud validations. Please check your permissions."
• "[Evinced SDK] Validation failed: An unexpected error occurred while running cloud validations."

Catch pattern:

1try {
2    const report = await wdioSdk.report();
3} catch (error) {
4    const message = error instanceof Error ? error.message : String(error);
5    console.error('Cloud validation failed:', message);
6}

Timeout configuration constraints:

CloudValidationsConfig accepts a finite timeoutSeconds greater than 0 and at most 600. A value of 0, a negative value, or a value above 600 throws immediately when the config is created. A value from 1 to 19 is accepted by the config object and then rejected by the engine at scan time, regardless of failOnError.

Migration guide

Upgrading from static-only to cloud + static validations

Step 1 — Update your SDK to a version that supports cloud validations (see release notes).

Step 2 — Verify credentials. Cloud validations require online credentials:

1// Required — online credentials only:
2wdioSdk.setupCredentials('your-service-account-id', 'your-api-key');

Step 3 — Enable cloud globally in your test setup:

1import { CloudValidationsConfig } from '@evinced/wdio-mobile-sdk';
2
3before(async () => {
4    wdioSdk.setupCredentials(SERVICE_ACCOUNT_ID, API_KEY);
5    wdioSdk.setOptions({
6        cloudValidations: CloudValidationsConfig.enabled()
7    });
8});

Step 4 — Decide your AI assertion strategy. The SDK gives you two controls to work with:

• Use failOnError on CloudValidationsConfig to decide whether a cloud call failure should throw or fall back silently.
• Use getNeedsReviewIssues(report) / hasNeedsReviewIssues(report) to identify AI-generated findings and handle them differently from deterministic issues. With the default mode (NeedsReviewMode.ENABLED), shouldAssert: true treats those findings as failures.

Example — separating deterministic and AI findings:

1import { getIssues, getNeedsReviewIssues } from '@evinced/wdio-mobile-sdk';
2
3const report = await wdioSdk.report({ shouldAssert: false });
4
5const reviewIssues = getNeedsReviewIssues(report);
6const deterministicIssues = getIssues(report).filter((issue) => issue.needsReview !== true);

How you act on each group — gating CI, logging, separating pipelines — is your team's choice.

Step 5 — Adjust CI timeouts. Each report() call may now take up to 25 seconds (default) longer. Consider a separate CI job for cloud-enabled scans.

Step 6 — Check firewall/proxy rules. Ensure your CI agents can reach Evinced cloud endpoints over HTTPS.

Troubleshooting

Cloud issues not appearing in the report

1. Confirm CloudValidationsConfig.enabled() is set on init options before or via setOptions().
2. Verify you are using online credentials, not offline tokens.
3. Check validationStatuses in the JSON report — if status is "error", the error code will indicate the root cause.
4. Ensure your network/firewall allows outbound HTTPS to Evinced cloud endpoints.

Error: "Could not connect to the cloud validations backend"

(failOnError = true; JSON report shows "errorCode": "cloudValidationsConnect")

• The test agent cannot reach the cloud backend over HTTPS.
• Check firewall rules, proxy settings, and VPN configuration.
• Fallback: set failOnError = false (default) to continue with local results while investigating.

Error: "Authentication failed for cloud validations"

(failOnError = true; JSON report shows "errorCode": "cloudValidationsAuth")

• The serviceAccountId or apiKey is incorrect, or offline credentials were used.
• Offline credentials are not supported for cloud validations.
• Verify credentials in the Evinced Hub; ensure setupCredentials() is called before enabling cloud validations.

Error: "A cloud validation run timed out"

(failOnError = true; JSON report shows "errorCode": "cloudValidationsTimeout")

• The cloud response did not arrive within timeoutSeconds.
• Increase timeoutSeconds: CloudValidationsConfig.enabled(60).
• Run in a lower-latency network or check Evinced service status.

Error: "timeout is under the limit"

Setting timeoutSeconds from 1 to 19 causes an error thrown at scan time (report() / reportStored() / stopAnalyze()), regardless of failOnError. CloudValidationsConfig accepts that value; the engine rejects it before the cloud request.

Actual message:

• "[Evinced SDK] Validation failed: The selected timeout (N seconds) for cloud validations is under the minimum timeout: 20 seconds"

A value of 0, a negative value, or a value above 600 throws earlier, when the config is created:

• "[Evinced SDK] cloudValidations timeoutSeconds must be a finite number greater than 0 and at most 600, got N"

Fix: use a value from 20 through 600.

Invalid cloudValidations config

• Pass a CloudValidationsConfig instance (or a plain object with optional enabled, timeoutSeconds, and failOnError fields).
• To explicitly disable, use new CloudValidationsConfig().setEnabled(false) or new CloudValidationsConfig(false).
• Remember that a per-call override fully replaces init config for that call.

API summary

API

EvincedWdioMobileSdk

constructor(initOptions?: Partial<EvincedWdioMobileSdkOptions>)

Creates an EvincedWdioMobileSdk instance and initializes it according to the options given. In case of no options provided, a default configuration will be applied.

Example of setting a custom directory for JSON/HTML files generated by the SDK:

1const options = { outputDir: './my-a11y-reports' };
2const wdioSdk = new EvincedWdioMobileSdk(options);

setOptions(options: Partial<EvincedWdioMobileSdkOptions>): void

Works the same as initOptions in constructor.

setReportNameAsTestName(testContext: any, option?: ReportNameOption): void

This method was created in order to be able to name the final report in the same way as the name of the test in which this report was created.

Example

1describe('DriverIO - report name as test name', () =\> {
2    it('Specific test info', async function () {
3    wdioSdk.setReportNameAsTestName(this);
4    let report = await wdioSdk.report();
5    // any assert you want
6  });
7});

In this method we three have options:

addReportCallInfo(testContext: any): void

You can use this method to add data about your Mocha test in the report. This includes which line the report method was called called, test method name and test name.

Example of test and method usage:

1describe('WebdriverIO - specific test info', () =\> {
2  it('Specific test info', async function () {
3    wdioSdk.addReportCallInfo(this);
4    let report = await wdioSdk.report();
5    // any assert you want
6  });
7});

setupCredentials(serviceAccountId: string, apiKey: string): boolean

A method to add credentials confirming the validity of the user's license. It accepts the following arguments:

• serviceAccountId - Evinced service account ID
• apiKey - Evinced API key

Returns a boolean flag indicating the success of the operation - if it is false there is something wrong with either validity of the license or with the checking infrastructure. See logs for more detailed output.

setupOfflineCredentials(serviceAccountId: string, accessToken: string): boolean

A method to add credentials confirming the validity of the user's license with an offline token. It accepts the following arguments:

• serviceAccountId - Evinced service account ID
• accessToken - Evinced access token

Returns a boolean flag indicating the success of the operation - if it is false there is something wrong with either validity of the license or with the checking infrastructure. See logs for more detailed output.

async report(options?: ReportOptions | ReportOptionsBuilder): Promise<Report>

Deprecated signature: report(shouldAssert?: boolean, evincedConfig?: EvincedConfig, upload?: string, customMetadata?: Record<string, string>, baselineConfig?: BaselineConfig): Promise<Report>

Generates accessibility report for the current state of the application. Returns a Report instance to allow users to perform custom assertions on their own.

Parameters:

• options - Either a ReportOptionsBuilder instance (recommended) or a plain ReportOptions object. The builder provides type safety and convenient method chaining. Supports cloudValidations for Cloud-Based Validations (per-call override fully replaces init config).

Note: The old positional parameter API (report(shouldAssert, evincedConfig, upload, customMetadata, baselineConfig)) is deprecated. Please use ReportOptionsBuilder or plain objects instead.

This method always writes HTML and JSON files to the configured directory.

Example usage:

1// Using builder (recommended)
2import { ReportOptionsBuilder } from '@evinced/wdio-mobile-sdk';
3const a11yReport = await wdioSdk.report(
4    new ReportOptionsBuilder()
5        .shouldAssert(true)
6        .build()
7);
8
9// Using plain object
10const a11yReport = await wdioSdk.report({
11    shouldAssert: true
12});
13
14// DEPRECATED: Old positional parameter API
15const a11yReport = await wdioSdk.report(false);

async analyze(evincedConfig?: EvincedConfig): Promise<void>

Collects an accessibility snapshot of the current application state and puts it into internal in-memory storage. This method is meant to be used in conjunction with EvincedWdioSdk.reportStored() for performing actual assertions against the content of this storage. Optional parameter is evincedConfig, which allows you to add filters by issue. More information about evincedConfig below.

Example usage:

1await $$(`-ios predicate string:${myElementSelector}`);
2// waiting until certain elements appears on the screen
3await wdioSdk.analyze();

async reportStored(options?: ReportStoredOptions | ReportStoredOptionsBuilder): Promise<Report[]>

Deprecated signature: reportStored(shouldAssert: boolean = false, upload?: string, customMetadata?: Record<string, string>, baselineConfig?: BaselineConfig): Promise<Report[]>

Generates a list of accessibility reports, one for each accessibility snapshot collected by EvincedWdioSdk.analyze(). Just like EvincedWdioSdk.report() this method may either perform simple assertion on its own (throwing an exception if there is at least one report with issues) or allow users to define their own assertions on the returned Report objects.

Parameters:

• options - Either a ReportStoredOptionsBuilder instance (recommended) or a plain ReportStoredOptions object. Supports cloudValidations for Cloud-Based Validations (per-call override fully replaces init config).

Note: The old positional parameter API (reportStored(shouldAssert, upload, customMetadata, baselineConfig)) is deprecated. Please use ReportStoredOptionsBuilder or plain objects instead.

This method always writes HTML and JSON files to the configured directory. Both of the files contain combined information about all of the application states collected. For more information regarding the HTML and JSON reports as well as the Report object itself, please see our detailed Mobile Reports page.

Example usage:

1// Using builder (recommended)
2import { ReportStoredOptionsBuilder } from '@evinced/wdio-mobile-sdk';
3after(async () => {
4  const a11yReports = await wdioSdk.reportStored(
5      new ReportStoredOptionsBuilder()
6          .shouldAssert(false)
7          .build()
8  );
9  const atLeastNonEmptyReportFound = a11yReports.some((report) =>
10      report.elements.length !== 0);
11  if (atLeastNonEmptyReportFound) {
12    throw new Error(`My app is not accessible!`);
13  }
14});
15
16// Using plain object
17after(async () => {
18  const a11yReports = await wdioSdk.reportStored({
19      shouldAssert: false
20  });
21});
22
23// DEPRECATED: Old positional parameter API
24after(async () => {
25  const a11yReports = await wdioSdk.reportStored(false);
26});

clearStored(): void

Removes all of the accessibility snapshots previously collected by EvincedWdioSdk.analyze() calls.

async startAnalyze(evincedConfig?: EvincedConfig)

This function starts the SDK in continuous mode. It allows you to simply start monitoring the screen at the beginning of the test, after which if you write just clicks through the web driver, the SDK will register all the clicks and create a separate scan for each of them. As if we were running analyze method on every click on the screen. To end this mode, we need to call stopAnalyze - more on that later.

Example:

1describe('WebDriverIO - continuous mode', () =\> {
2  beforeEach(async () =\> {
3    await wdioSdk.startAnalyze();
4  });
5  it('Continuous mode', async () =\> {
6    const buttonList = await $('id=buttonList');
7    await buttonList.click();
8    const buttonAccessible_name = await $('id=buttonAccessible_name');
9    await buttonAccessible_name.click();
10    const reports = await wdioSdk.stopAnalyze();
11  });
12});

The example shown above will return a report with 3 scans. The first one will be from the home screen that the app will load from, and the next two after each click.

There is support for the driver.action('pointer') trigger that you could use instead of element.click():

Example:

1describe('WebDriverIO - continuous mode', () =\> {
2  beforeEach(async () =\> {
3    await wdioSdk.startAnalyze();
4  });
5  it('Continuous mode', async () =\> {
6    const buttonList = await $('id=buttonList');
7    await driver.action('pointer', { pointerType: 'touch' })
8            .move({duration: 0, origin: buttonList })
9            .down()
10            .up()
11            .perform();
12    const buttonAccessible_name = await $('id=buttonAccessible_name');
13    await driver.action('pointer', { pointerType: 'touch' })
14            .move({duration: 0, origin: buttonAccessible_name })
15            .down()
16            .up()
17            .perform();
18    const reports = await wdioSdk.stopAnalyze();
19  });
20});

There is also support for the element.touchAction('tap') and the driver.touchAction({'tap'}) triggers that you could use instead if the test logic requires that.

[IMPORTANT] The .touchAction() API is only supported by the WebdriverIO of version 8 and below. If you are using WDIO of version 9 and above consider using .click() or .action('pointer') APIs for interactions with the elements on the screen.

Example:

1describe('WebDriverIO - continuous mode', () =\> {
2  beforeEach(async () =\> {
3    await wdioSdk.startAnalyze();
4  });
5  it('Continuous mode', async () =\> {
6    const buttonList = await $('id=buttonList');
7    await buttonList.touchAction('tap');
8    const buttonAccessible\_name = await $('id=buttonAccessible\_name');
9    await buttonAccessible\_name.touchAction('tap');
10  });
11});

Deprecated API

The old positional parameter API is deprecated. Migrate to using ReportOptionsBuilder (for report()) or ReportStoredOptionsBuilder (for reportStored() and stopAnalyze()) or plain objects.

Migration from report()

1// DEPRECATED: Old positional parameter API
2const report = await wdioSdk.report(false, undefined, undefined, {
3    isEnabled: true,
4    mode: 'compare'
5});
6
7// NEW: Using builder (recommended)
8import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
9const report = await wdioSdk.report(
10    new ReportOptionsBuilder()
11        .enableBaseline(BaselineMode.COMPARE)
12        .shouldAssert(false)
13        .build()
14);
15
16// NEW: Using plain object
17const report = await wdioSdk.report({
18    shouldAssert: false,
19    baselineConfig: {
20        isEnabled: true,
21        mode: 'compare'
22    }
23});

Migration from reportStored()

1// DEPRECATED: Old positional parameter API
2const reports = await wdioSdk.reportStored(false, undefined, undefined, {
3    isEnabled: true,
4    mode: 'compare'
5});
6
7// NEW: Using builder (recommended)
8const reports = await wdioSdk.reportStored(
9    new ReportStoredOptionsBuilder()
10        .shouldAssert(false)
11        .enableBaseline()
12        .build()
13);
14
15// NEW: Using plain object
16const reports = await wdioSdk.reportStored({
17    shouldAssert: false,
18    baselineConfig: {
19        isEnabled: true,
20        mode: 'compare'
21    }
22});

Migration from stopAnalyze()

1// DEPRECATED: Old positional parameter API
2const reports = await wdioSdk.stopAnalyze(false, undefined, undefined, {
3    isEnabled: true,
4    mode: 'compare'
5});
6
7// NEW: Using builder (recommended)
8const reports = await wdioSdk.stopAnalyze(
9    new ReportStoredOptionsBuilder()
10        .shouldAssert(false)
11        .enableBaseline(BaselineMode.COMPARE)
12        .build()
13);
14
15// NEW: Using plain object
16const reports = await wdioSdk.stopAnalyze({
17    shouldAssert: false,
18    baselineConfig: {
19        isEnabled: true,
20        mode: 'compare'
21    }
22});

or:

Example:

1describe('WebDriverIO - continuous mode', () =\> {
2  beforeEach(async () =\> {
3    await wdioSdk.startAnalyze();
4  });
5  it('Continuous mode', async () =\> {
6    const buttonList = await $('id=buttonList');
7    await driver.touchAction({
8        action: 'tap',
9        element: buttonList
10    });
11    const buttonAccessible\_name = await $('id=buttonAccessible\_name');
12    await driver.touchAction({
13        action: 'tap',
14        element: buttonAccessible\_name
15    });
16    const reports = await wdioSdk.stopAnalyze();
17  });
18});

async stopAnalyze(options?: ReportStoredOptions | ReportStoredOptionsBuilder): Promise<Report[]>

Deprecated signature: stopAnalyze(shouldAssert: boolean = false, upload?: string, customMetadata?: Record<string, string>, baselineConfig?: BaselineConfig): Promise<Report[]>

The second method is responsible for continuous mode. This method stops work in the continuous mode and returns the reports that were created during the work of the SDK in this mode. All scans are recorded and returned exactly as with reportStored.

Parameters:

• options - Either a ReportStoredOptionsBuilder instance (recommended) or a plain ReportStoredOptions object. Supports cloudValidations for Cloud-Based Validations (per-call override fully replaces init config).

Note: The old positional parameter API (stopAnalyze(shouldAssert, upload, customMetadata, baselineConfig)) is deprecated. Please use ReportStoredOptionsBuilder or plain objects instead.

Example usage:

1// Using builder (recommended)
2import { ReportStoredOptionsBuilder } from '@evinced/wdio-mobile-sdk';
3const reports = await wdioSdk.stopAnalyze(
4    new ReportStoredOptionsBuilder()
5        .shouldAssert(false)
6        .build()
7);
8
9// Using plain object
10const reports = await wdioSdk.stopAnalyze({
11    shouldAssert: false
12});
13
14// DEPRECATED: Old positional parameter API
15const reports = await wdioSdk.stopAnalyze(false);

ReportOptionsBuilder

The ReportOptionsBuilder class provides a fluent, type-safe API for constructing report options. It's the recommended way to configure report options, including baseline comparison settings.

Constructor

1new ReportOptionsBuilder()

Creates a new ReportOptionsBuilder instance.

Methods

shouldAssert(assert: boolean = true): ReportOptionsBuilder

Configures whether the SDK should automatically throw an error if issues are found.

• assert - If true, the SDK will throw an error if any issues are detected. Default: true

Example:

1new ReportOptionsBuilder()
2    .shouldAssert(true)
3    .build()

enableBaseline(mode?: BaselineMode): ReportOptionsBuilder

Enables baseline comparison for the report.

• mode - Optional baseline mode. Can be BaselineMode.RECORD, BaselineMode.COMPARE, or BaselineMode.DISABLED. If not provided, defaults to BaselineMode.COMPARE.

Example:

1import { ReportOptionsBuilder, BaselineMode } from '@evinced/wdio-mobile-sdk';
2
3new ReportOptionsBuilder()
4    .enableBaseline(BaselineMode.COMPARE)
5    .build()

failTestOnNewIssues(shouldFail: boolean = true): ReportOptionsBuilder

Configures whether the test should fail when new issues are detected that do not exist in the baseline file.

• shouldFail - If true, the SDK will fail the test if new issues are detected. Default: true

Example:

1new ReportOptionsBuilder()
2    .enableBaseline(BaselineMode.COMPARE)
3    .failTestOnNewIssues(true)
4    .build()

failTestOnBaselineComparisonError(shouldFail: boolean = true): ReportOptionsBuilder

Configures whether the test should fail when the baseline comparison encounters an error (e.g., invalid baseline file or mismatched number of scans).

• shouldFail - If true, the SDK will fail the test on comparison errors. Default: true

Example:

1new ReportOptionsBuilder()
2    .enableBaseline(BaselineMode.COMPARE)
3    .failTestOnBaselineComparisonError(true)
4    .build()

withCustomBaselineFileName(fileName: string): ReportOptionsBuilder

Sets a custom baseline file name or full path. In COMPARE mode the SDK uses this file for comparison instead of inferring the path from test context. In RECORD mode the baseline is saved to this file name or path. Useful when calling from lifecycle hooks or when using a custom location.

• fileName - The baseline file name or path (relative or absolute).

Example:

1new ReportOptionsBuilder()
2    .enableBaseline(BaselineMode.COMPARE)
3    .withCustomBaselineFileName('./custom/path/my-baseline.json')
4    .build()

withBaselineConfig(config: Partial<BaselineConfig>): ReportOptionsBuilder

Configures additional baseline comparison options. Use this method for setting ignoreFilters.

• config - A partial BaselineConfig object with properties like:
  • ignoreFilters?: BaselineIgnoreFilter[] - Array of ignore filters

Note: For common options like failTestOnNewIssues, failTestOnBaselineComparisonError, and customBaselineFileName, use the dedicated builder methods above instead of this method.

Example:

1import { ReportOptionsBuilder, BaselineMode, BaselineIgnoreFilterBuilder, IssueTypeId } from '@evinced/wdio-mobile-sdk';
2
3new ReportOptionsBuilder()
4    .enableBaseline(BaselineMode.COMPARE)
5    .failTestOnNewIssues(true)
6    .failTestOnBaselineComparisonError(true)
7    .withBaselineConfig({
8        ignoreFilters: [
9            new BaselineIgnoreFilterBuilder()
10                .withComment('Known issue')
11                .withIssueTypes([IssueTypeId.COLOR_CONTRAST])
12                .build()
13        ]
14    })
15    .build()

withCloudValidations(config: CloudValidationsConfig): ReportOptionsBuilder

Sets a per-call Cloud-Based Validations override for report(). The provided config fully replaces the init cloudValidations value for this call.

• config - A CloudValidationsConfig instance (for example CloudValidationsConfig.enabled() or CloudValidationsConfig.enabled(120, true))

Example:

1import { ReportOptionsBuilder, CloudValidationsConfig } from '@evinced/wdio-mobile-sdk';
2
3new ReportOptionsBuilder()
4    .shouldAssert(false)
5    .withCloudValidations(CloudValidationsConfig.enabled(120))
6    .build()

build(): ReportOptions

Builds and returns the ReportOptions object that can be passed to report().

Note: For reportStored() and stopAnalyze() use ReportStoredOptionsBuilder instead; it exposes the same baseline methods (e.g. enableBaseline, withCustomBaselineFileName, failTestOnNewIssues, withIgnoreFilter) and withCloudValidations, but no withEvincedConfig.

Example:

1const options = new ReportOptionsBuilder()
2    .enableBaseline(BaselineMode.COMPARE)
3    .shouldAssert(false)
4    .build();
5
6const report = await wdioSdk.report(options);

BaselineIgnoreFilterBuilder

The BaselineIgnoreFilterBuilder class provides a fluent, type-safe API for constructing baseline ignore filters.

Constructor

1new BaselineIgnoreFilterBuilder()

Creates a new BaselineIgnoreFilterBuilder instance.

Methods

withComment(comment: string): BaselineIgnoreFilterBuilder

Sets a descriptive comment explaining why issues matching this filter should be ignored.

• comment - The comment string describing the reason for ignoring.

Example:

1new BaselineIgnoreFilterBuilder()
2    .withComment('Known issue - JIRA-1234')
3    .build()

withIssueTypes(issueTypes: IssueTypeId[]): BaselineIgnoreFilterBuilder

Filters issues by their types.

• issueTypes - Array of issue type IDs (e.g. IssueTypeId.COLOR_CONTRAST, IssueTypeId.TAPPABLE_AREA). Import IssueTypeId from @evinced/wdio-mobile-sdk.

Example:

1import { BaselineIgnoreFilterBuilder, IssueTypeId } from '@evinced/wdio-mobile-sdk';
2
3new BaselineIgnoreFilterBuilder()
4    .withComment('Known color contrast issues')
5    .withIssueTypes([IssueTypeId.COLOR_CONTRAST])
6    .build()

withSeverities(severities: SeverityId[]): BaselineIgnoreFilterBuilder

Filters issues by their severity levels.

• severities - Array of severity IDs (e.g. SeverityId.MINOR, SeverityId.MODERATE). Import SeverityId from @evinced/wdio-mobile-sdk.

Example:

1import { BaselineIgnoreFilterBuilder, SeverityId } from '@evinced/wdio-mobile-sdk';
2
3new BaselineIgnoreFilterBuilder()
4    .withComment('Minor issues acceptable')
5    .withSeverities([SeverityId.MINOR])
6    .build()

withExternalElementIds(elementIds: string[]): BaselineIgnoreFilterBuilder

Filters issues by specific element IDs (accessibility identifiers or resource IDs).

• elementIds - Array of element identifier strings.

Example:

1new BaselineIgnoreFilterBuilder()
2    .withComment('Specific elements with known issues')
3    .withExternalElementIds(['login-button', 'submit-btn'])
4    .build()

build(): BaselineIgnoreFilter

Builds and returns the BaselineIgnoreFilter object that can be used in ignoreFilters array.

Example:

1import { IssueTypeId, SeverityId } from '@evinced/wdio-mobile-sdk';
2
3const filter = new BaselineIgnoreFilterBuilder()
4    .withComment('Known issue - JIRA-1234')
5    .withIssueTypes([IssueTypeId.COLOR_CONTRAST])
6    .withSeverities([SeverityId.MINOR])
7    .build();
8
9const report = await wdioSdk.report(
10    new ReportOptionsBuilder()
11        .enableBaseline(BaselineMode.COMPARE)
12        .withBaselineConfig({
13            ignoreFilters: [filter]
14        })
15        .build()
16);

EvincedWdioMobileSdkOptions

outputDir: string = 'evinced-reports'

A path to directory where output files from WebdriverIO SDK should be stored. Either absolute or relative path may be used. If the directory does not exist, it will be created automatically.

cloudValidations?: CloudValidationsConfig

Global defaults for Cloud-Based Validations applied to report(), reportStored(), and stopAnalyze(). Disabled by default (new CloudValidationsConfig(false)). Per-call options fully replace this value for that call.

Example:

1import { CloudValidationsConfig } from '@evinced/wdio-mobile-sdk';
2
3wdioSdk.setOptions({
4    cloudValidations: CloudValidationsConfig.enabled() // 25 s timeout, fail-open
5});

needsReviewConfig?: { mode?: NeedsReviewMode }

Controls how Needs Review issues (including Meaningful Heading) are exposed. Default mode is NeedsReviewMode.ENABLED. See Needs Review mode.

Example:

1import { NeedsReviewMode } from '@evinced/wdio-mobile-sdk';
2
3wdioSdk.setOptions({
4    needsReviewConfig: { mode: NeedsReviewMode.REPORT_ONLY }
5});

complianceMapping?: ComplianceMapping

Configures which compliance standards are attached to reported issues. When enabled, issues in reports can include success criteria for the selected standards (e.g. WCAG, Section 508, EN 301 549 / EAA).

Properties:

Example – WCAG only (default):

1// Default: WCAG only (no need to set explicitly)
2const wdioSdk = new EvincedWdioMobileSdk();

Example – WCAG + Section 508 + EAA:

1import { EvincedWdioMobileSdk } from '@evinced/wdio-mobile-sdk';
2
3const wdioSdk = new EvincedWdioMobileSdk({
4  complianceMapping: {
5    wcagEnabled: true,
6    section508Enabled: true,
7    eaaEnabled: true
8  }
9});

rulesConfig: RuleConfig[];

RuleConfig allows to change the accessibility check for different rules. By default, the value is empty.

Example:

Disable tappable area issues:

1const wdioSdk = new EvincedWdioMobileSdk();
2wdioSdk.setOptions({
3  rulesConfig: [{
4    name: { id: "69ab72aa-59be-43ad-b622-4bb686aace81"},
5    enabled: false
6  }]
7});