agentic-dev/docs/library-decisions/2026-05-14-@testing-library/jest-dom.md

package, version, tier, decision, date, deciders, adr, filter-results, verification-commands, accepted-cves

package	version	tier	decision	date	deciders	adr	filter-results	verification-commands	accepted-cves
@testing-library/jest-dom	^6.5.0	core	approved	2026-05-14	Danijel Martinek	null	license types maintenance boundary-fit shadow-check eu-residency cve-scan named-consumer MIT native active pass pass n/a clean pass	npm view @testing-library/jest-dom license npm view @testing-library/jest-dom version pnpm audit --audit-level=moderate

Filter: license

npm view @testing-library/jest-dom license returns MIT. MIT is on the allowlist.

Filter: types

@testing-library/jest-dom ships its own TypeScript declaration files that extend the vitest/jest expect matchers. No separate @types/ package is needed.

Filter: maintenance

Actively maintained by the Testing Library organization. The 6.x line is the current major. Regular releases tracking vitest and jest compatibility.

Filter: boundary-fit

@testing-library/jest-dom is a dependency of @repo/core-testing, which is the workspace's shared testing infrastructure package. Custom DOM matchers (toBeInTheDocument, toHaveTextContent, etc.) are set up in core-testing's setup file and available to all feature test suites via the core-testing dependency. This is the correct placement.

Filter: shadow-check

@testing-library/jest-dom is the sole custom DOM matcher extension in the workspace. No competing matcher library is present.

Filter: eu-residency

@testing-library/jest-dom is a test utility library with no network communication. EU residency does not apply.

Filter: cve-scan

pnpm audit --audit-level=moderate reports no advisories against @testing-library/jest-dom at the time of this trace.

Filter: named-consumer

@repo/core-testing uses @testing-library/jest-dom to set up custom DOM assertion matchers. Feature packages that render React components in tests use these matchers via core-testing. Named, non-hypothetical consumer exists today.

Prompt: replaces

@testing-library/jest-dom extends vitest's expect with semantic DOM matchers, replacing brittle assertion patterns like expect(el.innerHTML).toContain('text') with expect(el).toHaveTextContent('text').

Prompt: migration-cost-out

Low. @testing-library/jest-dom is configured in one setup file in @repo/core-testing. Removing it requires updating that setup and replacing any DOM-specific matchers in test files with lower-level assertions.

Prompt: alternatives-considered

1. Plain vitest expect matchers only — Viable but produces less readable test assertions for DOM state; toBeInTheDocument() is significantly clearer than checking element existence manually.
2. @vitest/ui accessibility assertions — Narrower scope; @testing-library/jest-dom covers the full semantic DOM assertion surface.