addCommand

The browser method addCommand helps you to write your own set of commands. You can write your command in a synchronous way or in an asynchronous way.

info

You can find more information on adding custom commands in the custom command guide.

Usage

browser.addCommand(name, callback, elementScope)

Parameters

Name	Type	Details
name	String	name of the custom command
callback	Function	function to be called
elementScope optional	Boolean	extend the Element object instead of the Browser object

Example

Asynchronous Mode

execute.js

await browser.addCommand('getUrlAndTitle', async function (customParam) {
    // `this` refers to the `browser` scope
    return {
        url: await this.getUrl(),
        title: await this.getTitle(),
        customParam: customParam
    }
})
//usage
it('should use my add command', async () => {
    await browser.url('https://webdriver.io')
    const result = await browser.getUrlAndTitle('foobar')

    assert.strictEqual(result.url, 'https://webdriver.io')
    assert.strictEqual(result.title, 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    assert.strictEqual(result.customParam, 'foobar')
})

Synchronous Mode

execute.js

browser.addCommand('getUrlAndTitle', function (customParam) {
    // `this` refers to the `browser` scope
    return {
        url: this.getUrl(),
        title: this.getTitle(),
        customParam: customParam
    }
})
//usage
it('should use my add command', () => {
    browser.url('https://webdriver.io')
    const result = browser.getUrlAndTitle('foobar')

    assert.strictEqual(result.url, 'https://webdriver.io')
    assert.strictEqual(result.title, 'WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    assert.strictEqual(result.customParam, 'foobar')
})

caution

Synchronous Mode will depcrecated with Node.js v16. With an update to the underlying Chromium version it became technically impossible to provide the same synchronous behavior. We recommend to start transition to asynchronous command execution. For more information, see our RFC.