Implementation:Webdriverio Webdriverio BrowserStack Service

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

Overview

The BrowserstackService class is the core per-worker BrowserStack service that manages session lifecycle, test observability, accessibility scanning, Percy visual testing, and AI self-healing within each browser session.

Description

BrowserstackService implements Services.ServiceInstance and runs in each worker process. It orchestrates the InsightsHandler, AccessibilityHandler, and PercyHandler across test lifecycle hooks. The service manages session naming, session status updates (passed/failed with reason), annotation of test/scenario/step names, and BrowserStack API calls via executeScript('browserstack_executor: ...'). It supports mocha, jasmine, and cucumber frameworks, tracks failure reasons separately for hooks vs test steps (supporting the ignoreHooksStatus option), and handles session reloading for retries.

Usage

This service runs automatically in every worker process when the browserstack service is configured. It connects to the BrowserStack session created by BrowserstackLauncherService and manages the session through each test's lifecycle.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-browserstack-service/src/service.ts
Lines: 1-857

Signature

export default class BrowserstackService implements Services.ServiceInstance {
    constructor(
        options: BrowserstackConfig & Options.Testrunner,
        private _caps: Capabilities.ResolvedTestrunnerCapabilities,
        private _config: Options.Testrunner
    )

    async beforeSession(config: Omit<Options.Testrunner, 'capabilities'>, capabilities: WebdriverIO.Capabilities): Promise<void>
    async before(caps: Capabilities.ResolvedTestrunnerCapabilities, specs: string[], browser: WebdriverIO.Browser): Promise<void>
    async beforeSuite(suite: Frameworks.Suite): Promise<void>
    async beforeHook(test: Frameworks.Test | CucumberHook, context: unknown): Promise<void>
    async afterHook(test: Frameworks.Test | CucumberHook, context: unknown, result: Frameworks.TestResult): Promise<void>
    async beforeTest(test: Frameworks.Test): Promise<void>
    async afterTest(test: Frameworks.Test, context: never, results: Frameworks.TestResult): Promise<void>
    async after(result: number): 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 onReload(oldSessionId: string, newSessionId: string): Promise<void>
}

Import

import BrowserstackService from './service.js'

I/O Contract

Inputs

Name	Type	Required	Description
options	`BrowserstackConfig & Options.Testrunner`	Yes	Service configuration merged with defaults (setSessionName, setSessionStatus, etc.)
_caps	`Capabilities.ResolvedTestrunnerCapabilities`	Yes	Resolved capabilities for the session
_config	`Options.Testrunner`	Yes	WebdriverIO testrunner configuration with user, key, framework, and cucumberOpts

Outputs

Name	Type	Description
Session status update	BrowserStack API call	Updates session name and status (passed/failed) with failure reasons
Annotations	BrowserStack executor	Annotates the session with test, scenario, and step information
InsightsHandler events	`TestData`	Test observability events dispatched through InsightsHandler
Accessibility scans	A11y results	Triggered through AccessibilityHandler at test boundaries

Usage Examples

Service configuration in wdio.conf

export const config = {
    services: [
        ['browserstack', {
            setSessionName: true,
            setSessionStatus: true,
            preferScenarioName: true,
            testObservability: true,
            accessibility: true,
            selfHeal: true,
            testObservabilityOptions: {
                ignoreHooksStatus: true
            }
        }]
    ]
}

Session naming with custom format

export const config = {
    services: [
        ['browserstack', {
            setSessionName: true,
            sessionNameFormat: (config, caps, suiteTitle, testTitle) => {
                return `${suiteTitle} > ${testTitle}`
            }
        }]
    ]
}

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment