Skip to main content

Expect

When you're writing tests, you often need to check that values meet certain conditions. expect gives you access to a number of "matchers" that let you validate different things on the browser, an element or mock object.

Default Options​

These default options below are connected to the waitforTimeout and waitforInterval options set in the config.

Only set the options below if you want to wait for specific timeouts for your assertions.

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

If you like to pick different timeouts and intervals, set these options like this:

// wdio.conf.js
import { setOptions } from 'expect-webdriverio'

export const config = {
    // ...
    before () {
        setOptions({ wait: 5000 })
    },
    // ...
}

Matcher Options​

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

Command Options​
NameTypeDetails
waitnumbertime in ms to wait for expectation to succeed. Default: 3000
intervalnumberinterval between attempts. Default: 100
messagestringuser message to prepend before assertion error
String Options​

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

NameTypeDetails
ignoreCasebooleanapply toLowerCase to both actual and expected values
trimbooleanapply trim to actual value
containingbooleanexpect actual value to contain expected value, otherwise strict equal.
asStringbooleanmight be helpful to force converting property value to string
Number Options​

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

NameTypeDetails
eqnumberequals
ltenumberless then equals
gtenumbergreater than or equals

Handling HTML Entities​

An HTML entity is a piece of text (“string”) that begins with an ampersand (&) and ends with a semicolon (;). Entities are frequently used to display reserved characters (which would otherwise be interpreted as HTML code), and invisible characters (like non-breaking spaces, e.g.  ).

To find or interact with such element use unicode equivalent of the entity. e.g.:

<div data="Some&nbsp;Value">Some&nbsp;Text</div>
const myElem = await $('div[data="Some\u00a0Value"]')
await expect(myElem).toHaveAttribute('data', 'div[Some\u00a0Value')
await expect(myElem).toHaveText('Some\u00a0Text')

You can find all unicode references in the HTML spec.

Note: unicode is case-insensitive hence both \u00a0 and \u00A0 works. To find element in browser inspect, remove u from unicode e.g.: div[data="Some\00a0Value"]

Browser Matchers​

toHaveUrl​

Checks if browser is on a specific page.

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

toHaveUrlContaining​

Checks if browser is on a page URL that contains a value.

Usage​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveUrlContaining('webdriver')

toHaveTitle​

Checks if website has a specific title.

Usage​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js')

toHaveTitleContaining​

Checks if website has a specific title that contains a value.

Usage​
await browser.url('https://webdriver.io/')
await expect(browser).toHaveTitleContaining('WebdriverIO')

Element Matchers​

toBeDisplayed​

Calls isDisplayed on given element.

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

toExist​

Calls isExisting on given element.

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

toBePresent​

Same as toExist.

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

toBeExisting​

Same as toExist.

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

toBeFocused​

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

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

toHaveAttribute​

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

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

toHaveAttr​

Same as toHaveAttribute.

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

toHaveAttributeContaining​

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

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

toHaveAttrContaining​

Same as toHaveAttributeContaining.

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

toHaveElementClass​

Checks if an element has a certain class name.

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

toHaveElementClassContaining​

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

Usage​
const myInput = await $('input')
await expect(myInput).toHaveElementClassContaining('form')

toHaveElementProperty​

Checks if an element has a certain property.

Usage​
const elem = await $('#elem')
await expect(elem).toHaveElementProperty('height', 23)
await expect(elem).not.toHaveElementProperty('height', 0)

toHaveValue​

Checks if an input element has a certain value.

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

toHaveValueContaining​

Checks if an input element contains a certain value.

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

toBeClickable​

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

Usage​
const elem = await $('#elem')
await expect(elem).toBeClickable()

toBeDisabled​

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

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

toBeEnabled​

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

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

toBeSelected​

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

Usage​
const elem = await $('#elem')
await expect(elem).toBeSelected()

toBeChecked​

Same as toBeSelected.

Usage​
const elem = await $('#elem')
await expect(elem).toBeChecked()

toHaveHref​

Checks if link element has a specific link target.

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

Same as toHaveHref.

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

toHaveHrefContaining​

Checks if link element contains a specific link target.

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

toHaveLinkContaining​

Same as toHaveHrefContaining.

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

toHaveId​

Checks if element has a specific id attribute.

Usage​
const elem = await $('#elem')
await expect(elem).toHaveId('elem')

toHaveText​

Checks if element has a specific text. Can also be called with an array as parameter in the case where the element can have different texts.

Usage​
await browser.url('https://webdriver.io/')
const elem = await $('.container')
await expect(elem).toHaveText('Next-gen browser and mobile automation test framework for Node.js')
await expect(elem).toHaveText(['Next-gen browser and mobile automation test framework for Node.js', 'Get Started'])

toHaveTextContaining​

Checks if element contains a specific text. Can also be called with an array as parameter in the case where the element can have different texts.

Usage​
await browser.url('https://webdriver.io/')
const elem = await $('.container')
await expect(elem).toHaveTextContaining('browser and mobile automation test framework')
await expect(elem).toHaveTextContaining(['browser and mobile automation test framework', 'Started'])

toBeDisplayedInViewport​

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

Usage​
const elem = await $('#elem')
await expect(elem).toBeDisplayedInViewport()

toHaveChildren​

Checks amount of the fetched element's children by calling element.$('./*') command.

Usage​
const list = await $('ul')
await expect(list).toHaveChildren() // the list has at least one item
// same as
await expect(list).toHaveChildren({ gte: 1 })

await expect(list).toHaveChildren(3) // the list has 3 items
// same as 
await expect(list).toHaveChildren({ eq: 3 })

toBeElementsArrayOfSize​

Checks amount of fetched elements using $$ command.

Usage​
const listItems = await $$('ul>li')
await expect(listItems).toBeElementsArrayOfSize(5) // 5 items in the list

await expect(listItems).toBeElementsArrayOfSize({ lte: 10 })
// same as
assert.ok(listItems.length <= 10)

Network Matchers​

toBeRequested​

Checks that mock was called

Usage​
const mock = browser.mock('**/api/todo*')
await expect(mock).toBeRequested()

toBeRequestedTimes​

Checks that mock was called for the expected amount of times

Usage​
const mock = browser.mock('**/api/todo*')
await expect(mock).toBeRequestedTimes(2) // await expect(mock).toBeRequestedTimes({ eq: 2 })

await expect(mock).toBeRequestedTimes({ gte: 5, lte: 10 }) // request called at least 5 times but less than 11

toBeRequestedWith​

Checks that mock was called according to the expected options.

Most of the options supports expect/jasmine partial matchers like expect.objectContaining

Usage​
const mock = browser.mock('**/api/todo*', { method: 'POST' })

await expect(mock).toBeRequestedWith({
    url: 'http://localhost:8080/api/todo',          // [optional] string | function | custom matcher
    method: 'POST',                                 // [optional] string | array
    statusCode: 200,                                // [optional] number | array
    requestHeaders: { Authorization: 'foo' },       // [optional] object | function | custom matcher
    responseHeaders: { Authorization: 'bar' },      // [optional] object | function | custom matcher
    postData: { title: 'foo', description: 'bar' }, // [optional] object | function | custom matcher
    response: { success: true },                    // [optional] object | function | custom matcher
})

await expect(mock).toBeRequestedWith({
    url: expect.stringMatching(/.*\/api\/.*/i),
    method: ['POST', 'PUT'], // either POST or PUT
    statusCode: [401, 403],  // either 401 or 403
    requestHeaders: headers => headers.Authorization.startsWith('Bearer '),
    postData: expect.objectContaining({ released: true, title: expect.stringContaining('foobar') }),
    response: r => Array.isArray(r) && r.data.items.length === 20
})

Using regular expressions​

You can also directly use regular expressions for all matchers that do text comparison.

Usage​
await browser.url('https://webdriver.io/')
const elem = await $('.container')
await expect(elem).toHaveText(/node\.js/i)
await expect(elem).toHaveText([/node\.js/i, 'Get Started'])
await expect(elem).toHaveTextContaining([/node\.js/i, 'Started'])
await expect(browser).toHaveTitle(/webdriverio/i)
await expect(browser).toHaveUrl(/webdriver\.io/)
await expect(elem).toHaveElementClass(/Container/i)

Default Matchers​

In addition to the expect-webdriverio matchers you can use builtin Jest's expect assertions or expect/expectAsync for Jasmine.

TypeScript​

If you are using the WDIO Testrunner everything will be automatically setup. Just follow the setup guide from the docs. However if you run WebdriverIO with a different testrunner or in a simple Node.js script you will need to add expect-webdriverio to types in the tsconfig.json.

  • "expect-webdriverio" for everyone except of Jasmine/Jest users.
  • "expect-webdriverio/jasmine" Jasmine
  • "expect-webdriverio/jest" Jest

JavaScript (VSCode)​

It's required to create jsconfig.json in project root and refer to the type definitions to make autocompletion work in vanilla js.

{
  "include": [
    "**/*.js",
    "**/*.json",
    "node_modules/expect-webdriverio"
  ]
}

Adding your own matchers​

Similar to how expect-webdriverio extends Jasmine/Jest matchers it's possible to add custom matchers.

Custom matchers should be added in wdio before hook

// wdio.conf.js
{
    async before () {
        const { addCustomMatchers } = await import('./myMatchers')
        addCustomMatchers()
    }
}
// myMatchers.js - Jest example
export function addCustomMatchers () {
    if (global.expect.expect !== undefined) { // Temporary workaround. See https://github.com/webdriverio/expect-webdriverio/issues/835
        global.expect = global.expect.expect;
    }

    expect.extend({
        myMatcher (actual, expected) {
            return { pass: actual === expected, message: () => 'some message' }
        }
    })
}

Welcome! How can I help?

WebdriverIO AI Copilot