Migrating CRA Tests from Jest to Vitest

CRA hides a ton of Jest configuration from you. You don't realize how much until it's gone and your tests start throwing "Cannot resolve module './Button.css'" errors everywhere. The CRA docs barely scratch the surface of what's actually happening behind the scenes.

What CRA Actually Does Behind the Scenes

CRA hides a bunch of Jest magic you never knew existed:

• Automatic jsdom setup with DOM globals
• CSS import stubbing (turns import './styles.css' into empty objects)
• Image/SVG mocking (imports become string paths)
• setupTests.js auto-loading
• Global test functions without imports (describe, test, expect)
• Custom Jest matchers from testing libraries
• Module mocking capabilities for Node modules
• Transform configurations for different file types
• Babel configuration hidden in react-scripts
• Coverage collection with sensible defaults

Switch to Vite and all of that vanishes instantly. Every component that imports CSS breaks. Every test using describe without importing it fails.

The 5 Ways Your Tests Will Break

The first thing that breaks is environment variables. process.env.REACT_APP_API_URL suddenly becomes undefined because Vite uses VITE_* prefixes instead of React's REACT_APP_* convention. Spent a couple hours figuring out why all our API mocks stopped working. You don't think to check this until half your tests are broken.

Then there's the CSS import nightmare:

Error: Cannot resolve module './Button.css'

This shows up everywhere. Jest stubbed CSS imports automatically, but Vitest requires explicit configuration to handle them. Every component that imports styles will throw this error.

Your setupTests.js file? Completely ignored. All those custom matchers, mock setups, polyfills - gone. Vitest needs explicit configuration to know about your setup file. The migration guide mentions this but doesn't emphasize how much shit will break when you miss it.

Jest injected test, describe, expect globally, but Vitest makes this optional and it's disabled by default. So every test file breaks with "describe is not defined" errors. You can enable Vitest globals or import everything manually like a savage.

And image imports that worked fine in Jest:

import logo from './logo.svg'

Suddenly fail in Vitest unless you configure asset mocks. Jest turned these into strings automatically through CRA's file transform.

How This Actually Went

I made the mistake of trying to do everything at once. Figured I'd knock it out in a morning - ended up debugging import errors for the rest of the day. Tests that were passing suddenly broke with messages that told me absolutely nothing useful.

First hour: "This'll be easy, just swap Jest for Vitest."
Second hour: "Why the fuck is every CSS import broken?"
Third hour: "OK, found the CSS mock config..."
Fourth hour: "Now environment variables are undefined everywhere."
Fifth hour: "Jesus Christ, why are half the tests still failing?"

Installing Vitest takes 30 seconds. Getting it to work with your existing setup? That's where you lose the afternoon. Took me two full days because our staging CI was using different environment variable names than local development. Didn't figure that out until I ran the tests in a Docker container and watched them fail the exact same way as CI.

Config That Actually Works

The official migration docs cover the basics but skip over the stuff that actually breaks. This config worked for me after I fixed the ESM import bullshit and path resolution problems.

npm uninstall @testing-library/jest-dom
npm install --save-dev vitest @vitejs/plugin-react jsdom @testing-library/jest-dom

Create vitest.config.ts:

/// <reference types=\"vitest\" />
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    css: true,
    globals: true,
  },
})

The Setup File That Actually Works

Create src/test/setup.ts and paste this:

import '@testing-library/jest-dom'
import { cleanup } from '@testing-library/react'
import { afterEach, vi } from 'vitest'

afterEach(() => {
  cleanup()
})

// Change these to whatever env vars your app actually uses
vi.stubEnv('VITE_API_URL', 'http://localhost:3001/api')
vi.stubEnv('VITE_APP_ENV', 'test')

// Polyfill bullshit for older Node versions
if (!global.fetch) {
  global.fetch = vi.fn()
}

// ResizeObserver mock - everything uses this now apparently
global.ResizeObserver = vi.fn().mockImplementation(() => ({
  observe: vi.fn(),
  unobserve: vi.fn(),
  disconnect: vi.fn(),
}))

// Mock all the asset bullshit - you get the idea
vi.mock('**/*.css', () => ({}))
vi.mock('**/*.scss', () => ({}))
vi.mock('**/*.png', () => ({ default: 'test-file-stub' }))
vi.mock('**/*.svg', () => ({
  default: 'test-file-stub',
  ReactComponent: vi.fn(() => null)
}))
// Add more as needed - jpeg, gif, whatever your app imports

This setup file replaces all the magic CRA did behind the scenes. Getting the environment variables right was way more annoying than expected - had to grep through the codebase multiple times to find all the ones we actually used. Missed a bunch the first time and spent hours figuring out why random tests were failing. Then I realized our staging environment was using different variable names than local development.

Pro tip: Don't trust your .env file. We had some genius who decided to use different variable names in production. REACT_APP_API_URL locally became REACT_APP_API_ENDPOINT in staging and API_URL in production. Took me forever to track down why tests passed locally but failed in CI. The error was just "undefined API URL" - super helpful.

The goal is making Vitest behave enough like Jest that you don't have to touch every test file. Most guides assume you're starting fresh, but when you're migrating an existing codebase, you need this kind of compatibility layer.

Performance Reality Check

Independent benchmarks show mixed results - Vitest can be faster in watch mode but not always faster for full test runs. The real benefit is better TypeScript support and hot reload capabilities.

Don't migrate for speed alone - the configuration overhead might offset any performance gains for smaller projects. The wins are clearer with large TypeScript codebases where Jest's Babel transform becomes a bottleneck.

When CSS Modules Decide to Be Difficult

CSS modules break differently than regular CSS. Your tests import components that expect class names but get empty objects instead. The CSS modules docs don't really prepare you for testing hell.

// This component breaks in tests
import styles from './Button.module.css' // styles is undefined

function Button() {
  return <button className={styles.primary}>Click me</button> // styles.primary is undefined
}

Don't configure CSS modules properly - just mock them:

// In setup file - works every time
vi.mock('**/*.module.css', () => ({
  default: new Proxy({}, {
    get: () => 'mock-class-name'
  })
}))

This gives every CSS class the same mock name. Tests pass, you move on with your life.

Environment Variables: The Hidden Time Sink

Converting REACT_APP_* to VITE_* sounds simple until you realize they're scattered everywhere - components, tests, config files, Dockerfile ENV vars, CI environment settings, probably places you forgot about.

Here's what actually happens:
First you grep for all the REACT_APP variables - that part's easy enough. Then you start updating the component code, changing process.env.REACT_APP_API_URL to import.meta.env.VITE_API_URL. This is where it gets tedious because they're everywhere and you'll definitely miss some.

Then you fix the tests by adding vi.stubEnv() calls. The .env file updates are straightforward - just rename the variables. But then you get to CI and deployment configs and realize you forgot about those entirely. That's where the day goes sideways because now you're digging through Kubernetes configs or Docker compose files or whatever deployment setup you're using.

// Create .env.test for sanity
VITE_API_URL=http://localhost:3001/api
VITE_APP_ENV=test
VITE_ENABLE_MOCK_DATA=true

React 18 Concurrent Mode Will Break Things

Suspense components and concurrent features introduce timing issues in tests. Components might not render immediately, causing random test failures.

// This test fails randomly in React 18
test('shows loading state', () => {
  render(<SuspenseComponent />)
  expect(screen.getByText('Loading...')).toBeInTheDocument() // Sometimes fails
})

Add to setup file:

import { configure } from '@testing-library/react'

configure({
  asyncUtilTimeout: 5000 // Give React more time to settle
})

Memory Issues with Large Test Suites

Vitest starts fast but large test suites will crush your RAM. Our test suite went from using maybe 1.5GB of memory with Jest to eating 4-5GB with Vitest on the same machine. Had to bump our CI runner memory limits because builds were getting killed randomly with "Process killed" messages and no other explanation.

Spent half a day wondering why CI kept failing until I checked the runner stats and saw memory usage spike to 100%. Vitest's memory usage can be way higher than Jest, especially with the default threading setup. Each worker thread keeps its own copy of modules loaded.

Fun discovery: If your tests import a lot of barrel exports (import { a, b, c } from './huge-barrel-file'), Vitest loads WAY more into memory than Jest did. We had one barrel file that imported like 50 components - Vitest loaded all of them for every test that imported even one component from it.

// vitest.config.ts - prevents memory explosions
export default defineConfig({
  test: {
    pool: 'forks', // More memory efficient than threads
    poolOptions: {
      forks: {
        minForks: 1,
        maxForks: 4 // Keep this low or you'll crash your machine
      }
    }
  }
})

VS Code Extension Crashes Frequently

The Vitest VS Code extension is barely functional with large codebases. It crashes when you have too many test files open. The GitHub issues are full of memory leak reports and performance problems that won't get fixed anytime soon.

Real talk: The extension constantly shows "Loading..." for tests that finished running 5 minutes ago. Click "Run Test" and sometimes it works, sometimes it freezes VS Code entirely. I've had to force-quit VS Code more times in the past month than the previous year combined.

Workarounds that might work:

• Disable auto-discovery: \"vitest.disabledWorkspaceFolders\": [\"**/node_modules\"]
• Restart extension weekly: Cmd+Shift+P > \"Restart Extension Host\"
• Use terminal for debugging: npm run test -- --reporter=verbose
• Just give up and run tests in terminal like the good old days

Image/SVG Import Hell

SVG imports are the worst because they can be imported as React components or URLs:

// This works in Jest but breaks in Vitest
import logo from './logo.svg'
import { ReactComponent as LogoIcon } from './logo.svg'

Easiest fix is to mock everything in setup:

vi.mock('**/*.svg', () => ({
  default: 'mock-svg-url',
  ReactComponent: vi.fn(() => React.createElement('svg'))
}))
vi.mock('**/*.png', () => ({ default: 'mock-png-url' }))
vi.mock('**/*.jpg', () => ({ default: 'mock-jpg-url' }))
vi.mock('**/*.gif', () => ({ default: 'mock-gif-url' }))

The Path Alias Problem

Your imports like @/components/Button break because Vitest doesn't automatically inherit your tsconfig paths.

Copy your tsconfig paths to vitest config:

import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '~': path.resolve(__dirname, './src'),
      'components': path.resolve(__dirname, './src/components')
    }
  }
})

Spent way too long debugging this because the error message is useless: "Cannot find module '@/components/Button'". Doesn't tell you it's a path resolution issue.

Vitest is way faster than Jest but getting there sucks. If you're starting from scratch, plan to lose at least a day to config bullshit. If you can steal a working config from somewhere, maybe you'll only lose a few hours.

The speed difference is real though - test reruns are basically instant compared to Jest's sluggish bullshit. Once you get past the migration pain, you'll wonder how you ever put up with Jest's 30-second startup time. But don't underestimate how much time you'll spend getting there. Budget for it or you'll be working late.