Modules

WebdriverIO publishes various modules to NPM and other registries that you can use to build your own automation framework. See more documentation on WebdriverIO setup types here.

webdriver and devtools

The protocol packages (webdriver and devtools) expose a class with the following static functions attached that allow you to initiate sessions:

newSession(options, modifier, userPrototype, customCommandWrapper)

Starts a new session with specific capabilities. Based on the session response commands from different protocols will be provided.

Paramaters

• options: WebDriver Options
• modifier: function that allows to modify the client instance before it is being returned
• userPrototype: properties object that allows to extend the instance prototype
• customCommandWrapper: function that allows to wrap functionality around function calls

Returns

• Browser object

Example

const client = await WebDriver.newSession({
    capabilities: { browserName: 'chrome' }
})

attachToSession(attachInstance, modifier, userPrototype, customCommandWrapper)

Attaches to a running WebDriver or DevTools session.

Paramaters

• attachInstance: instance to attach a session to or at least an object with a property sessionId (e.g. { sessionId: 'xxx' })
• modifier: function that allows to modify the client instance before it is being returned
• userPrototype: properties object that allows to extend the instance prototype
• customCommandWrapper: function that allows to wrap functionality around function calls

Returns

• Browser object

Example

const client = await WebDriver.newSession({...})
const clonedClient = await WebDriver.attachToSession(client)

reloadSession(instance)

Reloads a session given provided instance.

Paramaters

• instance: package instance to reload

Example

const client = await WebDriver.newSession({...})
await WebDriver.reloadSession(client)

webdriverio

Similar as to the protocol packages (webdriver and devtools) you can also use the WebdriverIO package APIs to manage sessions. The APIs can be imported using import { remote, attach, multiremote } from 'webdriverio and contain the following functionality:

remote(options, modifier)

Starts a WebdriverIO session. The instance contains all commands as the protocol package but with additional higher order functions, see API docs.

Paramaters

• options: WebdriverIO Options
• modifier: function that allows to modify the client instance before it is being returned

Returns

• Browser object

Example

import { remote } from 'webdriverio'

const browser = await remote({
    capabilities: { browserName: 'chrome' }
})

attach(attachOptions)

Attaches to a running WebdriverIO session.

Paramaters

• attachOptions: instance to attach a session to or at least an object with a property sessionId (e.g. { sessionId: 'xxx' })

Returns

• Browser object

Example

import { remote, attach } from 'webdriverio'

const browser = await remote({...})
const newBrowser = await attach(browser)

multiremote(multiremoteOptions)

Initiates a multiremote instance which allows you to control multiple session within a single instance. Checkout our multiremote examples for concrete use cases.

Paramaters

• multiremoteOptions: an object with keys representing the browser name and their WebdriverIO Options.

Returns

• Browser object

Example

import { multiremote } from 'webdriverio'

const matrix = await multiremote({
    myChromeBrowser: {
        capabilities: { browserName: 'chrome' }
    },
    myFirefoxBrowser: {
        capabilities: { browserName: 'firefox' }
    }
})
await matrix.url('http://json.org')
await matrix.getInstance('browserA').url('https://google.com')

console.log(await matrix.getTitle())
// returns ['Google', 'JSON']

Key

An object containing special character constants for use with the browser.keys command. These constants represent special keys that can be sent to the browser, such as Enter, Tab, Escape, arrow keys, function keys, and more.

Example

import { Key } from 'webdriverio'

// Press Enter key
await browser.keys(Key.Enter)

// Use Ctrl+A to select all (works cross-platform)
await browser.keys([Key.Ctrl, 'a'])

// Navigate with arrow keys
await browser.keys([Key.ArrowDown, Key.ArrowDown, Key.Enter])

Available Keys

The following special keys are available via the Key object:

Modifier Keys:

Navigation Keys:

Character Keys:

Numpad Keys:

Function Keys:

Other Keys:

:::info Cross-Platform Modifier Keys

The Key.Ctrl constant provides a convenient way to use the "control" modifier across different operating systems. On macOS, it maps to the Command key, while on Windows and Linux it maps to the Control key. This is useful when writing tests that need to work across multiple platforms, e.g., for select-all (Ctrl+A), copy (Ctrl+C), or paste (Ctrl+V) operations.

:::

@wdio/cli

Instead of calling the wdio command, you can also include the test runner as module and run it in an arbitrary environment. For that, you'll need to require the @wdio/cli package as module, like this:

<Tabs defaultValue="esm" values={[ {label: 'EcmaScript Modules', value: 'esm'}, {label: 'CommonJS', value: 'cjs'} ] }> <TabItem value="esm">

import Launcher from '@wdio/cli'

const Launcher = require('@wdio/cli').default

After that, create an instance of the launcher, and run the test.

Launcher(configPath, opts)

The Launcher class constructor expects the URL to the config file, and an opts object with settings that will overwrite those in the config.

Paramaters

• configPath: path to the wdio.conf.js to run
• opts: arguments (<RunCommandArguments>) to overwrite values from the config file

Example

const wdio = new Launcher(
    '/path/to/my/wdio.conf.js',
    { spec: '/path/to/a/single/spec.e2e.js' }
)

wdio.run().then((exitCode) => {
    process.exit(exitCode)
}, (error) => {
    console.error('Launcher failed to start the test', error.stacktrace)
    process.exit(1)
})

The run command returns a Promise. It is resolved if tests ran successfully or failed, and it is rejected if the launcher was unable to start run the tests.

@wdio/browser-runner

When running unit or component tests using WebdriverIO's browser runner you can import mocking utilities for your tests, e.g.:

import { fn, spyOn, mock, unmock } from '@wdio/browser-runner'

The following named exports are available:

fn

Mock function, see more in the official Vitest docs.

spyOn

Spy function, see more in the official Vitest docs.

mock

Method to mock file or dependency module.

Paramaters

• moduleName: either a relative path to the file to be mocked or a module name.
• factory: function to return the mocked value (optional)

Example

mock('../src/constants.ts', () => ({
    SOME_DEFAULT: 'mocked out'
}))

mock('lodash', (origModuleFactory) => {
    const origModule = await origModuleFactory()
    return {
        ...origModule,
        pick: fn()
    }
})

unmock

Unmock dependency that is defined within the manual mock (__mocks__) directory.

Paramaters

• moduleName: name of the module to be unmocked.

Example

unmock('lodash')