Implementation:Webdriverio Webdriverio Globals Types

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

Overview

Global type declarations for the WebdriverIO test environment, providing TypeScript types for browser, driver, $, $$, expect, multiRemoteBrowser, and wdio variables available in test files.

Description

This ambient declaration file defines the global variables and functions injected into the test environment when WebdriverIO's injectGlobals option is enabled (the default). It declares browser and driver as WebdriverIO.Browser instances, $ and $$ as element selector functions matching the browser's method signatures, and expect as the expect-webdriverio assertion type. The multiRemoteBrowser variable is typed for multiremote sessions. The wdio object provides execute and executeWithScope methods for sending commands from the browser context to Node.js when using the @wdio/browser-runner. The file also extends the NodeJS.Global interface for compatibility.

Usage

These type declarations are consumed automatically by TypeScript when the @wdio/globals package is included in a project's tsconfig.json types array. They enable autocompletion and type checking for global variables in test files without explicit imports. When injectGlobals is set to false, these globals are not injected at runtime, and users must import them explicitly from @wdio/globals instead.

Code Reference

Source Location

• Repository: Webdriverio_Webdriverio
• File: packages/wdio-globals/types.d.ts
• Lines: 1-48

Signature

type ExpectType = import('expect-webdriverio').Expect

declare module NodeJS {
    interface Global {
        /** @deprecated Use `multiRemoteBrowser` instead. */
        multiremotebrowser: WebdriverIO.MultiRemoteBrowser
        multiRemoteBrowser: WebdriverIO.MultiRemoteBrowser
        browser: WebdriverIO.Browser
        driver: WebdriverIO.Browser
        expect: ExpectType
    }
}

declare function $(...args: Parameters<WebdriverIO.Browser['$']>): ReturnType<WebdriverIO.Browser['$']>
declare function $$(...args: Parameters<WebdriverIO.Browser['$$']>): ReturnType<WebdriverIO.Browser['$$']>

/** @deprecated Use `multiRemoteBrowser` instead. */
declare var multiremotebrowser: WebdriverIO.MultiRemoteBrowser
declare var multiRemoteBrowser: WebdriverIO.MultiRemoteBrowser
declare var browser: WebdriverIO.Browser
declare var driver: WebdriverIO.Browser
declare var expect: ExpectType

declare var wdio: {
    execute: <CommandName>(
        command: CommandName,
        ...args: any[]
    ) => ReturnType<WebdriverIO.Browser[CommandName]>
    executeWithScope: <CommandName>(
        commandName: CommandName,
        scope: string,
        ...args: any[]
    ) => ReturnType<WebdriverIO.Browser[CommandName]>
}

Import

// These are ambient declarations - no import needed when injectGlobals is true.
// The types are available globally once @wdio/globals is in tsconfig.json:
//
// tsconfig.json:
// {
//   "compilerOptions": {
//     "types": ["@wdio/globals/types"]
//   }
// }

// When injectGlobals is false, import explicitly:
import { browser, driver, $, $$, expect } from '@wdio/globals'

I/O Contract

Global Declarations
Name	Type	Kind	Description
browser	WebdriverIO.Browser	Variable	Primary browser instance for WebDriver commands
driver	WebdriverIO.Browser	Variable	Alias for browser
$	(...args) => Element	Function	Single element selector (delegates to browser.$)
$$	(...args) => Element[]	Function	Multiple element selector (delegates to browser.$$)
expect	ExpectType	Variable	Assertion function from expect-webdriverio
multiRemoteBrowser	WebdriverIO.MultiRemoteBrowser	Variable	Browser instance for multiremote sessions
multiremotebrowser	WebdriverIO.MultiRemoteBrowser	Variable	Deprecated - use multiRemoteBrowser

wdio Object (Browser Runner)
Method	Parameters	Return	Description
execute	command: CommandName, ...args: any[]	ReturnType<Browser[CommandName]>	Execute a browser command from the browser runner context in Node.js
executeWithScope	commandName: CommandName, scope: string, ...args: any[]	ReturnType<Browser[CommandName]>	Execute a scoped element command from the browser runner in Node.js

Usage Examples

// Test file using global variables (injectGlobals: true)
describe('Login Page', () => {
    it('should login successfully', async () => {
        await browser.url('/login')

        const usernameInput = await $('#username')
        await usernameInput.setValue('testuser')

        const passwordInput = await $('#password')
        await passwordInput.setValue('password123')

        const submitBtn = await $('button[type="submit"]')
        await submitBtn.click()

        await expect(browser).toHaveUrl('/dashboard')

        const welcomeMsg = await $('h1.welcome')
        await expect(welcomeMsg).toHaveText('Welcome, testuser!')
    })

    it('should display validation errors', async () => {
        await browser.url('/login')

        const submitBtn = await $('button[type="submit"]')
        await submitBtn.click()

        const errors = await $$('.error-message')
        await expect(errors).toBeElementsArrayOfSize(2)
    })
})

// Using driver alias (equivalent to browser)
describe('API Testing', () => {
    it('should make a request', async () => {
        const response = await driver.execute(() => {
            return fetch('/api/status').then(r => r.json())
        })
        expect(response.status).toBe('ok')
    })
})

// Using wdio object in browser runner context
describe('Browser Runner Tests', () => {
    it('should execute Node.js command from browser', async () => {
        const title = await wdio.execute('getTitle')
        expect(title).toBe('My App')
    })
})

// Explicit imports when injectGlobals is false
import { browser, $, $$, expect } from '@wdio/globals'

describe('With explicit imports', () => {
    it('works the same way', async () => {
        await browser.url('/page')
        const el = await $('h1')
        await expect(el).toExist()
    })
})

Related Pages

• Principle:Webdriverio_Webdriverio_Global_API
• Implementation:Webdriverio_Webdriverio_Options_Types - injectGlobals option controls whether globals are injected
• Implementation:Webdriverio_Webdriverio_Capabilities_Types - Browser capabilities used by the global browser instance
• Implementation:Webdriverio_Webdriverio_Workers_Types - wdio object uses worker messaging for browser runner commands