Frameworks
The WDIO runner currently supports Mocha, Jasmine, and Cucumber.
To integrate each framework with WebdriverIO, there are adapter packages on NPM which must be installed. You cannot install the adapters just anywhere; these packages must be installed in the same location WebdriverIO is installed. So, if you installed WebdriverIO globally, be sure to install the adapter package globally, too.
Within your spec files (or step definitions), you can access the WebDriver instance using the global variable browser
. (You don't need to initiate or end the Selenium session. This is taken care of by the wdio
testrunner.)
Using Mochaβ
First, install the adapter package from NPM:
- npm
- Yarn
npm install @wdio/mocha-framework --save-dev
yarn add @wdio/mocha-framework --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"
})
If you want to run something asynchronously, you can either use the browser.call
command or custom commands.
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
npm install @wdio/jasmine-framework --save-dev
yarn add @wdio/jasmine-framework --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
invertGrepβ
If true it inverts the matching tests and only runs tests that don't match with the expression used in grep
. (Only applicable if no custom specFilter
function is set)
Type: boolean
Default: false
Using Cucumberβ
First, install the adapter package from NPM:
- npm
- Yarn
npm install @wdio/cucumber-framework --save-dev
yarn add @wdio/cucumber-framework --dev
If you want to use Cucumber, set the framework
property to cucumber
by adding framework: 'cucumber'
to the config file.
Options for Cucumber can be given in the config file with cucumberOpts
. Check out the whole list of options here.
To get up and running quickly with Cucumber, have a look on our cucumber-boilerplate
project that comes with all the step definitions you need to get stared, and you'll be writing feature files right away.
Cucumber Optionsβ
The following options can be applied in your wdio.conf.js
to configure your Cucumber environment using the cucumberOpts
property:
backtraceβ
Show full backtrace for errors.
Type: Boolean
Default: true
requireModuleβ
Require modules prior to requiring any support files.
Type: string[]
Default: []
Example:
cucumberOpts: {
requireModule: ['@babel/register']
// or
requireModule: [
[
'@babel/register',
{
rootMode: 'upward',
ignore: ['node_modules']
}
]
]
}
failAmbiguousDefinitionsβ
Treat ambiguous definitions as errors. Please note that this is a @wdio/cucumber-framework
specific option and not recognized by cucumber-js itself.
Type: boolean
Default: false
failFastβ
Abort the run on first failure.
Type: boolean
Default: false
ignoreUndefinedDefinitionsβ
Treat undefined definitions as warnings. Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself.
Type: boolean
Default: false
namesβ
Only execute the scenarios with name matching the expression (repeatable).
Type: RegExp[]
Default: []
profileβ
Specify the profile to use.
Type: string[]
Default: []
requireβ
Require files containing your step definitions before executing features. You can also specify a glob to your step definitions.
Type: string[]
Default: []
Example:
cucumberOpts: {
require: [path.join(__dirname, 'step-definitions', 'my-steps.js')]
}
snippetSyntaxβ
Specify a custom snippet syntax.
Type: string
Default: null
snippetsβ
Hide step definition snippets for pending steps.
Type: boolean
Default: true
sourceβ
Hide source uris.
Type: boolean
Default: true
strictβ
Fail if there are any undefined or pending steps.
Type: boolean
Default: false
tagExpressionβ
Only execute the features or scenarios with tags matching the expression. Please see the Cucumber documentation for more details.
Type: string
Default: null
tagsInTitleβ
Add cucumber tags to feature or scenario name.
Type: boolean
Default: false
timeoutβ
Timeout in milliseconds for step definitions.
Type: number
Default: 30000
Skipping tests in cucumberβ
Note that if you want to skip a test using regular cucumber test filtering capabilities available in cucumberOpts
, you will do it for all the browsers and devices configured in the capabilities. In order to be able to skip scenarios only for specific capabilities combinations without having a session started if not necessary, webdriverio provides the following specific tag syntax for cucumber:
@skip([condition])
were condition is an optional combination of capabilities properties with their values that when all matched with cause the tagged scenario or feature to be skipped. Of course you can add several tags to scenarios and features to skip a tests under several different conditions.
Here you have some examples of this syntax:
@skip()
: will always skip the tagged item@skip(browserName="chrome")
: the test will not be executed against chrome browsers.@skip(browserName="firefox";platformName="linux")
: will skip the test in firefox over linux executions.@skip(browserName=["chrome","firefox"])
: tagged items will be skipped for both chrome and firefox browsers.@skip(browserName=/i.*explorer/
: capabilities with browsers matching the regexp will be skipped (likeiexplorer
,internet explorer
,internet-explorer
, ...).
Import Step Definition Helperβ
In order to use step definition helper like Given
, When
or Then
or hooks, you are suppose to import then from @cucumber/cucumber
, e.g. like this:
import { Given, When, Then } from '@cucumber/cucumber'
Now, if you use Cucumber already for other types of tests unrelated to WebdriverIO for which you use a specific version you need to import these helpers in your e2e tests from the WebdriverIO Cucumber package, e.g.:
import { Given, When, Then } from '@wdio/cucumber-framework'
This ensures that you use the right helpers within the WebdriverIO framework and allows you to use an independant Cucumber version for other types of testing.