Skip to main content

WebdriverIOConfig

WebdriverIO configuration object, with Serenity/JS-specific additions.

Integrating WebdriverIO with Serenity/JS

// wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIOConfig = {

  framework: '@serenity-js/webdriverio',

  serenity: {
    runner: 'cucumber',
    // runner: 'mocha',
    // runner: 'jasmine',

    crew: [
      // Optional, print test execution results to standard output
      '@serenity-js/console-reporter',

      // Optional, produce Serenity BDD reports
      // and living documentation (HTML)
      '@serenity-js/serenity-bdd',
      [ '@serenity-js/core:ArtifactArchiver', {
          outputDirectory: 'target/site/serenity'
      } ],

      // Optional, automatically capture screenshots
      // upon interaction failure
      [ '@serenity-js/web:Photographer', {
          strategy: 'TakePhotosOfFailures'
          // strategy: 'TakePhotosOfInteractions'
      } ],
    ]
  },

  // Configure your Cucumber runner
  cucumberOpts: {
    // see Cucumber configuration options below
  },

  // ... or Jasmine runner
  jasmineOpts: {
    // see Jasmine configuration options below
  },

  // ... or Mocha runner
  mochaOpts: {
     // see Mocha configuration options below
  },

  runner: 'local',

  specs: [
    './features/*.feature',

    // or for Mocha/Jasmine
    // './*.spec.ts'
  ],

  // Any other WebdriverIO configuration
}

Learn more

Hierarchy

  • Testrunner
    • WebdriverIOConfig

Index

Properties

Methods

Properties

externaloptionalprotocol

protocol?: string = ```ts 'http' ```

Protocol to use when communicating with the Selenium standalone server (or driver).

externaloptionalhostname

hostname?: string = ```ts 'localhost' ```

Host of your WebDriver server.

externaloptionalport

port?: number

Port your WebDriver server is on.

externaloptionalpath

path?: string = ```ts '/' ```

Path to WebDriver endpoint or grid server.

externaloptionalqueryParams

queryParams?: {}

Query paramaters that are propagated to the driver server.

Type declaration

  • [name string]: string

externaloptionaluser

user?: string

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.

externaloptionalkey

key?: string

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.

externaloptionallogLevel

logLevel?: WebDriverLogTypes = WebDriverLogTypes

Level of logging verbosity.

externaloptionallogLevels

logLevels?: Record<string, WebDriverLogTypes>

Set specific log levels per logger use ā€˜silentā€™ level to disable logger

externaloptionalconnectionRetryTimeout

connectionRetryTimeout?: number = ```ts 120000 ```

Timeout for any WebDriver request to a driver or grid.

externaloptionalconnectionRetryCount

connectionRetryCount?: number = ```ts 3 ```

Count of request retries to the Selenium server.

externaloptionalheaders

headers?: {}

Specify custom headers to pass into every request.

Type declaration

  • [name string]: string

externaloptionalagent

agent?: { http: Agent; https: Agent } = { http: Agent; https: Agent }

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

Type declaration

  • externalhttp: Agent
  • externalhttps: Agent

externaloptionaltransformRequest

transformRequest?: (requestOptions: RequestLibOptions) => RequestLibOptions

Type declaration

    • (requestOptions: RequestLibOptions): RequestLibOptions

    • Function intercepting HTTP request options before a WebDriver request is made.

      Parameters

      • externalrequestOptions: RequestLibOptions

      Returns RequestLibOptions

externaloptionaltransformResponse

transformResponse?: (response: RequestLibResponse, requestOptions: RequestLibOptions) => RequestLibResponse

Type declaration

    • (response: RequestLibResponse, requestOptions: RequestLibOptions): RequestLibResponse

    • Function intercepting HTTP response objects after a WebDriver response has arrived.

      Parameters

      • externalresponse: RequestLibResponse
      • externalrequestOptions: RequestLibOptions

      Returns RequestLibResponse

externaloptionalenableDirectConnect

enableDirectConnect?: boolean

Appium direct connect options (see: https://appiumpro.com/editions/86-connecting-directly-to-appium-hosts-in-distributed-environments)

externaloptionalstrictSSL

strictSSL?: boolean = ```ts true ```

Whether it requires SSL certificates to be valid in HTTP/s requests for an environment which cannot get process environment well.

externaloptionaloutputDir

outputDir?: string

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.

externaloptionalcacheDir

cacheDir?: string

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.

externaloptionalautomationProtocol

automationProtocol?: SupportedProtocols

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.

@deprecated

this option will be removed in future versions of WebdriverIO. We recommend to use WebDriver for browser or mobile automation.

externaloptionalregion

region?: SauceRegions

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.

externaloptionalheadless

headless?: boolean

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

externaloptionalbaseUrl

baseUrl?: string

Shorten url command calls by setting a base URL.

externaloptionalwaitforTimeout

waitforTimeout?: number

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.

externaloptionalwaitforInterval

waitforInterval?: number

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

externalcapabilities

capabilities: RemoteCapabilities

Defines a set of capabilities you want to run in your testrunner session. Check out the WebDriver Protocol for more details. If you want to run a multiremote session you need to define instead of an array of capabilities an object that has an arbitrary browser instance name as string and its capabilities as values.

@example
// wdio.conf.js
export const config = {
  // define parallel running capabilities
  capabilities: [{
    browserName: 'safari',
    platformName: 'MacOS 10.13',
    ...
  }, {
    browserName: 'microsoftedge',
    platformName: 'Windows 10',
    ...
  }]
}
@example
// wdio.conf.js
export const config = {
  // multiremote example
  capabilities: {
    browserA: {
      browserName: 'chrome',
      browserVersion: 86
      platformName: 'Windows 10'
    },
    browserB: {
      browserName: 'firefox',
      browserVersion: 74
      platformName: 'Mac OS X'
    }
  }
})

externaloptionalrunner

runner?: browser | local | [browser, BrowserRunnerOptions] | [local, never]

Type of runner

  • local: every spec file group is spawned in its own local process running an independant browser session
  • browser: all spec files are run within the browser

externaloptionalrootDir

rootDir?: string

Project root directory path.

externaloptionalspecs

specs?: (string | string[])[]

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.

externaloptionalexclude

exclude?: string[]

Exclude specs from test execution.

externaloptionalsuites

suites?: Record<string, string[] | string[][]>

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

externaloptionalmaxInstances

maxInstances?: number

Maximum number of total parallel running workers.

externaloptionalmaxInstancesPerCapability

maxInstancesPerCapability?: number

Maximum number of total parallel running workers per capability.

externaloptionalinjectGlobals

injectGlobals?: boolean = ```ts true ```

Inserts WebdriverIOā€™s globals (e.g. browser, $ and $$) into the global environment. If you set to false, you should import from @wdio/globals, e.g.:

import { browser, $, $$, expect } from '@wdio/globals'

Note: WebdriverIO doesnā€™t handle injection of test framework specific globals.

externaloptionalbail

bail?: number

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.

externaloptionalupdateSnapshots

updateSnapshots?: all | new | none

Set to true if you want to update your snapshots.

externaloptionalresolveSnapshotPath

resolveSnapshotPath?: (testPath: string, snapExtension: string) => string

Type declaration

    • (testPath: string, snapExtension: string): string

    • Overrides default snapshot path. For example, to store snapshots next to test files.

      Parameters

      • externaltestPath: string
      • externalsnapExtension: string

      Returns string

externaloptionalspecFileRetries

specFileRetries?: number

The number of retry attempts for an entire specfile when it fails as a whole.

externaloptionalspecFileRetriesDelay

specFileRetriesDelay?: number

Delay in seconds between the spec file retry attempts

externaloptionalspecFileRetriesDeferred

specFileRetriesDeferred?: boolean

Whether or not retried spec files should be retried immediately or deferred to the end of the queue

externaloptionalgroupLogsByTestSpec

groupLogsByTestSpec?: boolean = ```ts false ```

Choose the log output view. If set to ā€œfalseā€ logs from different test files will be printed in real-time. Please note that this may result in the mixing of log outputs from different Test Specs when running in parallel. If set to ā€œtrueā€ log outputs will be grouped by test files and printed only when the test is completed. By default, it is set to ā€œfalseā€ so logs are printed in real-time.

externaloptionalservices

services?: ServiceEntry[]

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

externaloptionalframework

framework?: string

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

externaloptionalreporters

reporters?: ReporterEntry[]

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.

externaloptionalreporterSyncInterval

reporterSyncInterval?: number

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).

externaloptionalreporterSyncTimeout

reporterSyncTimeout?: number

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

externaloptionalexecArgv

execArgv?: string[]

Node arguments to specify when launching child processes.

externaloptionalrunnerEnv

runnerEnv?: Record<string, any>

A set of environment variables to be injected into the worker process.

externaloptionalfilesToWatch

filesToWatch?: string[]

Files to watch when running wdio with the --watch flag.

externaloptionalcucumberFeaturesWithLineNumbers

cucumberFeaturesWithLineNumbers?: string[] = string[]

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

externaloptionalwatch

watch?: boolean

flags

externaloptionalshard

shard?: ShardOptions

Shard tests and execute only the selected shard. Specify in the one-based form like { total: 5, current: 2 }.

externaloptionalmochaOpts

mochaOpts?: MochaOpts

framework options

externaloptionaljasmineOpts

jasmineOpts?: JasmineOpts

externaloptionalcucumberOpts

cucumberOpts?: CucumberOpts

externaloptionalautoCompileOpts

autoCompileOpts?: AutoCompileConfig

autocompile options

optionalserenity

serenity?: SerenityConfig & { runner?: string }

Serenity/JS configuration with an additional runner entry allowing to specify the test runner, such as cucumber, mocha, or jasmine.

Learn more

Methods

externaloptionalonPrepare

onPrepare?:

externaloptionalonComplete

onComplete?:

externaloptionalonWorkerStart

onWorkerStart?:

externaloptionalonWorkerEnd

onWorkerEnd?:

externaloptionalbefore

before?:

externaloptionalafter

after?:

externaloptionalbeforeSession

beforeSession?:

externaloptionalafterSession

afterSession?:

externaloptionalonReload

onReload?:

externaloptionalbeforeSuite

beforeSuite?:

externaloptionalafterSuite

afterSuite?:

externaloptionalbeforeTest

beforeTest?:

externaloptionalafterTest

afterTest?:

externaloptionalbeforeHook

beforeHook?:

externaloptionalafterHook

afterHook?:

externaloptionalbeforeCommand

beforeCommand?:

externaloptionalafterCommand

afterCommand?:

externaloptionalbeforeAssertion

beforeAssertion?:

externaloptionalafterAssertion

afterAssertion?: