feat: add toContainAnyBy* and toContainOneBy* query matchers by benquarmby · Pull Request #731 · testing-library/jest-dom

benquarmby · 2026-07-10T18:09:31Z

What:

This PR adds 16 new query matchers in the form toContainAnyBy* and toContainOneBy* covering all eight core Testing Library query types: AltText, DisplayValue, LabelText, PlaceholderText, Role, TestId, Text, and Title.

Why:

Resolves #548 which has the full context. TL;DR: Help consumers with:

Advice: If you want to assert that something exists, make that assertion explicit.

How:

Because all 16 matchers are nearly identical, a single new query-matchers.js module uses a factory to build the matchers and then export them as an object. The matchers.js module then destructures them as named exports.

Even though the new module is only a hundred lines, this is a large PR due to the tests, type declarations and documentation. I will add more context via inline PR comments to help with the review.

Important

As discussed in #548 (comment), this implementation requires a peer dependency on @testing-library/dom, which is a breaking change. We must also drop Node < 18. The commit message has a BREAKING CHANGE footer to match.

Checklist:

Documentation
Tests
Updated Type Definitions
Ready to be merged

benquarmby

I added some inline comments to provide more context.

benquarmby · 2026-07-10T18:21:19Z

+        if (prettyElements.length) {
+          parts.push('Here are the matching elements:', ...prettyElements)
+        }


This is a similar behavior to dom-testing-library/query-helpers.ts. The intent is to make these matchers as helpful diagnostically as @testing-library/dom itself.

benquarmby · 2026-07-10T18:26:05Z

+  // The function's .name must align with the matcher for the checkHtmlElement
+  // hint to render correctly.
+  Object.defineProperty(queryMatcher, 'name', {
+    value: matcherName,
+  })


Slightly quirky requirement here, so I added a code comment to explain. This is the existing code that our generated matcher function needs to work with:

jest-dom/src/utils.js

Lines 24 to 28 in 55c07ce

context.utils.matcherHint(

`${context.isNot ? '.not' : ''}.${matcherFn.name}`,

'received',

'',

),

benquarmby · 2026-07-10T18:31:56Z

+  "peerDependencies": {
+    "@testing-library/dom": ">=8 <11"
+  },


This is not open ended because we can't predict what @testing-library/dom v11 and higher will ship in terms of breaking changes. Whenever that day comes, increasing this range to support more versions is a straight-forward, non-breaking feature.

benquarmby · 2026-07-10T18:49:12Z

+  type DomQueryArgs<F extends DomQueryFunction = DomQueryFunction> = F extends (
+    container: HTMLElement,
+    ...args: infer A
+  ) => HTMLElement[]
+    ? A
+    : never
+
+  type DomQueryByBoundAttributeArgs = DomQueryArgs<AllByBoundAttribute>
+  type DomQueryByRoleArgs = DomQueryArgs<AllByRole>
+  type DomQueryByTextArgs = DomQueryArgs<AllByText>


The DomQueryArgs<F> utility type infers the argument types directly from @testing-library/dom. This ensures the matcher signatures stay in sync with the upstream queries automatically rather than duplicating them by hand.

benquarmby · 2026-07-10T18:49:50Z

-    /*
+    /**
     * @description


Find a bug, fix a bug. I noticed these weren't being picked up as JSDoc blocks.

benquarmby · 2026-07-10T18:50:41Z

+          "testing-library/no-container": "off",
+          "testing-library/no-render-in-setup": "off",
+          "testing-library/prefer-screen-queries": "off",
+          "testing-library/render-result-naming-convention": "off"


Needing to change these ESLint rules was a surprise, and definitely worth explaining.

This repo inherits its ESLint config from eslint-config-kentcdodds/jest via kcd-scripts. These testing-library rules are included, but they lie dormant until @testing-library/dom is a dependency. Well, guess who just added it?! 😅

There are 500+ violations in this repo alone. Fixing those is well outside the scope of this PR, so I opted to disable them instead. That's the same state as before.

benquarmby · 2026-07-17T16:48:17Z

A friendly ping on this one @gnapse, @kentcdodds. This PR follows through on the approach signed off on in #548. Sixteen new matchers covering the eight core queries (via factory) with full test coverage, type declarations, documentation, and a BREAKING CHANGE notation as discussed.

The concept sat for a while before we got here. It's been baking on internal test suites in the meantime, so confidence is high.

The CI workflows need a maintainer approval to trigger. Can you please unblock those? Then we can see the full results and the PR will be ready for review.

benquarmby · 2026-07-20T18:24:31Z

Thanks for running the build. We need to drop old Node versions much like:

feat: Drop support for Node.js 14.x and Node.js 16.x and add support for Node 20.x dom-testing-library#1255.

I have made that change and included it in the breaking change footer:

BREAKING CHANGE: @testing-library/dom is now a required peer dependency.
The minimum supported Node.js version is now 22.

This also limits the peer range of @testing-library/dom to >=10 <11.

Can you please re-run validation when you get a chance?

kentcdodds · 2026-07-20T18:41:45Z

Personally I'd drop Node 18 and 20 as well. They're no longer supported versions of Node anyway.

BREAKING CHANGE: @testing-library/dom is now a required peer dependency. The minimum supported Node.js version is now 22.

benquarmby · 2026-07-20T18:50:05Z

Personally I'd drop Node 18 and 20 as well. They're no longer supported versions of Node anyway.

Agreed and done. Breaking change footer adjusted. I'll leave it to you to adjust the required checks for this repo. Thanks again.

kentcdodds

Looks good. Thanks!

github-actions · 2026-07-20T19:04:10Z

🎉 This PR is included in version 6.10.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

BREAKING CHANGE: @testing-library/dom is now a required peer dependency. The minimum supported Node.js version is now 22. Repaired release for #731

kentcdodds · 2026-07-20T19:11:02Z

I messed up the release a bit, but I got this published as v7 and deprecated the mistaken release.

…n /webapp [skip ci] Bumps [@testing-library/jest-dom](https://github.com/testing-library/jest-dom) from 6.9.1 to 7.0.0. Release notes *Sourced from [@testing-library/jest-dom's releases](https://github.com/testing-library/jest-dom/releases).* > v7.0.0 > ------ > > [7.0.0](testing-library/jest-dom@v6.10.0...v7.0.0) (2026-07-20) > ========================================================================================== > > ### Features > > * add toContainAnyBy\* and toContainOneBy\* query matchers ([1e39089](testing-library/jest-dom@1e39089)) > > ### BREAKING CHANGES > > * `@testing-library/dom` is now a required peer dependency. The minimum supported > Node.js version is now 22. > > Repaired release for [testing-library/jest-dom#731](https://redirect.github.com/testing-library/jest-dom/pull/731) > > v6.10.0 > ------- > > [6.10.0](testing-library/jest-dom@v6.9.1...v6.10.0) (2026-07-20) > =========================================================================================== > > ### Features > > * add toContainAnyBy\* and toContainOneBy\* query matchers ([#731](https://redirect.github.com/testing-library/jest-dom/issues/731)) ([cae44df](testing-library/jest-dom@cae44df)) Commits * [`1e39089`](testing-library/jest-dom@1e39089) feat: add toContainAnyBy\* and toContainOneBy\* query matchers * [`cae44df`](testing-library/jest-dom@cae44df) feat: add toContainAnyBy\* and toContainOneBy\* query matchers ([#731](https://redirect.github.com/testing-library/jest-dom/issues/731)) * [`55c07ce`](testing-library/jest-dom@55c07ce) ci: switch release to npm trusted publishing ([#726](https://redirect.github.com/testing-library/jest-dom/issues/726)) * [`213256f`](testing-library/jest-dom@213256f) docs: move toHaveSelection from the deprecated section ([#717](https://redirect.github.com/testing-library/jest-dom/issues/717)) * See full diff in [compare view](testing-library/jest-dom@v6.9.1...v7.0.0) Maintainer changes This version was pushed to npm by [GitHub Actions](https://www.npmjs.com/~GitHub%20Actions), a new releaser for `@testing-library/jest-dom` since your current version. [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility\_score?dependency-name=@testing-library/jest-dom&package-manager=npm\_and\_yarn&previous-version=6.9.1&new-version=7.0.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- Dependabot commands and options You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

This MR contains the following updates: | Package | Type | Update | Change | OpenSSF | |---|---|---|---|---| | [@testing-library/jest-dom](https://github.com/testing-library/jest-dom) | devDependencies | major | [`^6.9.1` → `^7.0.0`](https://renovatebot.com/diffs/npm/@testing-library%2fjest-dom/6.9.1/7.0.1) | [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/testing-library/jest-dom/badge)](https://securityscorecards.dev/viewer/?uri=github.com/testing-library/jest-dom) | --- ### Release Notes <details> <summary>testing-library/jest-dom (@testing-library/jest-dom)</summary> ### [`v7.0.1`](https://github.com/testing-library/jest-dom/releases/tag/v7.0.1) [Compare Source](testing-library/jest-dom@v7.0.0...v7.0.1) ##### Bug Fixes - declare vitest as an optional peer dependency ([#733](testing-library/jest-dom#733)) ([3782c78](testing-library/jest-dom@3782c78)) ### [`v7.0.0`](https://github.com/testing-library/jest-dom/releases/tag/v7.0.0) [Compare Source](testing-library/jest-dom@v6.10.0...v7.0.0) ##### Features - add toContainAnyBy\* and toContainOneBy\* query matchers ([1e39089](testing-library/jest-dom@1e39089)) ##### BREAKING CHANGES - [@testing-library/dom](https://github.com/testing-library/dom) is now a required peer dependency. The minimum supported Node.js version is now 22. Repaired release for [#731](testing-library/jest-dom#731) ### [`v6.10.0`](https://github.com/testing-library/jest-dom/releases/tag/v6.10.0) [Compare Source](testing-library/jest-dom@v6.9.1...v6.10.0) ##### Features - add toContainAnyBy\* and toContainOneBy\* query matchers ([#731](testing-library/jest-dom#731)) ([cae44df](testing-library/jest-dom@cae44df)) </details> --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Mend Renovate CLI](https://github.com/renovatebot/renovate).  See merge request swiss-armed-forces/cyber-command/cea/loom!778 Co-authored-by: Loom MR Pipeline Trigger <group_103951964_bot_9504bb8dead6d4e406ad817a607f24be@noreply.gitlab.com>

benquarmby commented Jul 10, 2026

View reviewed changes

benquarmby mentioned this pull request Jul 10, 2026

Support assertions for each DOM query #548

Closed

benquarmby force-pushed the jest-dom-query branch 2 times, most recently from 50a1b1a to df79e2b Compare July 20, 2026 18:13

feat: add toContainAnyBy* and toContainOneBy* query matchers

1c9b805

BREAKING CHANGE: @testing-library/dom is now a required peer dependency. The minimum supported Node.js version is now 22.

benquarmby force-pushed the jest-dom-query branch from df79e2b to 1c9b805 Compare July 20, 2026 18:47

kentcdodds approved these changes Jul 20, 2026

View reviewed changes

kentcdodds merged commit cae44df into testing-library:main Jul 20, 2026
3 checks passed

github-actions Bot added the released label Jul 20, 2026

kentcdodds added a commit that referenced this pull request Jul 20, 2026

feat: add toContainAnyBy* and toContainOneBy* query matchers

1e39089

BREAKING CHANGE: @testing-library/dom is now a required peer dependency. The minimum supported Node.js version is now 22. Repaired release for #731

claude Bot mentioned this pull request Jul 24, 2026

chore(deps): update dependency @testing-library/jest-dom to v7 daisuke-tanabe/pokedex#287

Merged

1 task

macopc mentioned this pull request Jul 25, 2026

chore(deps-dev): bump @testing-library/jest-dom from 6.10.0 to 7.0.0 cogine-ai/OpenUsageCN#143

Closed

chapplehub mentioned this pull request Aug 1, 2026

chore(deps): update dependency @testing-library/jest-dom to v7 chapplehub/estimate-management-system#744

Merged

1 task

macopc mentioned this pull request Aug 15, 2026

chore(deps-dev): bump @testing-library/jest-dom from 6.10.0 to 7.0.1 cogine-ai/OpenUsageCN#201

Open

benquarmby mentioned this pull request Sep 23, 2026

feat: support vitest 5 #742

Open

3 of 4 tasks

	context.utils.matcherHint(
	`${context.isNot ? '.not' : ''}.${matcherFn.name}`,
	'received',
	'',
	),

Conversation

benquarmby commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benquarmby left a comment

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

benquarmby Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benquarmby commented Jul 17, 2026

Uh oh!

benquarmby commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kentcdodds commented Jul 20, 2026

Uh oh!

benquarmby commented Jul 20, 2026

Uh oh!

kentcdodds left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jul 20, 2026

Uh oh!

kentcdodds commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

benquarmby commented Jul 10, 2026 •

edited

Loading

benquarmby Jul 10, 2026 •

edited

Loading

benquarmby commented Jul 20, 2026 •

edited

Loading