Principle:Webdriverio Webdriverio Browser Session Creation

Overview

Browser Session Creation is a technique for establishing a remote browser connection via the WebDriver protocol to enable programmatic browser control. It is the fundamental entry point for any browser automation workflow in WebdriverIO, enabling test scripts to launch and communicate with browser instances through a standardized protocol interface.

Description

Browser Session Creation is the process of establishing a connection between a test script and a browser instance via the W3C WebDriver protocol. The client sends a "New Session" command with desired capabilities (browserName, browserVersion, platformName) to a WebDriver endpoint. The server launches the browser and returns a unique sessionId. All subsequent commands are scoped to this session.

The session creation process involves several key steps:

Capability Negotiation: The client specifies desired capabilities (e.g., browser name, version, platform) in a JSON payload. The server matches these against available browsers.
Browser Launch: The WebDriver endpoint starts the requested browser process.
Session Identifier Assignment: A unique session ID is returned, which serves as a path component in all subsequent HTTP requests.
Connection Establishment: The client stores the session ID and uses it for all further protocol communication.

This is the fundamental entry point for any browser automation workflow. Without a valid session, no browser commands can be issued.

Usage

Use Browser Session Creation when you need programmatic control over a browser for testing or automation. It is required as the first step in any WebdriverIO standalone script or testrunner workflow.

When to use:

At the beginning of every automated browser test
When launching a standalone WebdriverIO script
When connecting to a remote Selenium Grid or cloud provider (e.g., BrowserStack, Sauce Labs)
When the testrunner framework initializes each worker

When not to use:

When attaching to an already-existing session (use attach instead)
When the testrunner handles session lifecycle automatically (it calls this internally)

Theoretical Basis

The W3C WebDriver protocol defines a REST API where POST /session with a capabilities payload creates a new browser session. The protocol flow is defined as follows:

The client constructs a capabilities object conforming to the W3C specification, including required fields such as browserName and optional fields such as browserVersion and platformName.
The client sends an HTTP POST request to the /session endpoint with the capabilities in the request body.
The server (WebDriver endpoint) processes the capabilities using a "matching" algorithm to select an appropriate browser configuration.
The server launches the browser and establishes the automation session.
The server responds with a JSON body containing the sessionId (a unique string identifier) and the capabilities (the negotiated set of capabilities that were actually provided).
The sessionId is used as a path component in all subsequent HTTP requests (e.g., POST /session/{sessionId}/url to navigate).

The protocol is defined in the W3C WebDriver specification. The specification guarantees that a session ID is opaque, unique, and valid until explicitly deleted via DELETE /session/{sessionId}.

implemented_by Implementation:Webdriverio_Webdriverio_Remote_Function - The remote() function that concretely implements browser session creation in WebdriverIO.

Page Connections

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

Principle

Implementation

Heuristic

Environment