Options

Based on the setup type (e.g. using the raw protocol bindings, WebdriverIO as standalone package or the WDIO testrunner) there is a different set of options available to control the environment.

WebDriver Options#

The following options are defined when using the webdriver protocol package:

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

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. If you don't use a cloud provider this can be used to authenticate any other WebDriver backend.

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. If you don't use a cloud provider this can be used to authenticate any other WebDriver backend.

Type: String 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.

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

connectionRetryCount#

Maximum count of request retries to the Selenium server.

Type: Number
Default: 3

agent#

Allows you to use a custom http/https/http2 agent to make requests.

Type: Object
Default:

{
    http: new http.Agent({ keepAlive: true }),
    https: new https.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

strictSSL#

Whether it does not require SSL certificate to be valid. It can be set via an environment variables as STRICT_SSL or strict_ssl.

Type: Boolean
Default: true

WebdriverIO#

The following options (including the ones listed above) can be used with WebdriverIO in standalone:

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

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

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

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)

Testrunner Options#

The following options (including the ones listed above) are defined only for running WebdriverIO with the WDIO 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' }]

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

specFileRetriesDelay#

Delay in seconds between the spec file retry attempts

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

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 and cucumberOpts#

Specific framework-related options. See the framework adapter documentation on which options are available. Read more on this in Frameworks.

Type: Object
Default: { timeout: 10000 }

cucumberFeaturesWithLineNumbers#

List of cucumber features with line numbers (when using cucumber framework).

Type: String[] Default: []

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'
    }]
]

reporterSyncInterval#

Determines in which interval the reporter should check if they are synchronised if they report their logs asynchronously (e.g. if logs are streamed to a 3rd party vendor).

Type: Number
Default: 100 (ms)

reporterSyncTimeout#

Determines the maximum time reporters have to finish uploading all their logs until an error is being thrown by the testrunner.

Type: Number
Default: 5000 (ms)

execArgv#

Node arguments to specify when launching child processes.

Type: String[] Default: null

Hooks#

The WDIO testrunner allows you to set hooks to be triggered 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 (e.g. information about the test suite or test). Read more about all hook properties in our example config.

Note: Some hooks (onPrepare, onWorkerStart and onComplete) are executed in a different process and therefor can not share any global data with the other hooks that live in the worker process.

onPrepare#

Gets executed once before all workers get launched.

Parameters:

config (object): WebdriverIO configuration object
param (object[]): list of capabilities details

onWorkerStart#

Gets executed before a worker process is spawned and can be used to initialise specific service for that worker as well as modify runtime environments in an async fashion.

Parameters:

cid (string): capability id (e.g 0-0)
caps (object): containing capabilities for session that will be spawn in the worker
specs (string[]): specs to be run in the worker process
args (object): object that will be merged with the main configuration once worker is initialised
execArgv (string[]): list of string arguments passed to the worker process

beforeSession#

Gets executed just before initialising the webdriver session and test framework. It allows you to manipulate configurations depending on the capability or spec.

Parameters:

config (object): WebdriverIO configuration object
caps (object): containing capabilities for session that will be spawn in the worker
specs (string[]): specs to be run in the worker process

before#

Gets executed before test execution begins. At this point you can access to all global variables like browser. It is the perfect place to define custom commands.

Parameters:

caps (object): containing capabilities for session that will be spawn in the worker
specs (string[]): specs to be run in the worker process
browser (object): instance of created browser/device session

beforeSuite#

Hook that gets executed before the suite starts

Parameters:

suite (object): suite details

beforeHook#

Hook that gets executed before a hook within the suite starts (e.g. runs before calling beforeEach in Mocha)

Parameters:

test (object): test details
context (object): test context
stepData (object): step data (Cucumber only)
world (object): world context (Cucumber only)

afterHook#

Hook that gets executed after a hook within the suite ends (e.g. runs after calling afterEach in Mocha)

Parameters:

test (object): test details
context (object): test context
result (object): hook result (contains error, result, duration, passed, retries properties)
stepData (object): step data (Cucumber only)
world (object): world context (Cucumber only)

beforeTest#

Function to be executed before a test (in Mocha/Jasmine) starts.

Parameters:

test (object): test details
context (object): test context

beforeCommand#

Runs before a WebdriverIO command gets executed.

Parameters:

commandName (string): command name
args (*): arguments that command would receive

afterCommand#

Runs after a WebdriverIO command gets executed.

Parameters:

commandName (string): command name
args (*): arguments that command would receive
result (number): 0 - command success, 1 - command error
error (Error): error object if any

afterTest#

Function to be executed after a test (in Mocha/Jasmine) ends.

Parameters:

test (object): test details
context (object): test context
result (object): hook result (contains error, result, duration, passed, retries properties)

afterSuite#

Hook that gets executed after the suite has ended

Parameters:

suite (object): suite details

after#

Gets executed after all tests are done. You still have access to all global variables from the test.

Parameters:

result (number): 0 - test pass, 1 - test fail
caps (object): containing capabilities for session that will be spawn in the worker
specs (string[]): specs to be run in the worker process

afterSession#

Gets executed right after terminating the webdriver session.

Parameters:

config (object): WebdriverIO configuration object
caps (object): containing capabilities for session that will be spawn in the worker
specs (string[]): specs to be run in the worker process

onComplete#

Gets executed after all workers got shut down and the process is about to exit. An error thrown in the onComplete hook will result in the test run failing.

Parameters:

exitCode (number): 0 - success, 1 - fail
config (object): WebdriverIO configuration object
caps (object): containing capabilities for session that will be spawn in the worker
result (object): results object containing test results

onReload#

Gets executed when a refresh happens.

Parameters:

oldSessionId (string): session ID of the old session
newSessionId (string): session ID of the new session

beforeFeature#

Runs before a Cucumber Feature.

Parameters:

uri: (string): path to feature file
feature: (object): Cucumber feature object
scenario: (object): Cucumber scenario object

afterFeature#

Runs after a Cucumber Feature.

Parameters:

uri: (string): path to feature file
feature: (object): Cucumber feature object
scenario: (object): Cucumber scenario object

beforeScenario#

Runs before a Cucumber Scenario.

Parameters:

uri: (string): path to feature file
feature: (object): Cucumber feature object
scenario: (object): Cucumber scenario object
sourceLocation: (object): location of step

afterScenario#

Runs after a Cucumber Scenario.

Parameters:

uri: (string): path to feature file
feature: (object): Cucumber feature object
scenario: (object): Cucumber scenario object
result: (object): scenario result
sourceLocation: (object): location of step

beforeStep#

Runs before a Cucumber Step.

Parameters:

uri: (string): path to feature file
feature: (object): Cucumber feature object
step: (object): Cucumber step object

afterStep#

Runs after a Cucumber Step.

Parameters:

details: (object): step details (contains uri, feature and step property objects)
context: (object): Cucumber context object
result (object): step result (contains error, result, duration, passed, retries properties)