expect-webdriverio

[!IMPORTANT] This branch is v8 (WebdriverIO v10), not released yet.

expect-webdriverio	WebdriverIO	Node.js	Status	Docs
v8	v10	≥ 22.23.4, 24.22.1 or 26.12.1	In development	This README
v7	v9 (≥ 9.31.5)	≥ 20	Latest release, fixes only	v7 README

API | Multiple Elements | Multi-remote | Frameworks | TypeScript / JS Autocomplete | Examples | Extending Matchers | Migration from v7

WebdriverIO assertion library inspired by expect

Key Features

• Waits for expectations to succeed
• Supports single element $() & multiple elements $$()
• Supports multi-remote browsers & elements, with one expected value per browser instance
• Detailed error messages
• Works in Mocha, Cucumber, Jest, and Jasmine
• Built-in types for TypeScript and JS autocompletion

Installation

1. npm install expect-webdriverio
2. Install your test framework adapter (if not already set up via WDIO testrunner):
   • Mocha (default): npm install @wdio/mocha-framework
   • Jasmine: npm install @wdio/jasmine-framework
   • Cucumber: npm install @wdio/cucumber-framework
   • Jest: No adapter needed — see Jest Framework section

Note: WebdriverIO v10.0.0 or higher is required!

Usage

Using WebdriverIO Testrunner

If you run your tests through the WDIO testrunner, no additional setup is needed. WebdriverIO initializes expect-webdriverio and makes expect available in the global scope so you can use it directly in your tests:

await expect($('#submit')).toBeDisplayed()
await expect($$('buttons')).toBeDisplayed()

See more Examples.

Multi-remote

With multi-remote, assertions check every browser instance, with a single expected value or one per instance:

await expect(multiRemoteBrowser).toHaveTitle('WebdriverIO')
await expect(multiRemoteBrowser.$('h1')).toHaveText(expect.multiRemote({ chrome: 'Welcome', firefox: 'Bienvenue' }))

Local & Browser Runners

• Local Runner: Fully compatible. You can leverage your test framework adapter as mentioned above.
• Browser Runner: Designed for component frameworks like React, Preact, Vue.js, Svelte, and SolidJS, with a few known limitations. For details, see the Browser Runner Framework section.

Using in Standalone Mode

If you use WebdriverIO in standalone mode (without @wdio/globals), make sure you import expect-webdriverio before using it anywhere.

import { remote } from 'webdriverio'
import { expect } from 'expect-webdriverio'

;(async () => {
    const browser = await remote({
        capabilities: {
            browserName: 'chrome'
        }
    })

    await browser.url('https://webdriver.io')

    const $button = await browser.$('.DocSearch-Button')
    await expect($button).toBeDisplayed()
    
    await browser.deleteSession()
})().catch(console.error)

API

Please see the API documentation.

Error Messages

Error messages are informative out of the box and contain:

• Full element selector, like $('form')
• Actual and expected values
• Highlighted differences (text assertions)

What's Next?

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