Implementation:Webdriverio Webdriverio BrowserStack Launcher

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

Overview

The BrowserstackLauncherService class is the main BrowserStack service launcher that orchestrates setup, app uploads, capability management, Percy visual testing, accessibility, local tunnel, AI healing, and test orchestration during the prepare/complete lifecycle phases.

Description

BrowserstackLauncherService implements the Services.ServiceInstance interface and runs in the main (launcher) process. During construction, it normalizes configuration (testReporting/testObservability aliases, environment variables), patches capabilities with the service version, and extracts build metadata. The onPrepare method handles launching the test session with BrowserStack, setting up Percy, uploading apps, configuring accessibility options, starting the BrowserStack Local tunnel, and optionally running test orchestration (smart selection). The onComplete method handles stopping the build, uploading service logs, stopping Percy, and tearing down the local tunnel.

Usage

This class is automatically instantiated by WebdriverIO when the browserstack service is configured. It runs before any workers are started (onPrepare), during worker creation (onWorkerStart), and after all tests complete (onComplete).

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-browserstack-service/src/launcher.ts
Lines: 70-1160

Signature

export default class BrowserstackLauncherService implements Services.ServiceInstance {
    browserstackLocal?: BrowserstackLocal

    constructor(
        private _options: BrowserstackConfig & BrowserstackOptions,
        capabilities: Capabilities.TestrunnerCapabilities,
        private _config: Options.Testrunner
    )

    async onWorkerStart(cid: string, caps: WebdriverIO.Capabilities): Promise<void>
    async onPrepare(config: Options.Testrunner, capabilities: Capabilities.TestrunnerCapabilities | WebdriverIO.Capabilities): Promise<void>
    async onComplete(): Promise<void>
    async setupPercy(options: BrowserstackConfig & Options.Testrunner, config: Options.Testrunner, bsConfig: UserConfig): Promise<void>
    async stopPercy(): Promise<void>
}

Import

import BrowserstackLauncherService from './launcher.js'

I/O Contract

Inputs

Name	Type	Required	Description
_options	`BrowserstackConfig & BrowserstackOptions`	Yes	BrowserStack service configuration including app, local, percy, accessibility, and observability settings
capabilities	`Capabilities.TestrunnerCapabilities`	Yes	Testrunner capabilities (array or multiremote object) to be patched with BrowserStack metadata
_config	`Options.Testrunner`	Yes	WebdriverIO testrunner configuration with user, key, specs, and framework details

Outputs

Name	Type	Description
Patched capabilities	`Capabilities.TestrunnerCapabilities`	Capabilities enriched with `bstack:options`, service version, app URL, build identifier, accessibility options, and testhub UUID
Process environment	`process.env`	Sets BROWSERSTACK_TESTHUB_UUID, BROWSERSTACK_TESTHUB_JWT, BROWSERSTACK_PERCY, and other environment variables
BrowserStack Local tunnel	`BrowserstackLocal`	Started local tunnel instance (if `browserstackLocal` is enabled)

Usage Examples

Configuring the service in wdio.conf

// wdio.conf.ts
export const config = {
    services: [
        ['browserstack', {
            browserstackLocal: true,
            testObservability: true,
            accessibility: true,
            percy: false,
            app: './path/to/app.apk',
            buildIdentifier: '${BUILD_NUMBER}'
        }]
    ]
}

Service lifecycle flow

// WebdriverIO internally calls:
// 1. constructor(options, capabilities, config)
// 2. onPrepare(config, capabilities) - launches build, uploads app, starts tunnel
// 3. onWorkerStart(cid, caps) - per worker (sets Percy best platform)
// 4. onComplete() - stops build, uploads logs, stops tunnel and Percy

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment