expect-webdriverio

TypeScript / JS Autocomplete | Examples | Extending Matchers

WebdriverIO Assertion library inspired by expect

Key Features

waits for expectation to succeed
detailed error messages
works in Mocha, Cucumber, Jest, Jasmine
builtin types for TypeScript and JS autocompletion

Installation

npm install expect (Jasmine and Jest users should skip this step)
npm install expect-webdriverio

NOTE: WebdriverIO v5.16.11 or higher is required!

Usage

In your wdio.conf.js

beforeSession () { // before hook works as well
    require('expect-webdriverio')
},

In your test

const $button = $('button')
expect($button).toBeDisplayed()

See more Examples

API

See available Matchers

Besides of the expect-webdriverio matchers you can use builtin Jest's expect assertions or expect/expectAsync for Jasmine.

Default Options

{
    wait: 2000, // ms to wait for expectation to succeed
    interval: 100, // interval between attempts
}

Set options like this:

beforeSession () { // before hook works as well
    require('expect-webdriverio').setOptions({ wait: 5000 })
},

Matcher Options

Every matcher can take several options that allows you to modify the assertion:

Command Options

Name	Type	Details
`wait`	number	time in ms to wait for expectation to succeed. Default: `3000`
`interval`	number	interval between attempts. Default: `100`
`message`	string	user message to prepend before assertion error

String Options

This options can be applied in addition to the command options when strings are being asserted.

Name	Type	Details
`ignoreCase`	boolean	apply `toLowerCase` to both actual and expected values
`trim`	boolean	apply `trim` to actual value
`containing`	boolean	expect actual value to contain expected value, otherwise strict equal.
`asString`	boolean	might be helpful to force converting property value to string

Number Options

This options can be applied in addition to the command options when numbers are being asserted.

Name	Type	Details
`eq`	number	equals
`lte`	number	less then equals
`gte`	number	greater than or equals

Browser Matchers

toHaveUrl

Checks if browser is on a specifc page.

Usage

browser.url('https://webdriver.io/')
expect(browser).toHaveUrl('https://webdriver.io')

toHaveTitle

Checks if website has a specific title.

Usage

browser.url('https://webdriver.io/')
expect(browser).toHaveTitle('WebdriverIO · Next-gen WebDriver test framework for Node.js')

Element Matchers

toBeDisplayed

Calls isDisplayed on given element.

Usage

const elem = $('#someElem')
expect(elem).toBeDisplayed()

toBeVisible

Same as toBeDisplayed.

Usage

const elem = $('#someElem')
expect(elem).toBeVisible()

toExist

Calls isExisting on given element.

Usage

const elem = $('#someElem')
expect(elem).toExist()

toBePresent

Same as toExist.

Usage

const elem = $('#someElem')
expect(elem).toBePresent()

toBeExisting

Same as toExist.

Usage

const elem = $('#someElem')
expect(elem).toBeExisting()

toBeFocused

Checks if element has focus. This assertion only works in a web context.

Usage

const elem = $('#someElem')
expect(elem).toBeFocused()

toHaveAttribute

Checks if an element has a certain attribute with a specific value.

Usage

const myInput = $('input')
expect(myInput).toHaveAttribute('class', 'form-control')

toHaveAttr

Same as toHaveAttribute.

Usage

const myInput = $('input')
expect(myInput).toHaveAttr('class', 'form-control')

toHaveAttributeContaining

Checks if an element has a certain attribute that contains a value.

Usage

const myInput = $('input')
expect(myInput).toHaveAttributeContaining('class', 'form')

toHaveAttrContaining

Same as toHaveAttributeContaining.

Usage

const myInput = $('input')
expect(myInput).toHaveAttrContaining('class', 'form')

toHaveClass

Checks if an element has a certain class name.

Usage

const myInput = $('input')
expect(myInput).toHaveClass('form-control', { message: 'Not a form control!', })

toHaveClassContaining

Checks if an element has a certain class name that contains provided value.

Usage

const myInput = $('input')
expect(myInput).toHaveClassContaining('form')

toHaveProperty

Checks if an element has a certain property.

Usage

const elem = $('#elem')
expect(elem).toHaveProperty('height', 23)
expect(elem).not.toHaveProperty('height', 0)

toHaveValue

Checks if an input element has a certain value.

Usage

const myInput = $('input')
expect(myInput).toHaveValue('user', { ignoreCase: true })

toHaveValueContaining

Checks if an input element contains a certain value.

Usage

const myInput = $('input')
expect(myInput).toHaveValueContaining('us')

toBeClickable

Checks if an element can be clicked by calling isClickable on the element.

Usage

const elem = $('#elem')
expect(elem).toBeClickable()

toBeDisabled

Checks if an element is disabled by calling isEnabled on the element.

Usage

const elem = $('#elem')
expect(elem).toBeDisabled()
// same as
expect(elem).not.toBeEnabled()

toBeEnabled

Checks if an element is enabled by calling isEnabled on the element.

Usage

const elem = $('#elem')
expect(elem).toBeEnabled()
// same as
expect(elem).not.toBeDisabled()

toBeSelected

Checks if an element is enabled by calling isSelected on the element.

Usage

const elem = $('#elem')
expect(elem).toBeSelected()

toBeChecked

Same as toBeSelected.

Usage

const elem = $('#elem')
expect(elem).toBeChecked()

toHaveHref

Checks if link element has a specifc link target.

Usage

const link = $('a')
expect(link).toHaveHref('https://webdriver.io')

toHaveLink

Same as toHaveHref.

Usage

const link = $('a')
expect(link).toHaveLink('https://webdriver.io')

toHaveHrefContaining

Checks if link element contains a specifc link target.

Usage

const link = $('a')
expect(link).toHaveHrefContaining('webdriver.io')

toHaveLinkContaining

Same as toHaveHrefContaining.

Usage

const link = $('a')
expect(link).toHaveLinkContaining('webdriver.io')

toHaveId

Checks if element has a specific id attribute.

Usage

const elem = $('#elem')
expect(elem).toHaveId('elem')

toHaveText

Checks if element has a specific text.

Usage

browser.url('https://webdriver.io/')
const elem = $('.tagline')
expect(elem).toHaveText('Next-gen WebDriver test framework for Node.js')

toHaveTextContaining

Checks if element contains a specific text.

Usage

browser.url('https://webdriver.io/')
const elem = $('.tagline')
expect(elem).toHaveTextContaining('WebDriver test framework')

toBeDisplayedInViewport

Checks if an element is within the viewport by calling isDisplayedInViewport on the element.

Usage

const elem = $('#elem')
expect(elem).toBeDisplayedInViewport()

toBeVisibleInViewport

Same as toBeDisplayedInViewport.

Usage

const elem = $('#elem')
expect(elem).toBeVisibleInViewport()

toHaveChildren

Checks amount of fetched elements using $$ command.

Usage

const elems = $$('div')
expect(elems).toHaveChildren({ gte: 10 })
// same as
assert.ok(elems.length >= 10)

toBeElementsArrayOfSize

Same as toHaveChildren.

Usage

const elems = $$('div')
expect(elems).toBeElementsArrayOfSize({ gte: 10 })
// same as
assert.ok(elems.length >= 10)

Error messages

Error messages are informative out of the box and contain:

full element selector, like $('form').$('input')
actual and expected values
highlight the difference (texts assertions)

What's next?

First of all, feel free to raise an issue with your suggestions or help with PR!

Planned

css matcher
size matcher
cookie / localStorage matchers?
text regex matchers
multiremote support (if requested)