Webdriverio-testing-library NPM

The problem

You want to use dom-testing-library methods in your webdriverio tests.

This solution

Based heavily on nightwatch-testing-library

This allows you to use all the useful dom-testing-library methods in your tests.

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev webdriverio-testing-library

Usage

setupBrowser

Accepts a WebdriverIO BrowserObject and returns dom-testing-library queries modifed to return WebdriverIO Elements. All the queries are async, including queryBy and getBy variants, and are bound to document.body by default.

const {setupBrowser} = require('webdriverio-testing-library');

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')
})

Queries are also added to the BrowserObject and Elements as commands. The browser commands are scoped to the document.body as above and the Element commands are scoped to the element.

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')
})

within

Returns queries scoped to a WebdriverIO element

const {within} = require('webdriverio-testing-library')

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 pass a config to dom-testing-library

const {configure} = require('webdriverio-testing-library')

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

All the above methods are fully typed. To use the Browser and Element commands added by setupBrowser the global WebdriverIO namespace will need to be modified. Add the following to a typescript module:

import {WebdriverIOQueries} from 'webdriverio-testing-library';

declare global {
  namespace WebdriverIO {
    interface Browser extends WebdriverIOQueries {}
    interface Element extends WebdriverIOQueries {}
  }
}

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

import {WebdriverIOQueriesSync} from 'webdriverio-testing-library';

declare global {
  namespace WebdriverIO {
    interface Browser extends WebdriverIOQueriesSync {}
    interface Element extends WebdriverIOQueriesSync {}
  }
}