newWindow

Open a new window or tab and wait until its page has loaded, the equivalent of window.open(). This command does not work in mobile environments.

In a WebDriver BiDi session (the default since v10) it returns the new browsing context and does not switch to it: run commands on the returned context, while browser.url() keeps navigating the first one. In a WebDriver Classic session the command switches to the new window and returns { handle, type }.

Usage

await browser.newWindow(url, { type })

Parameters

Name	Type	Details
url	string	website URL to open
options optional	NewWindowOptions	newWindow command options
options.type optional	string	type of new window: 'tab' or 'window'

Example

newWindow.js

it('should open a new tab', async () => {
    const page = await browser.url('https://webdriver.io')
    const tab = await browser.newWindow('https://webdriver.io/docs/api', { type: 'tab' })

    console.log(await tab.getTitle()) // the title of the API page
    console.log(await page.getTitle()) // the first tab still answers commands
    await tab.closeWindow()
});

Returns

• <BrowsingContext|Object> return: In a BiDi session, the new browsing context. In a Classic session, {handle, type}.

Throws

• Error: If url is invalid, if the command is used on mobile, or type is not 'tab' or 'window'.