NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #824 most downloaded on npm
Simple and complete DOM testing utilities that encourage good testing practices.
Last release 21 days ago
13 Sep 2026
Ships unpredictably
gaps range from 8 days to 1.1 years
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
230 releases · first in 2019
lists elements that matched multiple error
add matcher name to multiple elements error
One column per quarter.
use the first label for LabelText query suggestions
waitFor: add onTimeout which adds DOM output to timeout errors (#671) (6bc8e2e), closes #559
## 7.17.2 (2020-06-24) ### Bug Fixes * add getConfig to types
waitFor: handle odd timing issue with fake timers
waitFor: add complete support for fake timers (#662) (5b2640a), closes #661
🚨 It's possible this will break your tests if you were working around our limitations before. Fixing the issue should be straightforward. Here's an example from my (Kent's) own workaround:
// using fake timers to skip debounce time
jest.useFakeTimers()
userEvent.clear(notesTextarea)
userEvent.type(notesTextarea, newNotes)
- act(() => jest.runAllTimers())
await screen.findByLabelText(/loading/i)
// wait for the loading spinner to go away
await waitForLoadingToFinish()
jest.useRealTimers()
Notice that all I needed to change was removing manually advancing timers because now we handle things automatically for you 🎉
use realTimers when using fakeTimers (#652) (ea22d73), closes #612
Nothing published for this version
Nothing published for this version
use custom testIdAttribute in getSuggestedQuery
createEvent: allow creating generic events
runWithRealTimers to be compatible with new version of jest (#649) (167b4ac), closes #612
add explicit error message for Promises passed to getWindowFromNode (#646) (2a51345), closes #609
Nothing published for this version
TS: fix typo in type definition for suggestions
canSuggest should not be case sensitive
suggestions: add option to get specific query suggestions
use regex based TextMatch for suggestions
return more data from getSuggestedQuery to support tooling
## 7.10.1 (2020-06-05) ### Bug Fixes * Bump dom-accessibility-api
Add check for container type on queries (#604) (16e41ac), closes testing-library/dom-testing-library#537
getConfig: export the getConfig function
config: add eventWrapper config for wrapping fireEvent
## 7.7.3 (2020-06-01) ### Bug Fixes * update config type
more improvements to suggestions
handle ignores for ByText in suggestions
suggestions for which query to use
Improve performance of ByRole in waitFor*
misleading advice in waitForElement deprecation warning
TS: Forbid async function as callback argument for waitFor
## 7.5.7 (2020-05-18) ### Bug Fixes * Consider and
types: add fourth param to build findAllBy and findBy queries
TS: declare first parameter of screen.debug as optional
revert pretty-format dependency upgrade
Consider explicit role when pretty printing roles (#568) (04b027c), closes #553
TS: add selected to ByRoleOptions
## 7.5.1 (2020-05-07) ### Bug Fixes * TS: incorrect imports in types
waitFor: improve error stack traces for async errors
update deprecation warning for waitForElement
Only return first child element in label query
waitFor: improve error message for non-function callbacks
queryHelpers.getElementError is not a function
fireEvent: Set composed property on relevant synthetic events
docs referenced old npm package
## 7.1.1 (2020-03-23) ### Bug Fixes * Bump types
waitFor*: improve stacktrace for timeout errors (#492) (02a5b82), closes #491
allByLabelText: forEach on NodeList is not supported in edge
remove very old deprecated method
find*: waitForElement was still in use
waitFor: replace wait with waitFor (read more in the Breaking changes list below) (2b641e1), closes #376 #416
wait with waitFor (read more in the Breaking changes list below) (2b641e1), closes #376 #416The new feature in waitForElementToBeRemoved is pretty cool. Here's what you had to do before:
const submitButton = screen.getByText(/submit/i)
fireEvent.click(submitButton)
await waitForElementToBeRemoved(() => screen.getByText(/submit/i))
// submit is now gone
That still works, but you can now do this too:
const submitButton = screen.getByText(/submit/i)
fireEvent.click(submitButton)
await waitForElementToBeRemoved(submitButton)
// submit is now gone
Cool right!?
Node 10 or greater is required. Node 8 is out of LTS (#459) (c3ab843), closes #430
MutationObserver is supported by all major browsers and recent versions of JSDOM. If you need, you can create your own shim (using @sheerun/mutationobserver-shim) and attach it to the window. If you're on an old version of Jest, either update your version of Jest or use jest-environment-jsdom-sixteen (#457) (e3fdb8e9)
If you're using the latest version of react-scripts (Create React App), here are your options:
Option 1:
Wait until the react-scripts updates to the latest version of Jest (subscribe to this PR)
Option 2 (recommended):
Install jest-environment-jsdom-sixteen and then update your test script:
...
"scripts": {
...
- "test": "react-scripts test --env=dom"
+ "test": "react-scripts test --env=jest-environment-jsdom-sixteen"
...
},
...
"devDependencies": {
...
"jest-environment-jsdom-sixteen": "^1.0.3",
...
},
...
Option 3:
Add the MutationObserver constructor to window via @sheerun/mutationobserver-shim:
npm install --save-dev @sheerun/mutationobserver-shim
# yarn add --dev @sheerun/mutationobserver-shim
// src/setupTests.js
import MutationObserver from '@sheerun/mutationobserver-shim'
window.MutationObserver = MutationObserver
wait is now deprecated in favor of waitForwaitFor satisfies the use cases of wait, waitForElement, and waitForDomChange, so those have been deprecated (will be removed in the next major version). Here are some examples of how you can change those:
- await wait()
+ await waitFor(() => {})
This should get you going on the upgrade, but it's recommended to avoid an empty callback and instead insert an assertion in that callback function. This is because otherwise your test is relying on the "next tick of the event loop" before proceeding, and that's not consistent with the philosophy of the library:
The more your tests resemble the way your software is used, the more confidence they can give you.
So it would be better to move the assertion that followed await wait() into the callback you provide to await waitFor(() => { /* assertion here */ })
As for waitForElement, that should normally be accomplished with one of the find* queries:
- const element = await waitForElement(() => screen.getByText(/loading/i))
+ const element = await screen.findByText(/loading/i)
However, if for some reason you cannot use a find query, then waitFor should be a find/replace for waitForElement:
- const element = await waitForElement(() => container.querySelector('.loading'))
+ const element = await waitFor(() => container.querySelector('.loading'))
waitForDomChange encouraged testing implementation details because the user doesn't care about when the DOM changes, they care about when something appears or disappears from the page, so it's better to use waitFor with a specific assertion or waitForElementToBeRemoved (if that's what you're actually trying to do):
- await waitForDomChange()
+ await waitFor(() => {})
// remember, this is not recommended, provide a specific assertion
- await waitForDomChange(mutationObserverOptions)
+ await waitFor(() => {}, mutationObserverOptions)
// if you provided mutationObserverOptions, you can provide those as a second argument
Note that wait called your callback function on an interval and waitFor also does this, but it also calls your callback with the mutation observer as well, which is why it supports the use cases of the deprecated methods so well.
And to be clear, waitForElementToBeRemoved, is not getting deprecated or removed, in fact, it got a really neat new feature which you can read about above.
Most of the time in the kinds of tests that people are writing with DOM Testing Library, if something doesn't happen within 1 second, then it probably won't happen at all and waiting a full 4.5 seconds is a frustrating amount of time. So that's why the default has been changed, however this can be configured when calling the async utility via the timeout option and it can also be globally configured: https://testing-library.com/docs/dom-testing-library/api-configuration
selector option in ByLabelText queries, then you will probably need to update that code to be able to find the label you're looking for: // <label for="example-input" class="example">Example</label><input id="example-input" />
- screen.getByLabelText(/example/i, {selector: '.example'})
+ screen.getByLabelText(/example/i)
+ // or: screen.getByLabelText(/example/i, {selector: '#example-input})
selector option in ByLabelText queries.If you used the selector option in ByLabelText queries, then you will probably need to update that code to be able to find the label you're looking for as a result of #373.
wait: remove default no-op callback
wait() in the past, you now have to supply a callback. Relying on the "next tick" is an implementation detail and should be avoided in favor of explicit expecations within your wait callback.remove mutationobserver shim (#457) (5fae126), closes #413
wait: waitForElement is deprecated in favor of find* queries or wait.
waitForElement is deprecated in favor of find* queries or wait.waitForDomChange is deprecated in favor of waitYour coding agent can read these notes before it upgrades. Set up the MCP server →