expectTypeOf and assertType syntaxes for type testing
Vitest allows writing type tests using `expectTypeOf` or `assertType` syntaxes. Both are imported from the 'vitest' package.
advanced/typecheck
22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Type errors in source code handling
Vitest prints out type errors found in source code during type checking. This behavior can be disabled using the `typecheck.ignoreSourceErrors` config option.
Type test file naming convention
By default, all tests inside `*.test-d.ts` files are considered type tests. This naming convention can be changed using the `typecheck.include` config option.
Type tests are statically analyzed only
Vitest does not run type test files; they are only statically analyzed by the compiler. Dynamic names, test.each, or test.for will not have their test names evaluated and will be displayed as written in the source.
Type test files overlap behavior in Vitest 2.1+
Starting with Vitest 2.1, if `include` and `typecheck.include` patterns overlap, Vitest will report type tests and runtime tests as separate entries. Before Vitest 2.1, the `typecheck.include` pattern would override `include`, preventing runtime tests from executing.
CLI flags work with type checking
CLI flags like `--allowOnly` and `-t` are supported for type checking in addition to runtime testing.
Type test error display with toEqualTypeOf and toExtend
The `.toEqualTypeOf` and `.toExtend` matchers use a special `MismatchInfo` helper type to produce error messages. Error messages show both expected and actual types in a human-readable format. For assertions like `expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()`, the error will indicate which property mismatches and show 'Expected: string, Actual: number' messaging.
toBe methods error messages for type mismatches
Methods like `toBeString`, `toBeNumber`, `toBeVoid` fail by resolving to a non-callable type when the actual type doesn't match. For example, `expectTypeOf(1).toBeString()` produces a TypeScript error 'This expression is not callable' with the meaningful error being 'Type ExpectString<number> has no call signatures', indicating a number was passed but a string was expected.
Type argument vs concrete object comparison
When using `.toEqualTypeOf` or `.toExtend`, assertions with type arguments produce clearer error messages than assertions with concrete objects. For example, `expectTypeOf({a: 1}).toEqualTypeOf<{a: string}>()` provides better errors than `expectTypeOf({a: 1}).toEqualTypeOf({a: ''})`. Using `typeof` on a complex value can help: `expectTypeOf(one).toEqualTypeOf<typeof two>()`.
assertType for simple type checking
The `assertType` API provides a simpler alternative to `expectTypeOf` for type checking. It uses the syntax `assertType<ExpectedType>(value)`. It can be combined with `@ts-expect-error` comments to assert that a type error occurs.
Preventing false positives with @ts-expect-error
When using `@ts-expect-error` syntax in type tests, include type test files in the `test.include` config option to make Vitest actually run the tests. This catches false positives where typos or other errors make the assertion pass incorrectly due to missing references.
Enable typecheck with --typecheck CLI flag
To enable type checking in Vitest, add the `--typecheck` flag to your Vitest command. This is typically configured in package.json scripts, such as `"test": "vitest --typecheck"`.
Vitest typecheck uses tsc or vue-tsc
Vitest calls either `tsc --noEmit` or `vue-tsc --noEmit` (depending on configuration) to perform type checking. This means type checking scripts can be removed from CI/CD pipelines when using Vitest's typecheck feature.
Type test example with expectTypeOf and assertType
Example type test in mount.test-d.ts: ```ts import { assertType, expectTypeOf } from 'vitest' import { mount } from './mount.js' test('my types work properly', () => { expectTypeOf(mount).toBeFunction() expectTypeOf(mount).parameter(0).toExtend<{ name: string }>() // @ts-expect-error name is a string assertType(mount({ name: 42 })) }) ``` This shows using expectTypeOf with matchers like toBeFunction() and parameter() to check function types, and assertType with @ts-expect-error to verify that type errors occur as expected.
typecheck.enabled flag enables typechecking
The `--typecheck.enabled` CLI flag enables typechecking alongside tests. Default is `false`.
typecheck.only flag runs only typecheck tests
The `--typecheck.only` CLI flag runs only typecheck tests and automatically enables typecheck. Default is `false`.
typecheck.checker flag specifies typechecker
The `--typecheck.checker <name>` CLI flag specifies the typechecker to use. Available values: "tsc" and "vue-tsc" and a path to an executable. Default is "tsc".
typecheck.allowJs flag allows JavaScript typechecking
The `--typecheck.allowJs` CLI flag allows JavaScript files to be typechecked. By default takes the value from tsconfig.json.
typecheck.ignoreSourceErrors flag ignores source errors
The `--typecheck.ignoreSourceErrors` CLI flag ignores type errors from source files.
typecheck.build flag uses TypeScript build mode
The `--typecheck.build` CLI flag uses TypeScript build mode for typechecking.
typecheck.tsconfig flag specifies tsconfig path
The `--typecheck.tsconfig <path>` CLI flag specifies a custom tsconfig file path.
typecheck.spawnTimeout flag sets spawn timeout
The `--typecheck.spawnTimeout <time>` CLI flag sets the minimum time in milliseconds to spawn the typechecker.