## TL;DR

`vitest --typecheck` runs the TypeScript compiler over your test files, while the normal run erases types and never sees them. That is why tests pass and typecheck fails. Fix the reported type errors, or narrow the typecheck include and exclude lists to the files you care about.

## Error

```text
FAIL  src/cart.test.ts :: calculates totals
TypeCheckError: src/cart.test.ts(12,5): error TS2339: Property 'total' does not exist on type 'Cart'.
```

## Steps

1. Run `npx vitest --typecheck --run` and read the TS error codes. Expected: each error names a file, line, and code like TS2339.
2. Check which tsconfig the typecheck uses; it defaults to your tsconfig.json, overridable with `typecheck.tsconfig`. Expected: you know the active config before changing anything.
3. Fix the type errors in the test files: wrong types, missing fields, untyped mocks. Expected: `npx tsc --noEmit` on those files comes back clean.
4. If an error sits in code you do not want typechecked (generated files, JS fixtures), exclude it with `typecheck.exclude`, or set `typecheck.ignoreSourceErrors` to true to keep test files strict while relaxing source files. Expected: typecheck passes without touching those files.
5. Rerun `npx vitest --typecheck --run`. Expected: typecheck passes and the normal run stays green.

## When to use

- CI has a separate typecheck job that fails while the test job passes.
- You just enabled typecheck and got a wall of errors.
- The errors reference test files only.

## When not to use

- The same tsc errors appear in your build; fix the source types, not the vitest config.
- Tests fail at runtime; that is a real bug, not a type issue.
- You want typechecking off entirely; remove --typecheck from the script instead of fighting it.

## Tool compatibility

- Vitest 1.x through 3.x, via `typecheck.enabled` or the `--typecheck` flag.
- TypeScript 5.x.

## Variant phrasings

### TypeCheckError in vitest output

The error class vitest raises for type failures. Each one carries the tsc code you need.

### tsc errors but tests pass, after enabling typecheck in CI

The classic shape of this problem: the CI typecheck job is new, the test job is old and green.

## Why it happens

Vitest typecheck type-checks test files (and by default the source files they touch) without running them. Runtime never sees types, so type errors and test results are fully independent of each other.

## Edge cases

- `typecheck.include` defaults to test file patterns; widening it pulls in more errors than you bargained for.
- Untyped third-party mocks produce TS errors that belong in a .d.ts file or a small typed helper.
- Typecheck is slower than the test run; keep it in its own CI job so it does not slow the feedback loop.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pCCUFTUGjUzC9v3pok49Og