globalSetup TypeScript typing inconsistencies when migrating vitest config across major versions

Direct answers

1. Vitest does not prioritize explicit return‑type annotations over inferred ones; TypeScript’s type checker (tsc/vue‑tsc) performs the validation, and Vitest only checks at runtime that the exported function matches the expected shape.
2. When multiple globalSetup entries exist, Vitest registers them in the order they appear in the merged config array. Teardown functions are then called in the reverse of that registration order, which is deterministic for a given config merge but is not a guaranteed public contract.
3. Moving from Vitest 2.x to 3.x usually preserves existing globalSetup code that follows the documented pattern (export default function setup() { … return () => {}; }). However, internal type helpers and re‑exports have changed, so imports from deep paths (e.g., import type { SetupFn } from 'vitest/dist/types') may break and need updating.

Confirmed facts

• Vitest’s globalSetup option expects a module that exports a function whose return value is assignable to () => void | Promise (or a teardown function).
• Config merging concatenates array fields like globalSetup rather than overriding them.
• The teardown execution order follows the registration order of the setup functions; Vitest does not document this as a stable API.
• Major version bumps may relocate internal type declarations; the public function‑export pattern remains stable.

Likely explanation / assumptions

If you see TypeScript errors after merging configs, they are likely caused by conflicting inferred return types (e.g., one setup returns a value, another returns undefined) that tsc cannot reconcile. The error originates from the type checker, not from Vitest’s runtime.

Assuming you rely on teardown order for cleanup of shared resources, any change in config merge order (e.g., adding a plugin that prepends a setup) could flip the teardown sequence and expose ordering‑dependent flakiness.

Assuming you upgraded Vitest without changing your setup files, most suites will continue to pass; failures usually stem from importing internal Vitest types that were moved or renamed in 3.x.

Steps to verify and fix

1. Run npx tsc --noEmit (or vue-tsc) against your vitest.config.ts and setup files to confirm the exact type mismatch.
2. Check the installed Vitest version with npx vitest --version and inspect the bundled declarations (node_modules/vitest/dist/*.d.ts) for the globalSetup option’s expected type.
3. If you use multiple setup files, add a temporary console.log in each setup/teardown and run the test suite once to observe the actual execution order.
4. When migrating from 2.x to 3.x, keep your setup files unchanged; if type errors appear, update any imports that reference deep Vitest paths to the public API (e.g., import type { Mock } from 'vitest' instead of from 'vitest/dist/types').

Missing diagnostic detail

To determine whether the type error is due to a conflicting inferred return type or a missing import, please share the exact TypeScript error message you see when running tsc.