fix(headless): register jest-dom matcher types for vitest 4

[alexcarpenter]

Problem

All test files in @clerk/headless had jest-dom matchers (toBeInTheDocument, toHaveAttribute, …) showing as TypeScript errors — 340 tsc errors across 11 files:

Property 'toBeInTheDocument' does not exist on type 'Assertion<HTMLElement>'.ts(2339)

Root cause

Vitest 4's Assertion interface is only augmentable from a file that is a proper module. @testing-library/jest-dom/vitest (the latest, v6.9.1) registers its matcher types via a triple-slash /// <reference> to an internal declaration file:

// @testing-library/jest-dom/vitest.d.ts
/// <reference path="types/vitest.d.ts" />

That referenced augmentation does not take effect when pulled in through this package's src/test-utils/jest-dom.d.ts re-export, so the matchers were never attached to the type expect() returns. Runtime was unaffected (matchers are registered via expect.extend in vitest.setup.ts), which is why tests passed and the errors were editor-only.

Why CI never caught it

The package had no typecheck step — build (vite-plugin-dts excludes *.test.tsx), lint (eslint), and test (vitest, runtime only) never ran tsc over test files.

Fix

• Declare the vitest module augmentation explicitly in jest-dom.d.ts (the manual setup jest-dom documents), matching the pattern the sibling vitest-axe.d.ts already uses.
• Chain tsc --noEmit into the package's lint script so test files are type-checked by the existing turbo lint CI job — scoped to @clerk/headless, no global turbo/CI changes.

Verification

• tsc --noEmit: 340 errors → 0
• vitest run: 402 passed, 1 skipped (unchanged)
• turbo lint --filter @clerk/headless: passes (0 errors; 11 pre-existing warnings untouched)

Summary by CodeRabbit

• Tests

  • Enhanced type support for test matchers, providing improved typing for assertion methods used in tests.

• Chores

  • Integrated TypeScript type checking into the lint workflow to validate code types and catch errors earlier during development.
  • Improved the development experience with more robust type definitions for testing utilities.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 10, 2026 11:29pm
swingset	Ready	Preview, Comment	Jun 10, 2026 11:29pm

[changeset-bot]

🦋 Changeset detected

Latest commit: cbad8aa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: d7067491-51e1-4b0c-82ac-bdbbfd3a77b1

📥 Commits

Reviewing files that changed from the base of the PR and between be44bae and cbad8aa.

📒 Files selected for processing (3)

• .changeset/headless-jest-dom-matcher-types.md
• packages/headless/package.json
• packages/headless/src/test-utils/jest-dom.d.ts

---

📝 Walkthrough

Walkthrough

This PR fixes TypeScript type declarations for jest-dom matchers in Vitest by replacing an indirect import with explicit module augmentation. A typecheck script is added to validate types, the lint pipeline is updated to run type checking, and a changeset entry documents the change.

Changes

Jest-DOM matcher types and TypeCheck validation

Layer / File(s)	Summary
Jest-dom matcher type augmentation packages/headless/src/test-utils/jest-dom.d.ts	The jest-dom declaration file replaces @testing-library/jest-dom/vitest imports with explicit vitest module augmentation that extends Assertion and AsymmetricMatchersContaining interfaces with TestingLibraryMatchers, ensuring matcher methods like toBeInTheDocument() are properly typed.
TypeCheck script integration and changeset packages/headless/package.json, .changeset/headless-jest-dom-matcher-types.md	The lint npm script now chains pnpm typecheck after eslint, a new typecheck script runs tsc --noEmit for validation, and a changeset entry documents the type fix.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 A rabbit types with care,
Jest-dom matchers declared fair,
Module augments the way,
Vitest matchers here to stay!
TypeCheck keeps the peace in air. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main fix: registering jest-dom matcher types for vitest 4 in the headless package, which directly addresses the TypeScript errors described in the PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8821

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8821

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8821

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8821

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8821

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8821

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8821

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8821

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8821

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8821

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8821

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8821

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8821

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8821

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8821

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8821

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8821

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8821

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8821

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8821

commit: cbad8aa