Package Exports

jest-dom

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jest-dom) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

jest-dom

Custom jest matchers to test the dom structure

The problem

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.

This solution

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.

Installation
Usage
Custom matchers
Inspiration
Other Solutions
Contributors
LICENSE

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 jest-dom

Usage

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

Custom matchers

`toBeInTheDOM`

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 (like queryByTestId) rather than a get function (like getByTestId). Otherwise the get* function could throw an error before your assertion.

`toHaveTextContent`

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')
// ...

`toHaveAttribute`

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',
)
// ...

`toHaveClass`

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')
// ...

Using with Typescript

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

Inspiration

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.

Contributors

Thanks goes to these people (emoji key):

_{Kent C. Dodds} 💻 📖 🚇 ⚠️	_{Ryan Castner} 📖	_{Daniel Sandiego} 💻	_{Paweł Mikołajczyk} 💻	_{Alejandro Ñáñez Ortiz} 📖	_{Matt Parrish} 🐛 💻 📖 ⚠️	_{Justin Hall} 📦
_{Anto Aravinth} 💻 ⚠️ 📖	_{Jonah Moses} 📖	_{Łukasz Gandecki} 💻 ⚠️ 📖	_{Ivan Babak} 🐛 🤔	_{Jesse Day} 💻	_{Ernesto García} 💻 📖 ⚠️