Implementation:Webdriverio Webdriverio Remote Function

Overview

The remote() function is the concrete tool provided by the WebdriverIO library for creating a WebDriver browser session. It is the primary entry point for standalone WebdriverIO usage, validating configuration, initializing the protocol client, establishing the session, and returning a fully-configured browser instance.

Description

The remote() function is the primary entry point for standalone WebdriverIO usage. It performs the following operations:

1. Validates configuration options using validateConfig() against the WDIO_DEFAULTS schema, ensuring all required options are present and correctly typed.
2. Enables file logging if an outputDir is specified, and configures log levels.
3. Resolves the protocol driver via getProtocolDriver(), which determines whether to use WebDriver Classic or WebDriver BiDi.
4. Builds the browser prototype by calling getPrototype('browser'), which aggregates all browser-level protocol commands and custom commands.
5. Creates a new browser session by invoking Driver.newSession(), which sends the W3C POST /session request with the specified capabilities.
6. Applies the remote modifier (if provided), allowing callers to customize the client prototype before it is finalized.
7. Registers the session manager for automatic resource tracking.
8. Returns a fully-configured WebdriverIO.Browser instance with the session ID, all protocol commands attached, and a chainable API.

The browser object uses a monadic pattern for chainable command execution, enabling fluent test authoring.

Source Location

Property	Value
Repository	https://github.com/webdriverio/webdriverio
File	packages/webdriverio/src/index.ts
Lines	L40-80
Exported As	Named export remote

Signature

export const remote = async function (
    params: Capabilities.WebdriverIOConfig,
    remoteModifier?: (
        client: WebDriverTypes.Client,
        options: Capabilities.WebdriverIOConfig
    ) => WebDriverTypes.Client
): Promise<WebdriverIO.Browser>

Import

import { remote } from 'webdriverio'

Inputs

Parameter	Type	Required	Description
params	Capabilities.WebdriverIOConfig	Yes	Configuration object containing capabilities and connection options. Key fields include: browserName, hostname, port, protocol, path, logLevel, capabilities, baseUrl, waitforTimeout, connectionRetryTimeout, connectionRetryCount.
remoteModifier	(client: WebDriverTypes.Client, options: Capabilities.WebdriverIOConfig) => WebDriverTypes.Client	No	Optional modifier function applied to the client prototype before session creation completes. Used internally by the testrunner to attach additional functionality.

Outputs

Return Type	Description
Promise<WebdriverIO.Browser>	A browser instance containing the sessionId, all W3C WebDriver protocol commands, WebdriverIO-specific convenience commands (e.g., $, $$, url), and a chainable API. The instance also exposes the negotiated capabilities object and configuration options.

Usage Example

import { remote } from 'webdriverio'

// Create a Chrome browser session
const browser = await remote({
    capabilities: {
        browserName: 'chrome',
        'goog:chromeOptions': {
            args: ['--headless', '--disable-gpu']
        }
    },
    logLevel: 'info'
})

try {
    // Navigate to a page
    await browser.url('https://webdriver.io')

    // Interact with elements
    const title = await browser.getTitle()
    console.log('Page title:', title)

    // Find and click an element
    const link = await browser.$('=API')
    await link.click()
} finally {
    // Always clean up the session
    await browser.deleteSession()
}

Internal Flow

The internal execution flow of remote() proceeds as follows:

1. validateConfig(WDIO_DEFAULTS, params, keysToKeep) validates and merges user-provided options with defaults.
2. enableFileLogging(config.outputDir) sets up file-based logging if configured.
3. getProtocolDriver({ ...params, ...config }) resolves the appropriate WebDriver protocol implementation.
4. getPrototype('browser') builds the browser command prototype by aggregating protocol commands.
5. Driver.newSession(options, modifier, prototype, wrapCommand, IMPLICIT_WAIT_EXCLUSION_LIST) sends the POST /session request and constructs the monad.
6. addLocatorStrategyHandler(instance) attaches custom locator strategy support.
7. registerSessionManager(instance) registers session lifecycle tracking.

Related Pages

• implements Principle:Webdriverio_Webdriverio_Browser_Session_Creation - The Browser Session Creation principle that this function implements.
• Environment:Webdriverio_Webdriverio_Node_Runtime_Environment
• Environment:Webdriverio_Webdriverio_Browser_Driver_Environment
• Heuristic:Webdriverio_Webdriverio_Exponential_Backoff_Retry