*.test-d.ts files, assert inferred types with expectTypeOf(...).toEqualTypeOf<T>() so a leaked any fails, and keep every // @ts-expect-error on a one-line call that differs from a valid call in exactly one way. Run them with vitest run --typecheck, because a plain vitest run never looks at those files. Anything about what the code does with real data stays in ordinary tests.A typed API client ships with a small, pleasant promise: client.get(\"/users/:id\", { id }) resolves to a User, and a misspelt path is a compile error. Six months later someone adds an escape hatch for ad-hoc URLs. Every test stays green. The misspelt path now compiles, returns unknown, and the first person to notice is a consumer whose editor stopped complaining.
Nothing in the runtime suite could have caught that, because at runtime the old and new clients behave identically. The thing that regressed was the type signature, and the type signature is the product for anyone importing the package. That is the case a type-level test exists for, and it is narrower than what most type test suites cover.
\n\nexpectTypeOf is re-exported from expect-type (dependency range ^1.4.0, current release 1.4.0), and TypeScript 7.0.2. Every example and every error below was produced with Vitest 5.0.2 using its default tsc checker against TypeScript 7.0.2 on Node.js 26.0.0. The Vitest documentation does not mention TypeScript 7 either way; that run is the only evidence here that the two work together.Before writing any assertion, list what someone calling the code could notice if it changed. For a typed client that list is short:
\n\nEverything else, such as the name of the conditional type that pulls :id out of a template or whether a helper returns an intersection or a flattened object, is an implementation detail. Pin it and the test fails on refactors no caller would notice, until the team learns to delete type tests unread.
Here is the client. The endpoint map is an interface from path literal to response type, and the parameters come from the path itself using template literal types:
\n\n// src/client.ts\nexport type User = { id: string; name: string; role: \"admin\" | \"member\" };\nexport type Order = { id: string; userId: string; totalCents: number };\n\nexport interface Endpoints {\n \"/users\": User[];\n \"/users/:id\": User;\n \"/users/:id/orders/:orderId\": Order;\n}\n\nexport type Path = keyof Endpoints;\n\ntype ParamNames<P extends string> =\n P extends `${string}:${infer Name}/${infer Rest}`\n ? Name | ParamNames<`/${Rest}`>\n : P extends `${string}:${infer Name}`\n ? Name\n : never;\n\nexport type Params<P extends string> = { [K in ParamNames<P>]: string };\n\ntype Args<P extends Path> = [ParamNames<P>] extends [never]\n ? []\n : [params: Params<P>];\n\nexport function createClient(baseUrl: string, fetchImpl: typeof fetch = fetch) {\n return {\n async get<P extends Path>(path: P, ...args: Args<P>): Promise<Endpoints[P]> {\n const params: Record<string, string> = args[0] ?? {};\n const url = path.replace(/:(\\w+)/g, (_, name: string) => encodeURIComponent(params[name]));\n const res = await fetchImpl(baseUrl + url);\n if (!res.ok) throw new HttpError(res.status, `GET ${url} failed with ${res.status}`);\n return res.json();\n },\n };\n}\n\nexport class HttpError extends Error {\n constructor(readonly status: number, message: string) {\n super(message);\n }\n}\n\nexport type ApiResult<P extends Path> =\n | { ok: true; data: Endpoints[P] }\n | { ok: false; status: number };\n\nexport async function tryGet<P extends Path>(\n client: ReturnType<typeof createClient>,\n path: P,\n ...args: Args<P>\n): Promise<ApiResult<P>> {\n try {\n return { ok: true, data: await client.get(path, ...args) };\n } catch (e) {\n return { ok: false, status: e instanceof HttpError ? e.status : 0 };\n }\n}Two design choices matter for testing. Args<P> collapses to an empty tuple when a path has no parameters, so client.get(\"/users\") takes one argument and client.get(\"/users/:id\") demands two. And Params is exported deliberately, because callers use it to build links, which makes its shape public. ParamNames and Args are not exported and will not be asserted on directly.
Note also what the declared return type hides. res.json() gives back any, and Promise<Endpoints[P]> accepts it without a word. The client's types describe what the server is supposed to send. Whether it does is a runtime question, and the earlier article on validating at TypeScript's runtime boundary covers it.
The Vitest guide states the file convention plainly: \"By default all tests inside *.test-d.ts files are considered type tests\". They are never executed. In the guide's words, Vitest \"doesn't run these files, they are only statically analyzed by the compiler\", which also means a test.each title is shown as written, not expanded.
// src/client.test-d.ts\nimport { describe, expectTypeOf, test } from \"vitest\";\nimport { createClient, type Order, type Params, type User } from \"./client.js\";\n\nconst client = createClient(\"https://api.example.test\");\n\ndescribe(\"get()\", () => {\n test(\"each path resolves to the response type the map declares\", () => {\n expectTypeOf(client.get(\"/users\")).resolves.toEqualTypeOf<User[]>();\n expectTypeOf(client.get(\"/users/:id\", { id: \"u_1\" })).resolves.toEqualTypeOf<User>();\n expectTypeOf(\n client.get(\"/users/:id/orders/:orderId\", { id: \"u_1\", orderId: \"o_9\" }),\n ).resolves.toEqualTypeOf<Order>();\n });\n\n test(\"params are inferred from the path template\", () => {\n expectTypeOf<Params<\"/users/:id/orders/:orderId\">>().toEqualTypeOf<{ id: string; orderId: string }>();\n expectTypeOf<Params<\"/users\">>().toEqualTypeOf<{}>();\n });\n\n test(\"calls the contract forbids\", () => {\n // @ts-expect-error \"/user\" is not a declared path\n client.get(\"/user\");\n // @ts-expect-error \"/users/:id\" needs an id\n client.get(\"/users/:id\");\n // @ts-expect-error \"userId\" is not a parameter of \"/users/:id\"\n client.get(\"/users/:id\", { userId: \"u_1\" });\n // @ts-expect-error \"/users\" takes no params\n client.get(\"/users\", { id: \"u_1\" });\n });\n});.resolves unwraps the promise before comparing, so there is no await and nothing is fetched. The expected types are written as literals, User[] and { id: string; orderId: string }, not computed from the code under test; that difference comes back later.
The refusal cases rely on @ts-expect-error, added in TypeScript 3.9. The release notes give the rule that makes it usable as an assertion: when a line is preceded by the comment, TypeScript suppresses the error, \"but if there's no error, TypeScript will report that // @ts-expect-error wasn't necessary\", as Unused '@ts-expect-error' directive. So a refusal test fails the moment the call starts compiling. The same notes recommend it over @ts-ignore when \"you're writing test code where you actually want the type system to error on an operation\".
Narrowing gets its own file because it tests a different export. The contract of ApiResult is that checking ok tells you which fields exist:
// src/result.test-d.ts\nimport { expectTypeOf, test } from \"vitest\";\nimport type { ApiResult, User } from \"./client.js\";\n\ntest(\"checking ok narrows the result\", () => {\n const result = {} as ApiResult<\"/users/:id\">;\n if (result.ok) {\n expectTypeOf(result.data).toEqualTypeOf<User>();\n } else {\n expectTypeOf(result).toEqualTypeOf<{ ok: false; status: number }>();\n expectTypeOf(result).not.toHaveProperty(\"data\");\n }\n});The cast is harmless: the file never runs. Flatten the union to { ok: boolean; data?: Endpoints[P]; status?: number }, a common \"simplification\", and all three assertions fail: data becomes User | undefined inside the if, and the else branch still has a data property.
Type checking is off by default: typecheck.enabled defaults to false. Run a project containing only these files through a plain vitest run and it stops with No test files found, exiting with code 1, because the default runtime include pattern is **/*.{test,spec}.?(c|m)[jt]s?(x) and a .test-d.ts name does not match it. In a project that also has runtime tests, the type tests are skipped with no message at all.
{\n \"scripts\": {\n \"test\": \"vitest run --typecheck\",\n \"test:types\": \"vitest run --typecheck.only\"\n },\n \"devDependencies\": {\n \"typescript\": \"7.0.2\",\n \"vitest\": \"5.0.2\"\n }\n}--typecheck runs the type tests alongside the runtime ones. --typecheck.only runs just the type tests, which is quicker when iterating on a signature. The type test glob, typecheck.include, defaults to ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)'].
Two defaults change what a green run means. First, typecheck.ignoreSourceErrors is false, so a type error anywhere in the source fails the suite, not only errors in test files. Because the run uses tsc --noEmit under the hood, the Testing Types guide says you can remove a separate type-check script from the pipeline. Keep yours if the build uses a different tsconfig from the one Vitest picks: typecheck.tsconfig defaults to the closest tsconfig.json. Second, typecheck.checker defaults to tsc and accepts vue-tsc or \"a path to custom binary or command name that produces the same output as tsc --noEmit --pretty false\". Vitest parses that text output, which is why the docs describe the checker by its output format rather than its implementation.
@ts-expect-error takes no error code. Any error on the next line satisfies it. That is the whole trap, and it shows up in three forms.
The first is the regression from the opening. Someone adds an overload for ad-hoc URLs:
\n\nget: get as {\n <P extends Path>(path: P, ...args: Args<P>): Promise<Endpoints[P]>;\n (path: string): Promise<unknown>;\n},Compare two refusal tests written against it. The loose one packs two mistakes into one call:
\n\n// Passes after the regression: the second argument still errors\n// @ts-expect-error \"/user\" is not a declared path\nclient.get(\"/user\", { id: \"u_1\" });\n\n// Fails after the regression, as it should\n// @ts-expect-error \"/user\" is not a declared path\nclient.get(\"/user\");The new overload accepts any string but only one argument, so the loose call still errors, on the argument count. The directive is satisfied and the test stays green while the promise it names has been broken. The minimal call, one character away from a valid client.get(\"/users\"), is what catches it:
src/client.test-d.ts(21,5): error TS2578: Unused '@ts-expect-error' directive.\nsrc/client.test-d.ts(23,5): error TS2578: Unused '@ts-expect-error' directive.The second line is a bonus: client.get(\"/users/:id\") with no parameters also compiles through the new overload, and that test fails too. One loosened signature, two broken promises, and only minimal calls see both. The rule to write down: every rejected call should differ from an accepted call in exactly one way, and the comment should name that one way.
The second form is a typo. The Vitest guide shows it with assertType<string>(answr): the misspelt name is itself a compile error, the directive is satisfied, and the test passes while checking nothing. The guide's fix is to also add the type test files to the runtime test.include, so the misspelling fails with a ReferenceError when executed. Before doing that, check what those files would do if run: the refusal tests above would call the real fetch against the base URL. Pass a stub fetchImpl to createClient first.
The third is layout. The directive covers the following line only. Format a refused call across several lines and the error can land on a line the directive does not reach:
\n\n// @ts-expect-error \"userId\" is not a parameter of \"/users/:id\"\nclient.get(\"/users/:id\", {\n userId: \"u_1\",\n});src/ml.test-d.ts(5,3): error TS2578: Unused '@ts-expect-error' directive.\nsrc/ml.test-d.ts(7,5): error TS2353: Object literal may only specify known properties, and 'userId' does not exist in type 'Params<\"/users/:id\">'.This failure is at least loud. Keep refused calls on one line anyway. If a formatter would wrap one, shorten the call rather than letting it split.
\n\nDelete the explicit return type from get, the kind of cleanup that looks tidy in review. The function now returns whatever res.json() returns, which is Promise<any>. Here is how four assertions respond:
// All three still pass: any is assignable to User[]\nassertType<Promise<User[]>>(client.get(\"/users\"));\nexpectTypeOf(client.get(\"/users\")).resolves.toExtend<User[]>();\nconst users: User[] = await client.get(\"/users\");\n\n// Fails: any is not identical to User[]\nexpectTypeOf(client.get(\"/users\")).resolves.toEqualTypeOf<User[]>();assertType is declared in Vitest as <T>(value: T): void with an empty body, so it is an assignability check and nothing more. toExtend is also an assignability check. any passes both. Only the equality matcher rejects it, with a terser error than its usual \"Expected: …, Actual: …\" message:
src/client.test-d.ts(8,63): error TS2344: Type 'User[]' does not satisfy the constraint 'never'.When you see constraint 'never' from toEqualTypeOf, suspect any on the actual side first. The expect-type README documents the related behaviours: .toEqualTypeOf \"distinguishes between deeply-nested any and unknown properties\", the toBe… matchers \"protect against any\", and .not.toBeAny() guards a return you have just given a real type.
That makes the choice of matcher a decision rather than taste. For inferred results callers depend on, use toEqualTypeOf. Use toExtend only for real \"is-a\" questions, such as \"is this handler assignable to the framework's type\". For an object checked against a subset of its keys, Vitest's docs recommend toMatchObjectType, which is \"stricter than toExtend\" and more likely to catch issues \"like readonly properties\", with one caveat: it \"only works with plain object types\" and fails on unions. If your suite still uses toMatchTypeOf, it has been deprecated \"since expect-type v1.2.0\"; the README says .toExtend is \"identical\" to it and that there are \"no foreseeable plans to remove\" it, so migrating is a search and replace with no behaviour change.
The expected side of an assertion has to come from somewhere other than the code under test. This one does not:
\n\n// Passes whatever ParamNames computes\ntype P = \"/users/:id/orders/:orderId\";\nexpectTypeOf<Params<P>>().toEqualTypeOf<{ [K in ParamNames<P>]: string }>();Break ParamNames so it stops recursing after the first parameter, and this test still passes, because both sides now agree on the wrong answer. The literal version from earlier fails, and so does the response-type test for the orders path, because orderId is no longer an accepted key. The mirrored test also had to export ParamNames just to be written, which turns a private helper into something a later refactor must keep.
If writing the expected type needs the same conditional-type machinery as the implementation, you are restating code, not testing it. Write out the literal answer for two or three representative inputs instead.
\n\nType tests cannot tell you that a/b is encoded as a%2Fb, or that a 404 becomes { ok: false, status: 404 }. Those claims go in an ordinary test file that runs in the same vitest run --typecheck:
// src/client.test.ts\nimport { expect, test, vi } from \"vitest\";\nimport { createClient, tryGet } from \"./client.js\";\n\ntest(\"fills and encodes path params\", async () => {\n const fetchImpl = vi.fn(async () => Response.json({ id: \"a/b\", name: \"Ada\", role: \"admin\" }));\n const client = createClient(\"https://api.example.test\", fetchImpl);\n\n await client.get(\"/users/:id\", { id: \"a/b\" });\n\n expect(fetchImpl).toHaveBeenCalledWith(\"https://api.example.test/users/a%2Fb\");\n});\n\ntest(\"a 404 becomes a failed result carrying the status\", async () => {\n const fetchImpl = vi.fn(async () => new Response(null, { status: 404 }));\n const client = createClient(\"https://api.example.test\", fetchImpl);\n\n await expect(tryGet(client, \"/users/:id\", { id: \"missing\" })).resolves.toEqual({ ok: false, status: 404 });\n});Neither file can do the other's job. The narrowing test proves tryGet is typed as a discriminated union; only the runtime test proves it actually returns the failure branch on a 404. And neither proves the server sends a User. If the response shapes come from captured payloads, the JSON Schema Generator gives you a starting schema for the runtime check that the type map cannot perform.
Type tests are cheap to run and expensive to maintain, because they fail on changes that are harmless to callers. Skip them when:
\n\ntsc already fails when a change breaks one of them.User returns User checks the compiler, not you.They earn their place on library boundaries and on shared internal packages whose generics other teams call: a client like this one, a typed event emitter, a form builder that infers field names, a schema helper. The test is whether a type-only change could break a caller that you cannot see from your own repository.
\n\nAn assistant can list a package's exported generics and draft accepted and refused calls for each, which saves typing. It cannot decide which inferred behaviour is a promise. Whether Params<\"/users\"> should be {} or never is an API decision for the maintainers, and a generated test that pins whichever one the code happens to produce makes that decision by accident.
Because it does not handle generic functions well, and this client is one. The expect-type README says toBeCallableWith \"will likely fail if you try to use it with a generic function or an overload\". With the client above, expectTypeOf(client.get).toBeCallableWith(\"/users/:id\", { id: \"x\" }) fails: the generic is resolved against the whole Path union, so the checker demands an orderId too. Calling the function directly under @ts-expect-error tests what a user would actually write.
No. Vitest's API page warns that \"during runtime this function doesn't do anything\", and expectTypeOf in Vitest 5.0.2 is a direct re-export of expect-type, whose README says neither it nor the chained functions \"have any meaningful runtime behaviour\". An expectTypeOf line in a regular .test.ts file is only checked if tsc or --typecheck covers that file.
Pick the exported generic in your codebase with the most callers outside its own package. Write down what those callers can observe, then create one .test-d.ts file with an equality assertion for each inferred result, a one-line @ts-expect-error for each refused call, and a narrowing test if it returns a union. Add --typecheck to the test script and pin Vitest to an exact version.
Then capture the output of three deliberate breakages, reverting each one afterwards: delete the function's explicit return type and confirm an equality assertion fails; add a (path: string) overload and confirm a refusal test reports TS2578; run plain vitest run and confirm the type tests do not appear in its output. If the first two stay green, the tests are checking assignability or catching the wrong error, and the third tells you whether your CI command was ever running them.
*.test-d.ts files are type tests by default, that Vitest \"calls tsc or vue-tsc\" and \"doesn't run these files\", that test.each names are not evaluated, that overlapping include and typecheck.include have been reported separately since Vitest 2.1, the answr typo example and the test.include remedy, the error-reading guidance, and that the typecheck run uses tsc --noEmit \"so you can remove\" a separate script.toEqualTypeOf, toExtend, .resolves, toHaveProperty and toBeCallableWith; toMatchObjectType being \"stricter than toExtend\" and limited to plain object types; and toMatchTypeOf deprecated \"since expect-type v1.2.0\".typecheck.enabled (false), typecheck.only, typecheck.checker (tsc, or a binary matching tsc --noEmit --pretty false output), typecheck.include and typecheck.ignoreSourceErrors (false).expectTypeOf is re-exported from expect-type, and that Vitest 5.0.2 depends on expect-type ^1.4.0.assertType is declared as <T>(value: T): void with an empty body, so it checks assignability only..toEqualTypeOf distinguishes nested any from unknown and the toBe… matchers \"protect against any\"; why .toMatchTypeOf is deprecated and that .toExtend is identical; and the listed limitations for intersections and for toBeCallableWith on generic or overloaded functions.Unused '@ts-expect-error' directive, plus the guidance to prefer it in test code.