Even a mechanical migration deserves a spec

Swapping Jest for Vitest is a mechanical migration. I still wrote a spec before touching a single test.

The reason was simple: the design system already ran on Vite (Storybook included), and Jest with ts-jest kept a second transform pipeline alive just for tests. Consolidate, and get faster.

The spec had three parts.

Inventory

I knew exactly what would break:

• 68 test files.
• jest.fn in about 120 places across 30 files.
• jest.mock in 15.
• Fake timers in exactly one file.
• toBeInTheDocument used 219 times.

Non-goals

• No migrating legacy packages that have no tests.
• No root-level Vitest config until a second package gets tests.
• No swapping jsdom for happy-dom.
• And no behavior changes in the tests, only jest.* becoming vi.*.

Definition of done

All 68 files passing with the same assertions, pnpm test and CI working unchanged, and five dependencies removed: jest, ts-jest, jest-environment-jsdom, @types/jest and ts-node.

Result: one day of spec, one day of migration, five small, reviewable commits.

The part that protects you most is the non-goals list. A mechanical migration turns into a rewrite the moment someone thinks "while I'm here...".

What was the last "simple" migration that grew on your team?