feat: Add Vitest integration for type-testing

[AliiiBenn]

Summary

• Add native Vitest integration for type-testing with custom matchers
• Provides a familiar expectType<T>() syntax for Vitest users
• Includes 18 type matchers: toBeType, toNotBeType, toExtend, toNotExtend, toHaveProperty, toBeAny, toBeNever, toBeUnknown, toBeVoid, toBeUndefined, toBeNull, toBeNullable, toBeOptional, toBeUnion, toBeTuple, toBeArray, toBeInhabited, toBeUninhabited
• Adds setup.ts for Vitest integration

Usage Example

import { expectType } from '@deessejs/type-testing/vitest'

expectType<string>().toBeType<string>()
expectType<{ a: string }>().toHaveProperty('a')
expectType<any>().toBeAny()
expectType<never>().toBeNever()

Or with Vitest's expect.extend:

import { expect, test } from 'vitest'
import { toBeType, toHaveProperty } from '@deessejs/type-testing/vitest'

expect.extend({ toBeType, toHaveProperty })

test('type checks', () => {
  expect<string>().toBeType<string>()
  expect<{ a: string }>().toHaveProperty('a')
})

Test Plan

• All 232 tests pass
• Type checking passes
• Linting passes
• 36 new tests added for the vitest module

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
type-testing-web	Ready	Preview, Comment	Mar 3, 2026 1:40pm

[marty-action]

Consider documenting this new Vitest integration in the README so users know how to use it.

[marty-action]

This matcher follows a different naming convention than standard Jest/Vitest matchers which typically use toBe/not.toBe pattern. Consider adding toBeNotType as an alias or documenting this intentional deviation.

[marty-action]

Good use of the type holder pattern. The return type casting with {} as any is necessary but consider adding a comment explaining why this is needed for the type testing pattern.

[marty-action]

Summary

This PR adds a native Vitest integration for the type-testing library, providing 18 custom type matchers and an expectType<T>() helper function. The implementation follows TypeScript's compile-time type checking pattern and integrates well with Vitest's testing framework.

Critical Issues

None identified. The implementation is solid and follows best practices.

Recommendations

1. Documentation: The README is missing documentation for this new Vitest integration feature. Users won't know how to use @deessejs/type-testing/vitest without it. Consider adding a "Vitest Integration" section.

2. Naming Convention: The matcher toNotBeType follows a different pattern than standard Jest/Vitest conventions (typically toBe/not.toBe). This is intentional but should be documented.

3. Type Safety: The use of {} as any in the return type (line 178 of matchers.ts) is necessary for this pattern but could benefit comment.

Positive Notes

• Clean implementation with good TypeScript patterns
• Comprehensive test coverage (36 new tests)
• Proper exports configuration from a clarifying in package.json
• Good JSDoc documentation with examples
• The expectType<T>() helper provides a familiar API for users coming from other testing frameworks
• The matchers leverage the existing type utilities effectively

Testing

The test file (vitest.test.ts) provides thorough type signature testing for all 18 matchers plus the expectType helper. Tests verify both the type signatures and runtime behavior.

---

Verdict: Approve with minor documentation recommendations.

[marty-action]

The setup file exports expectType but doesn't actually extend Vitest's expect with the matchers. The README suggests using this as a setup file (line 414), but it only re-exports expectType without calling expect.extend(). This means users need to manually call expect.extend({ toBeType, ... }) or import the matchers directly.

If the setup file is meant to auto-register matchers, it should include:

import { expect } from 'vitest'
import * as matchers from './matchers.js'

expect.extend(matchers)

Otherwise, consider clarifying in the documentation that this only exports expectType for convenience.

[marty-action]

Summary

The PR adds a comprehensive Vitest integration for the type-testing library, providing 18 custom type matchers and an expectType<T>() helper function. This enables users to write type tests in a familiar BDD-style syntax using Vitest.

Critical Issues

1. Setup file doesn't register matchers automatically

The setup file (packages/type-testing/src/vitest/setup.ts) only exports expectType but doesn't call expect.extend() to register the matchers with Vitest. This makes the setup file less useful than documented. Either:

• Add expect.extend(matchers) to actually register the matchers
• Or clarify in the documentation that this setup file only exports expectType for convenience

Recommendations

2. Consider adding TypeScript declarations for Vitest matchers

The current implementation uses runtime undefined as any returns which work but don't provide IDE autocomplete when used with expect.extend(). Consider adding a Vitest type declaration file for better developer experience.

3. Tests could include negative test cases

The current tests verify type signatures work correctly but don't test that type errors are properly triggered for failing cases. Consider adding tests that verify incorrect type assertions produce compile-time errors.

Positive Notes

• Clean implementation: The matchers are well-structured using conditional types that return CheckPass (which is true) on success and never on failure
• Comprehensive coverage: All 18 matchers have corresponding tests
• Good documentation: README has extensive Vitest integration section with usage examples
• Proper exports: Package.json correctly exposes /vitest and /vitest/setup subpaths
• Reuses existing types: Leverages the library's existing type utilities (Equal, IsAny, IsNever, etc.) rather than duplicating logic

Overall, this is a solid implementation with a minor issue around the setup file's functionality.