Edit

Options

WebdriverIO is not just a binding for the WebDriver protocol (like Selenium). It is a full test framework with numerous additional features and utilities. It is based on the webdriver package, which is a lightweight, non-opinionated implementation of the WebDriver specification including mobile commands supported by Appium.

WebdriverIO takes the protocol commands and creates smart user commands that makes using the protocol for test automation much easier.

WebdriverIO also enhances the WebDriver package with additional commands. They share the same set of options when run in a standalone script. But when testing starts from @wdio/cli (the WDIO testrunner), there are some additional options available for you to use in wdio.conf.js.

WebDriver Options

The following options are defined:

protocol

Protocol to use when communicating with the driver server.

Type: String
Default: http

hostname

Host of your driver server.

Type: String
Default: localhost

port

Port your driver server is on.

Type: Number
Default: 4444

path

Path to driver server endpoint.

Type: String
Default: /

queryParams

Query parameters that are propagated to the driver server.

Type: Object
Default: null

capabilities

Defines the capabilities you want to run in your WebDriver session. Check out the WebDriver Protocol for more details. If you run an older driver that doesn't support the WebDriver protocol, you’ll need to use the JSONWireProtocol capabilities to successfully run a session.

Additionally, a useful utility is the Sauce Labs Automated Test Configurator, which helps you create this object by clicking together your desired capabilities.

Type: Object
Default: null

Example:

{
    browserName: 'chrome', // options: `firefox`, `chrome`, `opera`, `safari`
    browserVersion: '27.0', // browser version
    platformName: 'Windows 10' // OS platform
}

If you’re running web or native tests on mobile devices, capabilities differs from the WebDriver protocol. See the Appium Docs for more details.

logLevel

Level of logging verbosity.

Type: String
Default: info
Options: trace | debug | info | warn | error | silent

outputDir

Directory to store all testrunner log files (including reporter logs and wdio logs). If not set, all logs are streamed to stdout. Since most reporters are made to log to stdout, it is recommended to only use this option for specific reporters where it makes more sense to push report into a file (like the junit reporter, for example).

When running in standalone mode, the only log generated by WebdriverIO will be the wdio log.

Type: String
Default: null

connectionRetryTimeout

Timeout for any WebDriver request to a driver or grid.

Type: Number
Default: 90000

connectionRetryCount

Maximum count of request retries to the Selenium server.

Type: Number
Default: 3

agent

Allows you to use a customhttp/https agent to make requests.

Type: Object
Default: new http(s).Agent({ keepAlive: true })

headers

Specify custom headers to pass into every request.

Type: Object
Default: {}

transformRequest

Function intercepting HTTP request options before a WebDriver request is made

Type: (RequestOptions) => RequestOptions
Default: none

transformResponse

Function intercepting HTTP response objects after a WebDriver response has arrived. The function is passed the original response object as the first and the corresponding RequestOptions as the second argument.

Type: (Response, RequestOptions) => Response
Default: none

---

WDIO Options

The following options are defined for running WebdriverIO with the @wdio/cli testrunner:

specs

Define specs for test execution.

Type: String[]
Default: []

exclude

Exclude specs from test execution.

Type: String[]
Default: []

suites

An object describing various of suites, which you can then specify with the --suite option on the wdio CLI.

Type: Object
Default: {}

capabilities

The same as the capabilities section described above, except with the option to specify either a multiremote object, or multiple WebDriver sessions in an array for parallel execution.

Type: Object|Object[]
Default: [{ maxInstances: 5, browserName: 'firefox' }]

baseUrl

Shorten url command calls by setting a base URL.

• If your url parameter starts with /, then baseUrl is prepended (except the baseUrl path, if it has one).
• If your url parameter starts without a scheme or / (like some/path), then the full baseUrl is prepended directly.

Type: String
Default: null

maxInstances

Maximum number of total parallel running workers.

Type: Number
Default: 100

maxInstancesPerCapability

Maximum number of total parallel running workers per capability.

Type: Number
Default: 100

bail

If you want your test run to stop after a specific number of test failures, use bail. (It defaults to 0, which runs all tests no matter what.) Note: Please be aware that when using a third party test runner (such as Mocha), additional configuration might be required.

Type: Number
Default: 0 (don't bail; run all tests)

specFileRetries

The number of times to retry an entire specfile when it fails as a whole.

Type: Number
Default: 0

specFileRetriesDeferred

Whether or not retried specfiles should be retried immediately or deferred to the end of the queue.

Type: Boolean
Default: true

waitforTimeout

Default timeout for all waitFor* commands. (Note the lowercase f in the option name.) This timeout only affects commands starting with waitFor* and their default wait time.

To increase the timeout for a test, please see the framework docs.

Type: Number
Default: 3000

waitforInterval

Default interval for all waitFor* commands to check if an expected state (e.g., visibility) has been changed.

Type: Number
Default: 500

services

Services take over a specific job you don't want to take care of. They enhance your test setup with almost no effort.

Type: String[]|Object[]
Default: []

framework

Defines the test framework to be used by the WDIO testrunner.

Type: String
Default: mocha
Options: mocha | jasmine

mochaOpts | jasmineNodeOpts

Specific framework-related options. See the framework adapter documentation on which options are available.

Type: Object
Default: { timeout: 10000 }

reporters

List of reporters to use. A reporter can be either a string, or an array of ['reporterName', { /* reporter options */}] where the first element is a string with the reporter name and the second element an object with reporter options.

Type: String[]|Object[]
Default: []

Example:

reporters: [
    'dot',
    'spec'
    ['junit', {
        outputDir: `${__dirname}/reports`,
        otherOption: 'foobar'
    }]
]

automationProtocol

Define the protocol you want to use for your browser automation. Currently only webdriver and devtools are supported, as these are the main browser automation technologies available.

If you want to automate the browser using devtools, make sure you have the NPM package installed ($ npm install --save-dev devtools).

Type: String Default: webdriver

execArgv

Node arguments to specify when launching child processes.

Type: String[] Default: null

user

Your cloud service username (only works for Sauce Labs, Browserstack, TestingBot, CrossBrowserTesting or LambdaTest accounts). If set, WebdriverIO will automatically set connection options for you.

Type: String Default: null

key

Your cloud service access key or secret key (only works for Sauce Labs, Browserstack, TestingBot, CrossBrowserTesting or LambdaTest accounts). If set, WebdriverIO will automatically set connection options for you.

Type: String Default: null

region

If running on Sauce Labs, you can choose to run tests between different datacenters: US or EU. To change your region to EU, add region: 'eu' to your config.

Note: This only has an effect if you provide user and key options that are connected to your Sauce Labs account.

Type: String
Default: us

(only for vm and or em/simulators)

headless

Sauce Labs provides a headless offering that allows you to run Chrome and Firefox tests headless.

Note: This only has an effect if you provide user and key options that are connected to your Sauce Labs account.

Type: Boolean
Default: false

(only for VM or EM/simulators)

Hooks

WebdriverIO allows you to set hooks to trigger at specific times of the test lifecycle. This allows custom actions (e.g., take screenshot if a test fails).

Every hook has as parameter specific information about the lifecycle (i.e. information about the test suite or test).

The following hooks are available: onPrepare, onWorkerStart, beforeSession, before, beforeSuite, beforeHook, afterHook, beforeTest, beforeCommand, afterCommand, afterTest, afterSuite, after, afterSession, onComplete, onReload, beforeFeature, beforeScenario, beforeStep, afterStep, afterScenario, afterFeature.

Type: Function
Default: null

Example:

// wdio.conf.js
exports.config = {
    // ...
    afterTest: (test, context, { error, result, duration, passed, retries }) => {
        console.log(`Finished test "${test.parent} - ${test.title}"`)
    }
    // ...