Principle:Webdriverio Webdriverio Cloud Capabilities Definition

Metadata

Field	Value
Page ID	Cloud_Capabilities_Definition
Wiki	Webdriverio_Webdriverio
Type	Principle
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 Implementations	Implementation: Cloud_Capabilities_Config

Overview

A mechanism for specifying browser, OS, and provider-specific settings for running tests on cloud-hosted browser infrastructure. Cloud Capabilities Definition extends the W3C WebDriver capabilities model with vendor-specific extensions for cloud testing platforms (BrowserStack, Sauce Labs, TestingBot), enabling tests to run across browsers, operating systems, and device combinations not available on the local machine.

Description

Cloud Capabilities Definition extends the W3C WebDriver capabilities model with vendor-specific extensions for cloud testing platforms. Standard capabilities (browserName, browserVersion, platformName) are augmented with vendor-namespaced options that control cloud-specific features such as video recording, debug logging, tunnels, build grouping, and session naming.

The three primary cloud providers supported by WebdriverIO each use their own namespace:

BrowserStack -- bstack:options for OS selection, build naming, debug tools, video recording, and local tunnel configuration.
Sauce Labs -- sauce:options for build tagging, session naming, tunnel configuration, and extended debugging.
TestingBot -- tb:options for tunnel identifiers and platform configuration.

In WebdriverIO, capabilities are defined in the capabilities array in wdio.conf.ts. Each entry in the array represents a browser session configuration. Cloud capabilities are mixed in alongside standard W3C capabilities, and the vendor-namespaced keys pass through to the cloud provider's infrastructure to configure the remote browser instance.

Key features enabled by cloud capabilities:

Cross-browser testing -- Specify any browser and version combination available on the cloud platform.
Cross-OS testing -- Run tests on Windows, macOS, Linux, iOS, and Android.
Build organization -- Group test sessions by build name for easier debugging and reporting.
Session recording -- Enable video recording, console logs, network logs, and screenshots.
Debug tools -- Enable provider-specific debugging features like BrowserStack's visual logs or Sauce Labs' extended debugging.
Tunnel integration -- Connect cloud browsers to local/internal applications via tunnel identifiers.

Usage

Use Cloud Capabilities Definition when configuring tests to run on cloud browser infrastructure. Define capabilities in wdio.conf.ts with vendor extensions for the chosen provider.

When to apply:

Running tests across multiple browsers and OS combinations not available locally.
Testing on real mobile devices via cloud device farms.
Integrating test runs with CI/CD pipelines using build-level grouping.
When you need video recordings and debug logs for test failure analysis.

When to avoid:

For local development testing where a local browser suffices.
When the cloud provider is not part of the testing infrastructure.

Basic configuration pattern:

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.BROWSERSTACK_USERNAME,
    key: process.env.BROWSERSTACK_ACCESS_KEY,
    capabilities: [{
        browserName: 'chrome',
        browserVersion: 'latest',
        'bstack:options': {
            os: 'Windows',
            osVersion: '11',
            buildName: 'My Build',
            sessionName: 'Login Test',
            debug: true,
            video: true
        }
    }],
    services: ['browserstack']
}

Theoretical Basis

The W3C WebDriver capabilities model uses a matched capabilities negotiation protocol. When a test session is created, the client sends a set of requested capabilities. The server (cloud provider) matches these against its available infrastructure and creates a session on a matching browser instance.

Capability types:

Type	Scope	Examples
Standard W3C	Defined by the WebDriver specification	`browserName`, `browserVersion`, `platformName`
Vendor extensions	Defined by the vendor, using namespaced keys	`bstack:options`, `sauce:options`, `tb:options`
Browser-specific	Defined by browser vendors	`goog:chromeOptions`, `moz:firefoxOptions`

Vendor extension mechanism:

The W3C WebDriver specification allows any key containing a colon (:) to pass through as a vendor extension. Cloud providers interpret these extensions to configure their infrastructure:

The cloud platform receives bstack:options.os: 'Windows' and provisions a Windows VM.
The platform receives bstack:options.video: true and starts video recording for the session.
The platform receives bstack:options.buildName: 'CI Build #42' and groups the session under that build in the dashboard.

Service integration:

WebdriverIO cloud service packages (@wdio/browserstack-service, @wdio/sauce-service, @wdio/testingbot-service) automatically enhance capabilities with additional metadata:

Service version identifiers for support diagnostics.
Session names derived from test titles.
Build identifiers from CI environment variables.
Tunnel identifiers for local testing connections.

implemented_by Implementation: Cloud_Capabilities_Config

Page Connections

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

Principle

Implementation

Heuristic

Environment