Implementation:Webdriverio Webdriverio Capabilities Types

Knowledge Sources	Webdriverio_Webdriverio
Domains	Type_Definitions, Capabilities
Last Updated	2026-02-12 00:00 GMT

Overview

Comprehensive TypeScript type definitions for WebDriver and WebdriverIO capabilities covering the W3C standard, vendor-specific browser options, cloud provider configurations, and Appium mobile testing capabilities.

Description

This module defines the complete type hierarchy for browser and device capabilities used throughout WebdriverIO. It includes the core W3C WebDriver capabilities interface (WebdriverIO.Capabilities), vendor-specific extensions for Chrome (ChromeOptions), Firefox (FirefoxOptions), and Edge, as well as mobile testing types through AppiumCapabilities, AppiumAndroidCapabilities, and AppiumXCUITestCapabilities. Cloud provider integrations are typed via SauceLabsCapabilities and BrowserStackCapabilities. All vendor extensions are unified through the VendorExtensions interface.

Usage

Use these types when defining browser or device capabilities for WebdriverIO test sessions. They provide autocompletion and type safety for configuration objects passed to remote(), multiremote(), and the testrunner capabilities property. Reference these types when building custom capability objects, creating reusable capability presets, or when writing services that need to inspect or transform capabilities.

Code Reference

Source Location

• Repository: Webdriverio_Webdriverio
• File: packages/wdio-types/src/Capabilities.ts
• Lines: 1-1890

Signature

export type PageLoadingStrategy = 'none' | 'eager' | 'normal'

export type Timeouts = Record<'script' | 'pageLoad' | 'implicit', number>

export interface ProxyObject {
    proxyType?: ProxyTypes
    proxyAutoconfigUrl?: string
    httpProxy?: string
    httpProxyPort?: number
    sslProxy?: string
    sslProxyPort?: number
    socksProxy?: string
    socksProxyPort?: number
    noProxy?: string[]
}

declare global {
    namespace WebdriverIO {
        interface Capabilities extends VendorExtensions, ConnectionOptions {
            browserName?: string
            browserVersion?: string
            platformName?: string
            acceptInsecureCerts?: boolean
            pageLoadStrategy?: PageLoadingStrategy
            proxy?: ProxyObject
            setWindowRect?: boolean
            timeouts?: Timeouts
            strictFileInteractability?: boolean
            unhandledPromptBehavior?: string
            webSocketUrl?: boolean
        }
    }
}

export interface W3CCapabilities {
    alwaysMatch: WebdriverIO.Capabilities
    firstMatch: WebdriverIO.Capabilities[]
}

export interface ChromeOptions { /* ... */ }
export interface FirefoxOptions { /* ... */ }
export interface AppiumCapabilities { /* ... */ }
export interface SauceLabsCapabilities { /* ... */ }
export interface BrowserStackCapabilities { /* ... */ }

export interface VendorExtensions extends EdgeCapabilities, AppiumCapabilities,
    WebdriverIOCapabilities, SauceLabsCapabilities, SauceLabsVisualCapabilities,
    TestingbotCapabilities, SeleniumCapabilities, GeckodriverCapabilities,
    ChromedriverCapabilities, BrowserStackCapabilities, LambdaTestCapabilities { /* ... */ }

Import

import type { Capabilities } from '@wdio/types'

// Access specific types
type Strategy = Capabilities.PageLoadingStrategy
type W3C = Capabilities.W3CCapabilities
type Chrome = Capabilities.ChromeOptions
type Firefox = Capabilities.FirefoxOptions
type Sauce = Capabilities.SauceLabsCapabilities
type BStack = Capabilities.BrowserStackCapabilities

// Global namespace capabilities
const caps: WebdriverIO.Capabilities = { browserName: 'chrome' }

I/O Contract

Key Type Members
Name	Type	Required	Description
browserName	string	No	Identifies the user agent (e.g., 'chrome', 'firefox', 'safari')
browserVersion	string	No	Version of the user agent
platformName	string	No	Operating system of the endpoint node
acceptInsecureCerts	boolean	No	Trust untrusted TLS certificates during session
pageLoadStrategy	PageLoadingStrategy	No	Page load strategy: 'none', 'eager', or 'normal'
proxy	ProxyObject	No	Proxy configuration for the session
timeouts	Timeouts	No	Script, pageLoad, and implicit timeout values
'goog:chromeOptions'	ChromeOptions	No	Chrome-specific options via vendor extension
'moz:firefoxOptions'	FirefoxOptions	No	Firefox-specific options via vendor extension
'sauce:options'	SauceLabsCapabilities	No	Sauce Labs cloud configuration
'bstack:options'	BrowserStackCapabilities	No	BrowserStack cloud configuration

Dependent / Derived Types
Name	Description	Used By
W3CCapabilities	Structured W3C capabilities with alwaysMatch/firstMatch	Session creation
RequestedStandaloneCapabilities	Union of W3C and flat capabilities	remote()
TestrunnerCapabilities	Array/multiremote capability types for testrunner	wdio.conf.ts
VendorExtensions	Aggregated vendor-specific capability interfaces	WebdriverIO.Capabilities

Usage Examples

import type { Capabilities } from '@wdio/types'

// Basic W3C capabilities
const chromeCapabilities: WebdriverIO.Capabilities = {
    browserName: 'chrome',
    browserVersion: '120',
    platformName: 'Windows 11',
    acceptInsecureCerts: true,
    pageLoadStrategy: 'eager',
    'goog:chromeOptions': {
        args: ['--headless', '--disable-gpu'],
        prefs: { 'download.default_directory': '/tmp' }
    }
}

// W3C structured capabilities
const w3cCaps: Capabilities.W3CCapabilities = {
    alwaysMatch: {
        browserName: 'firefox',
        'moz:firefoxOptions': {
            args: ['-headless']
        }
    },
    firstMatch: [{}]
}

// Sauce Labs cloud capabilities
const sauceCaps: WebdriverIO.Capabilities = {
    browserName: 'chrome',
    platformName: 'Windows 10',
    browserVersion: 'latest',
    'sauce:options': {
        name: 'My Test Suite',
        build: 'build-123',
        tunnelIdentifier: 'my-tunnel'
    }
}

// Appium mobile capabilities
const appiumCaps: WebdriverIO.Capabilities = {
    platformName: 'Android',
    'appium:deviceName': 'Pixel 6',
    'appium:app': '/path/to/app.apk',
    'appium:automationName': 'UiAutomator2'
}

// Testrunner multiremote capabilities
const multiremoteCaps: Capabilities.RequestedMultiremoteCapabilities = {
    myChromeBrowser: {
        capabilities: {
            browserName: 'chrome'
        }
    },
    myFirefoxBrowser: {
        capabilities: {
            browserName: 'firefox'
        }
    }
}

Related Pages

• Principle:Webdriverio_Webdriverio_Type_Safety
• Implementation:Webdriverio_Webdriverio_Options_Types - Configuration options that consume capabilities
• Implementation:Webdriverio_Webdriverio_Services_Types - Services that receive capabilities
• Implementation:Webdriverio_Webdriverio_Config_Constants - Default configuration values including capability defaults