WebdriverIO Testing Library

webdriverio-testing-library allows the use of dom-testing-library queries in WebdriverIO for end-to-end web testing.

Install

Be sure to follow the WebdriverIO install & config instructions first

then just

npm install -D @testing-library/webdriverio

• webdriverio-testing-library on GitHub

API

setupBrowser

Accepts a WebdriverIO browser object and returns dom-testing-library queries modifed to return WebdriverIO elements like normal selectors. All queries are async and are bound to document.body by default.

import { setupBrowser } from '@testing-library/webdriverio'

it('can click button', async () => {

const { getByText } = setupBrowser(browser)

const button = await getByText('Button Text')

await button.click()

expect(await button.getText()).toEqual('Button Clicked')

})

setupBrowser also adds queries as commands to the browser and to all WebdriverIO elements. The browser commands are scoped to document.body. The element commands are scoped to the element in the same way as if it was passed to within.

it('adds queries as browser commands', async () => {

setupBrowser(browser)

expect(await browser.getByText('Page Heading')).toBeDefined()

})

it('adds queries as element commands scoped to element', async () => {

setupBrowser(browser)

const nested = await browser.$('*[data-testid="nested"]')

const button = await nested.getByText('Button Text')

await button.click()

expect(await button.getText()).toEqual('Button Clicked')

})

When using sync mode these commands are also synchronous:

it('adds queries as browser commands', async () => {

setupBrowser(browser)

expect(browser.getByText('Page Heading')).toBeDefined()

})

it('adds queries as element commands scoped to element', async () => {

setupBrowser(browser)

const nested = browser.$('*[data-testid="nested"]')

const button = nested.getByText('Button Text')

button.click()

expect(button.getText()).toEqual('Button Clicked')

})

within

Accepts a WebdriverIO element and returns queries scoped to that element

import { within } from '@testing-library/webdriverio'

it('within scopes queries to element', async () => {

const nested = await browser.$('*[data-testid="nested"]')

const button = await within(nested).getByText('Button Text')

await button.click()

expect(await button.getText()).toEqual('Button Clicked')

})

configure

Lets you configure dom-testing-library

import { configure } from '@testing-library/webdriverio'

beforeEach(() => {

configure({ testIdAttribute: 'data-automation-id' })

})

afterEach(() => {

configure(null)

})

it('lets you configure queries', async () => {

const { getByTestId } = setupBrowser(browser)

expect(await getByTestId('testid-in-data-automation-id-attr')).toBeDefined()

})

Typescript

This library comes with full typescript definitions. To use the commands added by setupBrowser the Browser and Element interfaces in the global WebdriverIO namespace need to be extended. Add the following to a typescript module:

import { WebdriverIOQueries } from '@testing-library/webdriverio'

declare global {

namespace WebdriverIO {

interface Browser extends WebdriverIOQueries {}

interface Element extends WebdriverIOQueries {}

}

}

If you are using the @wdio/sync package you will need to use the WebdriverIOQueriesSync type to extend the interfaces:

import { WebdriverIOQueriesSync } from '@testing-library/webdriverio'

declare global {

namespace WebdriverIO {

interface Browser extends WebdriverIOQueriesSync {}

interface Element extends WebdriverIOQueriesSync {}

}

}

Additional information about using typescript with WebdriverIO can be found here