Exit course
Chapter 5 of 11 Intermediate 6 min read 2 quick checks Updated

Assertions with expect-webdriverio

Watch this chapter Starts at 3:09 in the 9:06 course video.
On this page
  1. Browser, element and list matchers
  2. The strict-mode error you will meet
  3. Values and attributes
  4. Assertions on plain values
  5. Timeouts and messages
  6. Run it

An assertion is where a test decides pass or fail, so it is also where most timing bugs show up. WebdriverIO's expect comes from the expect-webdriverio package: Jest's familiar expect API plus matchers for browsers and elements that retry until they pass or time out. This chapter covers the matchers you will use daily, how they wait, and when you should not use them.

Browser, element and list matchers#

Create test/specs/assertions.e2e.ts. The practice site's /tables page has two tables of people with their last names, first names and amounts due:

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

describe('Assertions', () => {
    it('checks the page, elements and lists', async () => {
        await browser.url('/tables')

        await expect(browser).toHaveTitle('The Internet')
        await expect(browser).toHaveUrl(expect.stringContaining('/tables'))

        const lastNames = $$('#table1 tbody td:first-child')
        await expect(lastNames).toBeElementsArrayOfSize(4)
        await expect(lastNames).toHaveText(['Smith', 'Bach', 'Doe', 'Conway'])

        await expect($('#table2')).toHaveElementClass('tablesorter')
        await expect($('#table2 thead .dues')).toHaveText('Due')
    })
})

Three kinds of subject appear here:

  • browser: toHaveTitle, toHaveUrl, and others about the page as a whole.
  • An element ($(...)): toHaveText, toHaveElementClass, toBeDisplayed, toBeClickable, toBeSelected, toHaveValue, toHaveAttribute and more.
  • A list ($$(...)): toBeElementsArrayOfSize, and toHaveText with an array, which compares the elements one by one in page order.

Each assertion is awaited and each one retries. expect(lastNames).toHaveText([...]) keeps re-reading the cells until they match or waitforTimeout passes. That is what lets you assert right after an action without any wait in between.

Asymmetric matchers from Jest work inside the WebdriverIO matchers: expect.stringContaining('/tables') above, expect.stringMatching(/\d+ items/), or expect.arrayContaining([...]) when only some items matter.

The strict-mode error you will meet#

The first draft of this test used $('#table2 .dues'), and it failed:

StrictSelectorError: strict mode violation: `$("#table2 .dues")` resolved to 5 elements, expected 1.

The table's header cell has the dues class, and so does every cell in the column. The matcher passed the error through rather than checking the first match. #table2 thead .dues names the one element the test means. When a selector resolves to several elements inside an assertion, it is nearly always this: a class that marks a column, a row type or a state, not a single element.

A list is sorted by the server and sometimes takes a second to reorder after you click "Sort by name". Which assertion is reliable?

The WebdriverIO matcher re-reads the list until it matches in order, so it waits out the reorder. Reading the texts first and comparing a plain array checks one moment in time; a pause only guesses how long the server needs.

Values and attributes#

it('reads attributes and values', async () => {
    await browser.url('/inputs')
    const input = $('input[type="number"]')

    await expect(input).toHaveAttribute('type', 'number')
    await input.setValue('42')
    await expect(input).toHaveValue('42')
    await expect(input).not.toHaveValue('')
})

toHaveValue reads the form control's current value, which is what you want after typing. toHaveAttribute reads the HTML attribute, which for inputs is the initial value, not what the user typed. Use the first for "what is in the field", the second for markup such as aria-expanded, href or disabled.

.not negates a matcher and still retries: not.toBeDisplayed() waits for an element to disappear, the same as the reverse wait in chapter 3.

If you are upgrading from WebdriverIO 9, a few matchers were renamed in expect-webdriverio 8: toHaveAttr is now toHaveAttribute and toHaveClass is now toHaveElementClass.

Assertions on plain values#

Sometimes the value you want to check is not on an element: a number you computed, a cookie, a response body. Then you read it once and use a regular Jest matcher, without await on the expect:

it('can check a value that is not on an element', async () => {
    await browser.url('/dropdown')
    await $('#dropdown').selectByVisibleText('Option 2')

    const value = await $('#dropdown').getValue()
    expect(value).toBe('2')
})

This does not retry, because value is a plain string that will never change. That is fine here (the select changed synchronously), but it is the classic way to reintroduce flakiness: expect(await el.getText()).toBe('Saved') reads the text once, while await expect(el).toHaveText('Saved') waits for it. When the subject is an element or the browser, use the WebdriverIO matcher.

A save button shows "Saving..." and then "Saved". expect(await $('#status').getText()).toBe('Saved') fails about one run in five. Why, and what is the fix?

Awaiting getText() first turns the subject into a string, and a plain matcher checks it once. Passing the element to the WebdriverIO matcher makes it re-read the text until it matches.

Timeouts and messages#

Matchers use waitforTimeout by default. Override it per assertion when one check is known to be slow:

await expect($('#report')).toBeDisplayed({ wait: 30000, message: 'report did not render' })

wait: 0 makes a matcher check exactly once. A matcher returns as soon as it passes, so a long wait costs nothing on a passing run; it only decides how long a failing run takes to report. The message is printed above the matcher's own output when it fails:

Error: report did not render
Expect $(`#report`) to be displayed

Expected: "displayed"
Received: "not displayed"

Run it#

npx wdio run wdio.conf.ts --spec test/specs/assertions.e2e.ts
[chrome 157.0.8103.78 mac #0-0] Assertions
[chrome 157.0.8103.78 mac #0-0]    ✓ checks the page, elements and lists
[chrome 157.0.8103.78 mac #0-0]    ✓ reads attributes and values
[chrome 157.0.8103.78 mac #0-0]    ✓ can check a value that is not on an element
[chrome 157.0.8103.78 mac #0-0]
[chrome 157.0.8103.78 mac #0-0] 3 passing (4s)

For visual comparisons (does the page still look the same?) WebdriverIO has a separate visual service with its own matchers; the visual regression testing course explains when screenshots are the right assertion and when they are not.