You want to use jest to write tests that assert various things about the state of a DOM. As part of that goal, you want to avoid all the repetitive patterns that arise in doing so. Checking for an element's attributes, its text content, its css classes, you name it.
The jest-dom
library provides a set of custom jest matchers that you can use
to extend jest. These will make your tests more declarative, clear to read and
to maintain.
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 jest-dom
Import jest-dom/extend-expect
once (for instance in your tests setup file)
and you're good to go:
import 'jest-dom/extend-expect'
Alternatively, you can selectively import only the matchers you intend to use,
and extend jest's expect
yourself:
import {toBeInTheDOM, toHaveClass} from 'jest-dom'
expect.extend({toBeInTheDOM, toHaveClass})
This allows you to assert whether an element present in the DOM or not.
// add the custom expect matchers once
import 'jest-dom/extend-expect'
// ...
// <span data-testid="count-value">2</span>
expect(queryByTestId(container, 'count-value')).toBeInTheDOM()
expect(queryByTestId(container, 'count-value1')).not.toBeInTheDOM()
// ...
Note: when using
toBeInTheDOM
, make sure you use a query function (likequeryByTestId
) rather than a get function (likegetByTestId
). Otherwise theget*
function could throw an error before your assertion.
This API allows you to check whether the given element has a text content or not.
// add the custom expect matchers once
import 'jest-dom/extend-expect'
// ...
// <span data-testid="count-value">2</span>
expect(getByTestId(container, 'count-value')).toHaveTextContent('2')
expect(getByTestId(container, 'count-value')).not.toHaveTextContent('21')
// ...
This allows you to check wether the given element has an attribute or not. You can also optionally check that the attribute has a specific expected value.
// add the custom expect matchers once
import 'jest-dom/extend-expect'
// ...
// <button data-testid="ok-button" type="submit" disabled>
// OK
// </button>
expect(getByTestId(container, 'ok-button')).toHaveAttribute('disabled')
expect(getByTestId(container, 'ok-button')).toHaveAttribute('type', 'submit')
expect(getByTestId(container, 'ok-button')).not.toHaveAttribute(
'type',
'button',
)
// ...
This allows you to check wether the given element has certain classes within its
class
attribute.
// add the custom expect matchers once
import 'jest-dom/extend-expect'
// ...
// <button data-testid="delete-button" class="btn extra btn-danger">
// Delete item
// </button>
expect(getByTestId(container, 'delete-button')).toHaveClass('extra')
expect(getByTestId(container, 'delete-button')).toHaveClass('btn-danger btn')
expect(getByTestId(container, 'delete-button')).not.toHaveClass('btn-link')
// ...
When you use custom Jest Matchers with Typescript, you will need to extend the
type signature of jest.Matchers<void>
, then cast the result of expect
accordingly. Here's a handy usage example:
// this adds custom expect matchers once
import 'jest-dom/extend-expect'
interface ExtendedMatchers extends jest.Matchers<void> {
toHaveTextContent: (htmlElement: string) => object
toBeInTheDOM: () => void
}
test('renders the tooltip as expected', async () => {
// however you render it:
// render(`<div><span>hello world</span></div>`)
;(expect(
container,
document.querySelector('span'),
) as ExtendedMatchers).toHaveTextContent('hello world')
})
This whole library was extracted out of Kent C. Dodds' dom-testing-library, which was in turn extracted out of react-testing-library.
The intention is to make this available to be used independently of these other libraries, and also to make it more clear that these other libraries are independent from jest, and can be used with other tests runners as well.
I'm not aware of any, if you are please make a pull request and add it here!
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT