The Browser Object

Extends: EventEmitter

The browser object is the session instance you use to control the browser or mobile device with. If you use the WDIO test runner, you can access the WebDriver instance through the global browser or driver object or import it using @wdio/globals. If you use WebdriverIO in standalone mode the browser object is returned by the remote method.

The session is initialized by the test runner. The same goes for ending the session. This is also done by the test runner process.

Properties

A browser object has the following properties:

Name	Type	Details
capabilities	Object	Assigned capabilities from the remote server. Example: { acceptInsecureCerts: false, browserName: 'chrome', browserVersion: '105.0.5195.125', chrome: { chromedriverVersion: '105.0.5195.52', userDataDir: '/var/folders/3_/pzc_f56j15vbd9z3r0j050sh0000gn/T/.com.google.Chrome.76HD3S' }, 'goog:chromeOptions': { debuggerAddress: 'localhost:64679' }, networkConnectionEnabled: false, pageLoadStrategy: 'normal', platformName: 'mac os x', proxy: {}, setWindowRect: true, strictFileInteractability: false, timeouts: { implicit: 0, pageLoad: 300000, script: 30000 }, unhandledPromptBehavior: 'dismiss and notify', 'webauthn:extension:credBlob': true, 'webauthn:extension:largeBlob': true, 'webauthn:virtualAuthenticators': true }
requestedCapabilities	Object	Capabilities requested from the remote server. Example: { browserName: 'chrome' }
sessionId	String	Session id assigned from the remote server.
options	Object	WebdriverIO options depending on how the browser object was created. See more setup types.
commandList	String[]	A list of commands registered to the browser instance
isMobile	Boolean	Indicates a mobile session. See more under Mobile Flags.
isIOS	Boolean	Indicates an iOS session. See more under Mobile Flags.
isAndroid	Boolean	Indicates an Android session. See more under Mobile Flags.

Methods

Based on the automation backend used for your session, WebdriverIO identifies which Protocol Commands will be attached to the browser object. For example if you run an automated session in Chrome, you will have access to Chromium specific commands like elementHover but not any of the Appium commands.

Furthermore WebdriverIO provides a set of convenient methods that are recommended to use, to interact with the browser or elements on the page.

In addition to that the following commands are available:

Name	Parameters	Details
addCommand	- commandName (Type: String) - fn (Type: Function) - attachToElement (Type: boolean)	Allows to define custom commands that can be called from the browser object for composition purposes. Read more in the Custom Command guide.
overwriteCommand	- commandName (Type: String) - fn (Type: Function) - attachToElement (Type: boolean)	Allows to overwrite any browser command with custom functionality. Use carefully as it can confuse framework users. Read more in the Custom Command guide.
addLocatorStrategy	- strategyName (Type: String) - fn (Type: Function)	Allows to define a custom selector strategy, read more in the Selectors guide.

Remarks

Mobile Flags

If you need to modify your test based on whether or not your session runs on a mobile device, you can access the mobile flags to check.

For example, given this config:

// wdio.conf.js
export const config = {
    // ...
    capabilities: \\{
        platformName: 'iOS',
        app: 'net.company.SafariLauncher',
        udid: '123123123123abc',
        deviceName: 'iPhone',
        // ...
    }
    // ...
}

You can access these flags in your test like so:

// Note: `driver` is the equivalent to the `browser` object but semantically more correct
// you can choose which global variable you want to use
console.log(driver.isMobile) // outputs: true
console.log(driver.isIOS) // outputs: true
console.log(driver.isAndroid) // outputs: false

This can be useful if, for example, you want to define selectors in your page objects based on the device type, like this:

// mypageobject.page.js
import Page from './page'

class LoginPage extends Page {
    // ...
    get username() {
        const selectorAndroid = 'new UiSelector().text("Cancel").className("android.widget.Button")'
        const selectorIOS = 'UIATarget.localTarget().frontMostApp().mainWindow().buttons()[0]'
        const selectorType = driver.isAndroid ? 'android' : 'ios'
        const selector = driver.isAndroid ? selectorAndroid : selectorIOS
        return $(`${selectorType}=${selector}`)
    }
    // ...
}

You can also use these flags to run only certain tests for certain device types:

// mytest.e2e.js
describe('my test', () => {
    // ...
    // only run test with Android devices
    if (driver.isAndroid) {
        it('tests something only for Android', () => {
            // ...
        })
    }
    // ...
})

Events

The browser object is an EventEmitter and a couple of events are emitted for your use cases.

Here is a list of events. Keep in mind that this is not the full list of available events yet. Feel free to contribute to update the document by adding descriptions of more events here.

command

This event is emitted whenever WebdriverIO sends a WebDriver Classic command. It contains the following information:

• command: the command name, e.g. navigateTo
• method: the HTTP method used to send the command request, e.g. POST
• endpoint: the command endpoint, e.g. /session/fc8dbda381a8bea36a225bd5fd0c069b/url
• body: the command payload, e.g. { url: 'https://webdriver.io' }

result

This event is emitted whenever WebdriverIO receives a result of a WebDriver Classic command. It contains the same information as the command event with the addition of the following information:

• result: the command result

bidiCommand

This event is emitted whenever WebdriverIO sends a WebDriver Bidi command to the browser driver. It contains information about:

• method: WebDriver Bidi command methid
• params: associated command parameter (see API)

bidiResult

In case of a successful command execution, the event payload will be:

• type: success
• id: the command id
• result: the command result (see API)

In case of a command error, the event payload will be:

• type: error
• id: the command id
• error: the error code, e.g. invalid argument
• message: details about the error
• stacktrace: a stack trace

request.performance

This is an event to measure WebDriver level operations. Whenever WebdriverIO sends a request to the WebDriver backend, this event will be emitted with some useful information:

• durationMillisecond: Time duration of the request in millisecond.
• error: Error object if the request failed.
• request: Request object. You can find url, method, headers, etc.
• retryCount: If it's 0, the request was the first attempt. It will increase when WebDriverIO retries under the hood.
• success: Boolean to represent the request was succeeded or not. If it's false, error property will be provided as well.

An example event:

Object {
  "durationMillisecond": 0.01770925521850586,
  "error": [Error: Timeout],
  "request": Object { ... },
  "retryCount": 0,
  "success": false,
},

Custom Commands

You can set custom commands on the browser scope to abstract away workflows that are commonly used. Check out our guide on Custom Commands for more information.