Implementation:Webdriverio Webdriverio AccessibilityHandler Class

Knowledge Sources	Webdriverio_Webdriverio
Domains	Accessibility_Testing, BrowserStack
Last Updated	2026-02-12 00:00 GMT

Overview

The AccessibilityHandler class manages accessibility scanning automation for WebdriverIO tests running on BrowserStack, providing hooks for mocha and cucumber frameworks.

Description

The _AccessibilityHandler class (exported as AccessibilityHandler via the o11yClassErrorHandler wrapper) automates accessibility scanning during test execution. It adds custom browser commands (getAccessibilityResultsSummary, getAccessibilityResults, performScan, startA11yScanning, stopA11yScanning) and wraps existing browser commands to trigger scans automatically. The handler supports both web and app accessibility automation sessions, validates platform capabilities, and manages per-session and per-test scan state through internal metadata maps.

Usage

Use this class when you need to integrate BrowserStack Accessibility Automation into your WebdriverIO test suite. It is instantiated by the BrowserstackService during the before hook and invoked at each test lifecycle boundary (beforeTest, afterTest, beforeScenario, afterScenario).

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-browserstack-service/src/accessibility-handler.ts
Lines: 79-518

Signature

class _AccessibilityHandler {
    constructor(
        private _browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
        _capabilities: Capabilities.ResolvedTestrunnerCapabilities,
        _options: BrowserstackConfig & BrowserstackOptions,
        private isAppAutomate: boolean,
        _config: Options.Testrunner,
        private _framework?: string,
        _accessibilityAutomation?: boolean | string,
        _turboscale?: boolean | string,
        _accessibilityOpts?: AccessibilityOptions
    )

    setSuiteFile(filename: string): void
    async before(sessionId: string): Promise<void>
    async beforeTest(suiteTitle: string | undefined, test: Frameworks.Test): Promise<void>
    async afterTest(suiteTitle: string | undefined, test: Frameworks.Test): Promise<void>
    async beforeScenario(world: ITestCaseHookParameter): Promise<void>
    async afterScenario(world: ITestCaseHookParameter): Promise<void>
}

Import

import AccessibilityHandler from './accessibility-handler.js'

I/O Contract

Inputs

Name	Type	Required	Description
_browser	WebdriverIO.MultiRemoteBrowser	Yes	The browser instance to attach accessibility commands to
_capabilities	`Capabilities.ResolvedTestrunnerCapabilities`	Yes	Resolved capabilities for the current session
_options	`BrowserstackConfig & BrowserstackOptions`	Yes	BrowserStack service configuration options
isAppAutomate	`boolean`	Yes	Whether the session is an App Automate session
_config	`Options.Testrunner`	Yes	WebdriverIO testrunner configuration
_framework	`string`	No	Test framework name (mocha or cucumber)
_accessibilityAutomation	string	No	Whether accessibility automation is enabled
_turboscale	string	No	Whether TurboScale mode is active
_accessibilityOpts	`AccessibilityOptions`	No	Additional accessibility options (include/exclude tags, autoScanning)

Outputs

Name	Type	Description
browser.getAccessibilityResultsSummary	`() => Promise<Record<string, unknown>>`	Custom command returning a11y results summary
browser.getAccessibilityResults	`() => Promise<Array<Record<string, unknown>>>`	Custom command returning detailed a11y results
browser.performScan	undefined>	Custom command to manually trigger an a11y scan
browser.startA11yScanning	`() => Promise<void>`	Custom command to start accessibility scanning
browser.stopA11yScanning	`() => Promise<void>`	Custom command to stop accessibility scanning

Usage Examples

Instantiating AccessibilityHandler in BrowserstackService

this._accessibilityHandler = new AccessibilityHandler(
    this._browser,
    this._caps,
    this._options,
    this._isAppAutomate(),
    this._config,
    this._config.framework,
    this._accessibility,
    this._turboScale,
    this._options.accessibilityOptions
)
await this._accessibilityHandler.before(sessionId)

Running a manual scan during a test

// Inside a test, after AccessibilityHandler has been initialized
const scanResults = await browser.performScan()
const summary = await browser.getAccessibilityResultsSummary()
const fullResults = await browser.getAccessibilityResults()

Controlling scanning within a test

// Start scanning for a specific test section
await browser.startA11yScanning()
// ... perform actions ...
await browser.stopA11yScanning()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment