Configuration
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.
Next to the WebDriver based capabilities you can apply browser and vendor specific options that allow deeper configuration to the remote browser or device. These are documented in the corresponding vendor docs, e.g.:
goog:chromeOptions
: for Google Chromemoz:firefoxOptions
: for Mozilla Firefoxms:edgeOptions
: for Microsoft Edgesauce:options
: for Sauce Labsbstack:options
: for BrowserStackselenoid:options
: for Selenoid
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: `chrome`, `edge`, `firefox`, `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: 120000
connectionRetryCount
Maximum count of request retries to the Selenium server.
Type: Number
Default: 3
agent
Allows you to use a customhttp
/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 WebDriver request and when connect to browser through Puppeteer using CDP protocol.
These headers aren't passed into browser request. If you are looking for modifying request headers of browser requests, please get involved in #6361!
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
enableDirectConnect
Whether enable Appium direct connection feature. It does nothing if the response did not have proper keys while the flag is enabled.
Type: Boolean
Default: true
cacheDir
The path to the root of the cache directory. This directory is used to store all drivers that are downloaded when attempting to start a session.
Type: String
Default: process.env.WEBDRIVER_CACHE_DIR || os.tmpdir()
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/
, thenbaseUrl
is prepended (except thebaseUrl
path, if it has one). - If your
url
parameter starts without a scheme or/
(likesome/path
), then the fullbaseUrl
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 data centers: 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)
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. You can either specify a glob pattern to match multiple files at once or wrap a glob or set of paths into an array to run them within a single worker process. All paths are seen as relative from the config file path.
Type: (String | String[])[]
Default: []
exclude
Exclude specs from test execution. All paths are seen as relative from the config file path.
Type: String[]
Default: []