---
title: Assertions with expect-webdriverio | TestingBot
description: An assertion is where a test decides pass or fail, so it is also where
  most timing bugs show up. WebdriverIO&#39;s `expect` comes from the…
source_url:
  html: https://testingbot.com/resources/courses/webdriverio/assertions
  md: https://testingbot.com/resources/courses/webdriverio/assertions.md
---

Course

[WebdriverIO Tutorial for Web Testing](https://testingbot.com/resources/courses/webdriverio)

Chapter 5 of 11

1. [1 WebdriverIO Tutorial: Web Testing in TypeScript](https://testingbot.com/resources/courses/webdriverio)
2. [2 Set Up a WebdriverIO Project in TypeScript](https://testingbot.com/resources/courses/webdriverio/project-setup)
3. [3 WebdriverIO Selectors: CSS, Text, Role and $$](https://testingbot.com/resources/courses/webdriverio/selectors)
4. [4 Async/Await, Auto-Waiting and Explicit Waits](https://testingbot.com/resources/courses/webdriverio/waiting)
5. [5 Assertions with expect-webdriverio](https://testingbot.com/resources/courses/webdriverio/assertions)
6. [6 Page Objects in WebdriverIO](https://testingbot.com/resources/courses/webdriverio/page-objects)
7. [7 Run WebdriverIO on TestingBot Across Browsers](https://testingbot.com/resources/courses/webdriverio/run-on-testingbot)
8. [8 Parallel Runs, Suites and Running a Subset](https://testingbot.com/resources/courses/webdriverio/parallel-and-suites)
9. [9 Reporters, Screenshots on Failure and CI](https://testingbot.com/resources/courses/webdriverio/reporters-and-ci)
10. [10 Debugging WebdriverIO Tests](https://testingbot.com/resources/courses/webdriverio/debugging)
11. [11 Knowledge check](https://testingbot.com/resources/courses/webdriverio/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 5 of 11 Intermediate 6 min read 2 quick checks Updated Nov 2026 

# Assertions with expect-webdriverio
[Watch this chapter Starts at 3:09 in the 9:06 course video.](https://www.youtube.com/watch?v=kgScgamfIDc&t=189s)On this page
1. [Browser, element and list matchers](https://testingbot.com#browser-element-and-list-matchers)
2. [The strict-mode error you will meet](https://testingbot.com#the-strict-mode-error-you-will-meet)
3. [Values and attributes](https://testingbot.com#values-and-attributes)
4. [Assertions on plain values](https://testingbot.com#assertions-on-plain-values)
5. [Timeouts and messages](https://testingbot.com#timeouts-and-messages)
6. [Run it](https://testingbot.com#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[#](https://testingbot.com#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:

```typescript
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[#](https://testingbot.com#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?

 `const names = await $$('li').map(e => e.getText()); expect(names).toEqual([...])` `await expect($$('li')).toHaveText(['Bach', 'Conway', 'Doe', 'Smith'])` `await browser.pause(1000)` and then compare the list once

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[#](https://testingbot.com#values-and-attributes)

```typescript
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[#](https://testingbot.com#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`:

```typescript
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?

 The text is read once, sometimes while it still says "Saving..."; use `await expect($('#status')).toHaveText('Saved')` `getText` is unreliable in Firefox; use `getHTML` The test needs `strictSelectors: false`

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[#](https://testingbot.com#timeouts-and-messages)

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

```typescript
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[#](https://testingbot.com#run-it)

```bash
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](https://testingbot.com/resources/courses/visual-regression-testing) explains when screenshots are the right assertion and when they are not.

[Previous · Chapter 4 Async/Await, Auto-Waiting and Explicit Waits](https://testingbot.com/resources/courses/webdriverio/waiting) [Next · Chapter 6 Page Objects in WebdriverIO](https://testingbot.com/resources/courses/webdriverio/page-objects)

On this page

1. [Browser, element and list matchers](https://testingbot.com#browser-element-and-list-matchers)
2. [The strict-mode error you will meet](https://testingbot.com#the-strict-mode-error-you-will-meet)
3. [Values and attributes](https://testingbot.com#values-and-attributes)
4. [Assertions on plain values](https://testingbot.com#assertions-on-plain-values)
5. [Timeouts and messages](https://testingbot.com#timeouts-and-messages)
6. [Run it](https://testingbot.com#run-it)

Certification

Earn the free, resume-worthy TestingBot WebdriverIO Certification for this course.

[How it works](https://testingbot.com/resources/courses/webdriverio/certification)
