From cbad8aa4cdc57d82112482d70400fd2b4b5c11e6 Mon Sep 17 00:00:00 2001
From: Alex Carpenter <alex.carpenter@clerk.dev>
Date: Wed, 10 Jun 2026 19:27:46 -0400
Subject: [PATCH] fix(headless): register jest-dom matcher types for vitest 4

@testing-library/jest-dom/vitest registers its matcher types via a
triple-slash reference that does not take effect when re-exported through
this package's test setup, leaving toBeInTheDocument/toHaveAttribute and
friends untyped across all test files (340 tsc errors, invisible in CI).

Declare the vitest module augmentation explicitly, and run tsc as part of
the package's lint task so the test files are type-checked in CI.
---
 .changeset/headless-jest-dom-matcher-types.md  |  2 ++
 packages/headless/package.json                 |  5 +++--
 packages/headless/src/test-utils/jest-dom.d.ts | 17 ++++++++++++++++-
 3 files changed, 21 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/headless-jest-dom-matcher-types.md

diff --git a/.changeset/headless-jest-dom-matcher-types.md b/.changeset/headless-jest-dom-matcher-types.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/headless-jest-dom-matcher-types.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/headless/package.json b/packages/headless/package.json
index 7d1136cfcac..8a46326ac62 100644
--- a/packages/headless/package.json
+++ b/packages/headless/package.json
@@ -53,8 +53,9 @@
   "scripts": {
     "build": "rm -rf dist && vite build",
     "dev": "vite build --watch",
-    "lint": "eslint src",
-    "test": "vitest run"
+    "lint": "eslint src && pnpm typecheck",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@floating-ui/react": "catalog:repo"
diff --git a/packages/headless/src/test-utils/jest-dom.d.ts b/packages/headless/src/test-utils/jest-dom.d.ts
index 69f12cf866b..7c5aed2b331 100644
--- a/packages/headless/src/test-utils/jest-dom.d.ts
+++ b/packages/headless/src/test-utils/jest-dom.d.ts
@@ -1,2 +1,17 @@
-import '@testing-library/jest-dom/vitest';
+import 'vitest';
 import './vitest-axe';
+
+import type { TestingLibraryMatchers } from '@testing-library/jest-dom/matchers';
+
+// `@testing-library/jest-dom/vitest` registers its matcher types via a
+// triple-slash `/// <reference>` to an internal declaration file, which does not
+// reliably apply when re-exported through this package's test setup. Declare the
+// `vitest` module augmentation explicitly so `expect(...).toBeInTheDocument()` and
+// friends are typed. `import 'vitest'` keeps this file a module augmentation
+// rather than an ambient module declaration that would shadow vitest's own types.
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Assertion<T = any> extends TestingLibraryMatchers<any, T> {}
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface AsymmetricMatchersContaining extends TestingLibraryMatchers<any, any> {}
+}