Principle:Webdriverio Webdriverio Cloud Session Management

Overview

A mechanism for synchronizing test execution metadata with cloud testing platforms through lifecycle event hooks.

Description

Cloud Session Management keeps cloud testing dashboards in sync with local test execution. Service hooks intercept test lifecycle events (session start, test start, test pass/fail, session end) and update the cloud provider's API with test names, statuses, error messages, and build metadata. This enables features like automatic session naming, pass/fail marking, video correlation, and build grouping on cloud dashboards.

The core challenge is that cloud testing platforms (BrowserStack, Sauce Labs, TestingBot) maintain their own session records but have no inherent knowledge of local test outcomes. Without Cloud Session Management, sessions on cloud dashboards would show as "completed" but never as "passed" or "failed," test names would default to session IDs, and builds would lack any logical grouping.

Cloud services solve this by acting as middleware between the local WDIO test runner and the cloud provider's REST API. When the test runner emits lifecycle events, the cloud service:

Captures test metadata -- test name, suite name, tags, build identifier
Tracks test outcomes -- pass, fail, skip, with associated error messages and stack traces
Updates the cloud session -- via the provider's REST API (e.g., PUT /sessions/{sessionId})
Handles session lifecycle -- including session refresh (onReload) where a new browser session replaces the old one mid-test

Each cloud provider has provider-specific features beyond basic session management:

BrowserStack -- Observability integration, accessibility testing, Percy visual testing, performance measurement, and Test Hub synchronization
Sauce Labs -- Test Runs API for RDC (Real Device Cloud) sessions, CI metadata injection, and job asset management
TestingBot -- Lightweight session status and name updates

Usage

Use Cloud Session Management when running tests on BrowserStack, Sauce Labs, or TestingBot. The service automatically hooks into test lifecycle events. Configure via the services array in wdio.conf.ts. No manual API calls are needed -- the service handles all cloud communication.

Basic configuration for BrowserStack:

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.BROWSERSTACK_USERNAME,
    key: process.env.BROWSERSTACK_ACCESS_KEY,
    services: ['browserstack'],
    capabilities: [{
        browserName: 'chrome',
        'bstack:options': {
            buildName: 'My Build',
            projectName: 'My Project'
        }
    }]
}

Basic configuration for Sauce Labs:

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.SAUCE_USERNAME,
    key: process.env.SAUCE_ACCESS_KEY,
    services: ['sauce'],
    capabilities: [{
        browserName: 'chrome',
        'sauce:options': {
            build: 'My Build'
        }
    }]
}

Basic configuration for TestingBot:

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    user: process.env.TESTINGBOT_KEY,
    key: process.env.TESTINGBOT_SECRET,
    services: [['testingbot', { tbTunnel: false }]],
    capabilities: [{
        browserName: 'chrome'
    }]
}

When to use:

Running end-to-end tests on cloud browser grids
Needing automatic pass/fail reporting on cloud dashboards
Correlating video recordings and screenshots with specific tests
Grouping sessions by build or project in the cloud provider's UI

When not to use:

Running tests locally or against a self-hosted Selenium grid
Using a cloud provider without a dedicated WDIO service

Theoretical Basis

Cloud Session Management uses the Service Lifecycle Hook pattern from WebdriverIO's plugin architecture. Services implement hooks (beforeSession, before, beforeTest, afterTest, after, onReload) that are called at specific points during test execution. The hooks use the cloud provider's REST API to update session metadata.

This follows the Observer pattern -- the test runner emits lifecycle events and services react to them without the runner needing to know about cloud providers. The pattern provides:

Decoupling -- The test runner does not know about cloud providers; cloud services subscribe to events independently
Composability -- Multiple cloud services could theoretically be active (though typically only one is used)
Transparency -- Test code is completely unaware of cloud session management; it happens at the infrastructure level

The lifecycle event flow for a typical test is:

Hook	When Fired	Cloud Action
`beforeSession`	Before WebDriver session created	Configure session metadata in capabilities
`before`	After session created, before tests	Store session ID, initialize tracking
`beforeTest`	Before each test	Update session name on cloud dashboard
`afterTest`	After each test	Record pass/fail, capture error messages
`after`	After all tests	Set final session status via REST API
`onReload`	When session is refreshed	Transfer metadata from old to new session

The onReload hook is particularly important because WebdriverIO supports mid-test session refresh. When a session is recreated (e.g., due to a crash), the cloud service must update the old session's status and begin tracking the new one.

implemented_by Implementation:Webdriverio_Webdriverio_Cloud_Service_Hooks

Page Connections

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

Principle

Implementation

Heuristic

Environment