Implementation:Webdriverio Webdriverio Cloud Capabilities Config

Metadata

Field	Value
Page ID	Cloud_Capabilities_Config
Wiki	Webdriverio_Webdriverio
Type	Implementation (API Doc)
Domains	Testing, Cloud, Configuration
Knowledge Sources	Repo (https://github.com/webdriverio/webdriverio), Doc (https://webdriver.io/docs/browserstack-service), Doc (https://www.browserstack.com/docs/automate/selenium/getting-started/nodejs)
Related Principles	Principle: Cloud_Capabilities_Definition

Overview

Concrete configuration interface for cloud provider capabilities provided by WDIO cloud service packages. Cloud capabilities are defined using W3C capability objects augmented with vendor extensions. The BrowserstackConfig, SauceServiceConfig, and TestingbotOptions interfaces define the provider-specific configuration. These are used in the capabilities array and services configuration in wdio.conf.ts.

Description

Cloud capabilities are configured at two levels:

Capabilities level -- W3C capability objects with vendor-namespaced extensions (bstack:options, sauce:options, tb:options) define per-session browser and platform settings.
Service level -- Service configuration interfaces (BrowserstackConfig, SauceServiceConfig, TestingbotOptions) define cross-session settings like local tunneling, session naming behavior, test reporting, and accessibility automation.

Source

File	Lines	Description
`packages/wdio-browserstack-service/src/types.ts`	L62-212	`BrowserstackConfig` service configuration interface
`packages/wdio-sauce-service/src/types.ts`	L4-51	`SauceServiceConfig` service configuration interface
`packages/wdio-testingbot-service/src/types.ts`	L49-60	`TestingbotOptions` service configuration interface

BrowserStack Configuration

BrowserstackConfig Interface

// packages/wdio-browserstack-service/src/types.ts (L62-212)
export interface BrowserstackConfig {
    buildIdentifier?: string;           // Unique build ID (supports ${BUILD_NUMBER}, ${DATE_TIME})
    testObservability?: boolean;         // Enable Test Reporting and Analytics (default: true) [deprecated]
    testReporting?: boolean;             // Enable Test Reporting and Analytics (default: true)
    testObservabilityOptions?: TestObservabilityOptions;  // Reporting options [deprecated]
    testReportingOptions?: TestReportingOptions;          // Reporting options
    percy?: boolean;                     // Enable Percy visual testing (default: false)
    percyCaptureMode?: string;           // Screenshot capture mode: 'auto'|'click'|'testcase'|'screenshot'|'manual'
    accessibility?: boolean;             // Enable Accessibility Automation (default: false)
    accessibilityOptions?: { [key: string]: unknown };  // Accessibility config
    app?: string | AppConfig;            // App file path or hashed ID for app testing
    browserstackLocal?: boolean;         // Enable local tunnel (default: false)
    forcedStop?: boolean;                // Kill tunnel without waiting for callback (default: false)
    opts?: Partial<BSOptions>;           // BrowserStack Local binary options
    preferScenarioName?: boolean;        // Use Cucumber Scenario name as session name (default: false)
    sessionNameFormat?: Function;        // Custom session name formatter
    sessionNameOmitTestTitle?: boolean;  // Omit test title from session name (default: false)
    sessionNamePrependTopLevelSuiteTitle?: boolean;  // Prepend suite title (default: false)
    setSessionName?: boolean;            // Auto-set session name (default: true)
    setSessionStatus?: boolean;          // Auto-set session status (default: true)
    turboScale?: boolean;               // Enable TurboScale grid (default: false)
    selfHeal?: boolean;                  // Enable self-healing selectors
    testOrchestrationOptions?: TestOrchestrationOptions;  // Smart test selection config
}

BrowserStack Capability Extensions

I/O Contract -- bstack:options namespace:

Property	Type	Description
`os`	`string`	Operating system (e.g., `'Windows'`, `'OS X'`)
`osVersion`	`string`	OS version (e.g., `'11'`, `'Ventura'`)
`buildName`	`string`	Build name for grouping sessions in dashboard
`sessionName`	`string`	Session name for individual test identification
`debug`	`boolean`	Enable visual logs (screenshots at each step)
`video`	`boolean`	Enable video recording of the session
`networkLogs`	`boolean`	Enable network traffic logging
`consoleLogs`	`string`	Console log level (`'disable'`, `'errors'`, `'warnings'`, `'info'`, `'verbose'`)
`local`	`boolean`	Route traffic through BrowserStack Local tunnel
`localIdentifier`	`string`	Tunnel identifier for multiple concurrent tunnels

Sauce Labs Configuration

SauceServiceConfig Interface

// packages/wdio-sauce-service/src/types.ts (L4-51)
export interface SauceServiceConfig {
    maxErrorStackLength?: number;        // Max error stack lines sent to Sauce Labs
    tunnelName?: string;                 // Sauce Connect tunnel identifier
    tunnelOwner?: string;                // Tunnel owner account
    sauceConnect?: boolean;              // Enable Sauce Connect tunnel (default: false)
    sauceConnectOpts?: SauceConnectOptions;  // Sauce Connect binary options
    uploadLogs?: boolean;                // Upload WDIO logs to Sauce Labs (default: true)
    setJobName?: Function;               // Custom job name formatter
}

Sauce Labs Capability Extensions

I/O Contract -- sauce:options namespace:

Property	Type	Description
`build`	`string`	Build identifier for grouping jobs
`name`	`string`	Test/job name
`tags`	`string[]`	Tags for filtering and searching jobs
`tunnelName`	`string`	Sauce Connect tunnel identifier
`tunnelOwner`	`string`	Owner of the shared tunnel
`screenResolution`	`string`	Browser window resolution (e.g., `'1920x1080'`)
`extendedDebugging`	`boolean`	Enable extended debugging features

TestingBot Configuration

TestingbotOptions Interface

// packages/wdio-testingbot-service/src/types.ts (L49-60)
export interface TestingbotOptions {
    tbTunnel?: boolean;                  // Enable TestingBot Tunnel (default: false)
    tbTunnelOpts?: TunnelLauncherOptions;  // Tunnel binary options
}

TestingBot Capability Extensions

I/O Contract -- tb:options namespace:

Property	Type	Description
`tunnel-identifier`	`string`	Tunnel identifier for routing traffic
`build`	`string`	Build name for grouping sessions
`name`	`string`	Test session name

Full Example: BrowserStack Capabilities Configuration

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.BROWSERSTACK_USERNAME,
    key: process.env.BROWSERSTACK_ACCESS_KEY,

    services: [['browserstack', {
        browserstackLocal: false,
        testReporting: true,
        testReportingOptions: {
            buildName: 'My Project - CI Build',
            projectName: 'My Project'
        },
        setSessionName: true,
        setSessionStatus: true
    }]],

    capabilities: [
        // Chrome on Windows 11
        {
            browserName: 'chrome',
            browserVersion: 'latest',
            'bstack:options': {
                os: 'Windows',
                osVersion: '11',
                buildName: 'Regression Suite',
                sessionName: 'Chrome Windows Test',
                debug: true,
                video: true,
                networkLogs: true
            }
        },
        // Safari on macOS
        {
            browserName: 'safari',
            browserVersion: 'latest',
            'bstack:options': {
                os: 'OS X',
                osVersion: 'Ventura',
                buildName: 'Regression Suite',
                sessionName: 'Safari macOS Test',
                debug: true,
                video: true
            }
        },
        // Firefox on Windows 10
        {
            browserName: 'firefox',
            browserVersion: 'latest',
            'bstack:options': {
                os: 'Windows',
                osVersion: '10',
                buildName: 'Regression Suite',
                sessionName: 'Firefox Windows Test'
            }
        }
    ]
}

Full Example: Sauce Labs Capabilities Configuration

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.SAUCE_USERNAME,
    key: process.env.SAUCE_ACCESS_KEY,

    services: [['sauce', {
        sauceConnect: false,
        uploadLogs: true
    }]],

    capabilities: [{
        browserName: 'chrome',
        browserVersion: 'latest',
        platformName: 'Windows 11',
        'sauce:options': {
            build: 'CI Build #42',
            name: 'Login Flow Tests',
            tags: ['regression', 'login'],
            screenResolution: '1920x1080',
            extendedDebugging: true
        }
    }]
}

Usage Examples

Multi-browser matrix

capabilities: [
    { browserName: 'chrome', 'bstack:options': { os: 'Windows', osVersion: '11' } },
    { browserName: 'firefox', 'bstack:options': { os: 'Windows', osVersion: '11' } },
    { browserName: 'safari', 'bstack:options': { os: 'OS X', osVersion: 'Ventura' } },
    { browserName: 'edge', 'bstack:options': { os: 'Windows', osVersion: '11' } }
]

Mobile device testing

capabilities: [{
    browserName: 'safari',
    'bstack:options': {
        deviceName: 'iPhone 14',
        osVersion: '16',
        realMobile: true,
        buildName: 'Mobile Tests'
    }
}]

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment