Frameworks
WebdriverIO Runner has built-in support for Mocha, Jasmine, and Cucumber.js. You can also integrate it with 3rd-party open-source frameworks, such as Serenity/JS.
To integrate WebdriverIO with a test framework, you need an adapter package available on NPM. Note that the adapter package must be installed in the same location where WebdriverIO is installed. So, if you installed WebdriverIO globally, be sure to install the adapter package globally, too.
Integrating WebdriverIO with a test framework lets you access the WebDriver instance using the global browser
variable in your spec files or step definitions. Note that WebdriverIO will also take care of instantiating and ending the Selenium session, so you don't have to do it yourself.
Using Mocha
First, install the adapter package from NPM:
- npm
- Yarn
- pnpm
npm install @wdio/mocha-framework --save-dev
yarn add @wdio/mocha-framework --dev
pnpm add @wdio/mocha-framework --save-dev
By default WebdriverIO provides an assertion library that is built-in which you can start right away:
describe('my awesome website', () => {
it('should do some assertions', async () => {
await browser.url('https://webdriver.io')
await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
})
})
WebdriverIO supports Mocha's BDD
(default), TDD
, and QUnit
interfaces.
If you like to write your specs in TDD style, set the ui
property in your mochaOpts
config to tdd
. Now your test files should be written like this:
suite('my awesome website', () => {
test('should do some assertions', async () => {
await browser.url('https://webdriver.io')
await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
})
})
If you want to define other Mocha-specific settings, you can do it with the mochaOpts
key in your configuration file. A list of all options can be found on the Mocha project website.
Note: WebdriverIO does not support the deprecated usage of done
callbacks in Mocha:
it('should test something', (done) => {
done() // throws "done is not a function"
})
Mocha Options
The following options can be applied in your wdio.conf.js
to configure your Mocha environment. Note: not all options are supported, e.g. applying the parallel
option will cause an error as the WDIO testrunner has its own way to run tests in parallel. The following options however are supported:
require
The require
option is useful when you want to add or extend some basic functionality (WebdriverIO framework option).
Type: string|string[]
Default: []
compilers
Use the given module(s) to compile files. Compilers will be included before requires (WebdriverIO framework option).
Type: string[]
Default: []
allowUncaught
Propagate uncaught errors.
Type: boolean
Default: false
bail
Bail after first test failure.
Type: boolean
Default: false
checkLeaks
Check for global variable leaks.
Type: boolean
Default: false
delay
Delay root suite execution.
Type: boolean
Default: false
fgrep
Test filter given string.
Type: string
Default: null
forbidOnly
Tests marked only
fail the suite.
Type: boolean
Default: false
forbidPending
Pending tests fail the suite.
Type: boolean
Default: false
fullTrace
Full stacktrace upon failure.
Type: boolean
Default: false
global
Variables expected in global scope.
Type: string[]
Default: []
grep
Test filter given regular expression.
Type: RegExp|string
Default: null
invert
Invert test filter matches.
Type: boolean
Default: false
retries
Number of times to retry failed tests.
Type: number
Default: 0
timeout
Timeout threshold value (in ms).
Type: number
Default: 30000
Using Jasmine
First, install the adapter package from NPM:
- npm
- Yarn
- pnpm
npm install @wdio/jasmine-framework --save-dev
yarn add @wdio/jasmine-framework --dev
pnpm add @wdio/jasmine-framework --save-dev
You can then configure your Jasmine environment by setting a jasmineOpts
property in your config. A list of all options can be found on the Jasmine project website.
Intercept Assertion
The Jasmine framework allows it to intercept each assertion in order to log the state of the application or website, depending on the result.
For example, it is pretty handy to take a screenshot every time an assertion fails. In your jasmineOpts
you can add a property called expectationResultHandler
that takes a function to execute. The function’s parameters provide information about the result of the assertion.
The following example demonstrates how to take a screenshot if an assertion fails:
jasmineOpts: {
defaultTimeoutInterval: 10000,
expectationResultHandler: function(passed, assertion) {
/**
* only take screenshot if assertion failed
*/
if(passed) {
return
}
browser.saveScreenshot(`assertionError_${assertion.error.message}.png`)
}
},
Note: You cannot stop test execution to do something async. It might happen that the command takes too much time and the website state has changed. (Though usually, after another 2 commands the screenshot is taken anyway, which still gives some valuable information about the error.)
Jasmine Options
The following options can be applied in your wdio.conf.js
to configure your Jasmine environment using the jasmineOpts
property. For more information on these configuration options, check out the Jasmine docs.
defaultTimeoutInterval
Default Timeout Interval for Jasmine operations.
Type: number
Default: 60000
helpers
Array of filepaths (and globs) relative to spec_dir to include before jasmine specs.
Type: string[]
Default: []
requires
The requires
option is useful when you want to add or extend some basic functionality.
Type: string[]
Default: []
random
Whether to randomize spec execution order.
Type: boolean
Default: true
seed
Seed to use as the basis of randomization. Null causes the seed to be determined randomly at the start of execution.
Type: Function
Default: null
failSpecWithNoExpectations
Whether to fail the spec if it ran no expectations. By default a spec that ran no expectations is reported as passed. Setting this to true will report such spec as a failure.
Type: boolean
Default: false
oneFailurePerSpec
Whether to cause specs to only have one expectation failure.
Type: boolean
Default: false
specFilter
Function to use to filter specs.
Type: Function
Default: (spec) => true
grep
Only run tests matching this string or regexp. (Only applicable if no custom specFilter
function is set)
Type: string|Regexp
Default: null