Implementation:Webdriverio Webdriverio InsightsHandler Class

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

Overview

The InsightsHandler class tracks test execution metadata for both mocha and cucumber frameworks, managing observability data that is sent to BrowserStack Test Reporting and Analytics.

Description

The _InsightsHandler class (exported as InsightsHandler via o11yClassErrorHandler) collects detailed test lifecycle data including test starts, finishes, hooks, cucumber steps, screenshots, HTTP commands, and console logs. It builds TestData objects with integrations metadata (browser, platform, session information) and dispatches them through the Listener singleton. The handler also maintains a static currentTest reference and supports CBT (cross-browser testing) data queuing for deferred session association.

Usage

Use this class when BrowserStack Test Reporting and Analytics (observability) is enabled. It is instantiated by BrowserstackService.before() and is called from service lifecycle hooks for every test event, browser command, and cucumber step.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-browserstack-service/src/insights-handler.ts
Lines: 47-980

Signature

class _InsightsHandler {
    public static currentTest: CurrentRunInfo
    public currentTestId: string | undefined
    public cbtQueue: Array<CBTData>

    constructor(
        private _browser: WebdriverIO.Browser | WebdriverIO.MultiRemoteBrowser,
        private _framework?: string,
        _userCaps?: Capabilities.ResolvedTestrunnerCapabilities,
        _options?: BrowserstackConfig & BrowserstackOptions
    )

    async before(): Promise<void>
    async beforeTest(test: Frameworks.Test): Promise<void>
    async afterTest(test: Frameworks.Test, result: Frameworks.TestResult): Promise<void>
    async browserCommand(commandType: string, args: BeforeCommandArgs | AfterCommandArgs, test?: Frameworks.Test | ITestCaseHookParameter): Promise<void>
    async beforeFeature(uri: string, feature: Feature): Promise<void>
    async beforeScenario(world: ITestCaseHookParameter): Promise<void>
    async afterScenario(world: ITestCaseHookParameter): Promise<void>
    async beforeStep(step: Frameworks.PickleStep, scenario: Pickle): Promise<void>
    async afterStep(step: Frameworks.PickleStep, scenario: Pickle, result: Frameworks.PickleResult): Promise<void>
    async beforeHook(test: Frameworks.Test | CucumberHook | undefined, context: unknown): Promise<void>
    async afterHook(test: Frameworks.Test | CucumberHook | undefined, result: Frameworks.TestResult): Promise<void>
    async sendCBTInfo(): Promise<void>
    public hasTestStepFailures(world: ITestCaseHookParameter): boolean
}

Import

import InsightsHandler from './insights-handler.js'

I/O Contract

Inputs

Name	Type	Required	Description
_browser	WebdriverIO.MultiRemoteBrowser	Yes	Browser instance for session metadata extraction
_framework	`string`	No	Test framework identifier (mocha, cucumber, jasmine)
_userCaps	`Capabilities.ResolvedTestrunnerCapabilities`	No	User-provided capabilities for integration metadata
_options	`BrowserstackConfig & BrowserstackOptions`	No	Service options including observability settings

Outputs

Name	Type	Description
TestData events	`TestData`	Dispatched through `Listener` for test start, finish, hook, log, screenshot, and CBT events
InsightsHandler.currentTest	`CurrentRunInfo`	Static reference to the currently executing test UUID and metadata

Usage Examples

Setting up InsightsHandler

this._insightsHandler = new InsightsHandler(
    this._browser,
    this._config.framework,
    this._caps,
    this._options
)
await this._insightsHandler.before()

Tracking mocha test events

// Called by BrowserstackService.beforeTest
await this._insightsHandler.beforeTest(test)

// Called by BrowserstackService.afterTest
await this._insightsHandler.afterTest(test, results)

Tracking cucumber scenario lifecycle

await this._insightsHandler.beforeFeature(uri, feature)
await this._insightsHandler.beforeScenario(world)
await this._insightsHandler.beforeStep(step, scenario)
await this._insightsHandler.afterStep(step, scenario, result)
await this._insightsHandler.afterScenario(world)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment