testing-library-extra

Add bySelector and byAttribute to @testing-library/dom

Why?

The manager of @testing-library/dom believes that using the querySelector API as an escape hatch in test code is a bad practice.

However, for some specific purposes, such as automation in browser extensions, not having CSS selectors would become extremely challenging.

See: PR (267) issues (512)

Install

1npm install testing-library-extra

Usage

Use BySelector

Example DOM

1<button class="open-dialog">open dialog</button>
2<div class="dialog">
3  <form>
4    <input name="username"/>
5    <input name="password"/>
6    <button type="submit"/>
7  </form>
8</div>

Use the css selector to simulate user login.

1import { getBySelector, findBySelector } from 'testing-library-extra'
2import userEvent from '@testing-library/user-event'
3
4const dialogButton = getBySelector(document.body, '.open-dialog')
5
6// Click the button to pop up the user form.
7userEvent.click(dialogButton)
8
9const dialog = await findBySelector(document.body, '.dialog', { timeout: 1000 })
10
11const usernameInput = getBySelector(dialog, 'form input[name="username"]')
12const passwordInput = getBySelector(dialog, 'form input[name="password"]')
13const loginButton = getBySelector(dialog, 'form button[type="submit"]')
14
15userEvent.type(usernameInput, 'admin')
16userEvent.type(passwordInput, 'abc123')
17
18userEvent.click(loginButton)

Use ByAttribute

Example DOM

1<button data-action="openFn...">open dialog<button>
2<div data-id="dialog">
3  <form>
4    <input data-name="username"/>
5    <input data-name="password"/>
6    <button data-action="loginFn" type="submit"/>
7  </form>
8</div>

Use the attribute selector to match any dom.

1import { getByAttribute, findByAttribute } from 'testing-library-extra'
2import userEvent from '@testing-library/user-event'
3
4const dialogButton = getByAttribute(document.body, 'data-action', /^open/)
5
6userEvent.click(dialogButton)
7
8const dialog = await findByAttribute(document.body, 'data-id', 'dialog', { timeout: 1000 })
9
10const usernameInput = getByAttribute(dialog, 'data-name', 'username')
11const passwordInput = getByAttribute(dialog, 'data-name', 'password')
12const loginButton = getByAttribute(dialog, 'data-action', /^login/)
13
14userEvent.type(usernameInput, 'admin')
15userEvent.type(passwordInput, 'abc123')
16
17userEvent.click(loginButton)

Expose API

This project exposes the following api, and the usage is consistent with the original project types-of-queries.

• BySelector

  • getBySelector

  • getAllBySelector

  • queryBySelector

  • queryAllBySelector

  • findBySelector

  • findAllBySelector

• ByAttribute

  • getByAttribute

  • getAllByAttribute

  • queryByAttribute

  • queryAllByAttribute

  • findByAttribute

  • findAllByAttribute

LICENSE

This project is licensed under the MIT License - see the LICENSE file for details.