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 multi-remote instance which allows you to control multiple session within a single instance. Checkout our multi-remote 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:

@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:

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')

Welcome! How can I help?