Vitest Pattern | Bootspring Docs

Configure and use Vitest for fast, modern testing in Next.js applications with TypeScript, React Testing Library, and coverage reporting.

Overview#

Vitest is a blazing-fast test runner built on Vite, providing excellent TypeScript and ESM support out of the box. It's the recommended testing framework for modern Next.js applications.

When to use:

Unit testing utility functions and classes
Component testing with React Testing Library
Testing Server Actions and API routes
Testing custom hooks

Key features:

Native ESM and TypeScript support
Jest-compatible API
Fast HMR-powered watch mode
Built-in code coverage
Snapshot testing

Code Example#

Setup Configuration#

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./vitest.setup.ts'],
    include: ['**/*.test.{ts,tsx}'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['node_modules/', '*.config.*']
    }
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

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

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

// Mock next/navigation
vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: vi.fn(),
    replace: vi.fn(),
    back: vi.fn()
  }),
  usePathname: () => '/',
  useSearchParams: () => new URLSearchParams()
}))

Unit Testing Functions#

// lib/utils.test.ts
import { describe, it, expect } from 'vitest'
import { formatPrice, calculateDiscount, validateEmail } from './utils'

describe('formatPrice', () => {
  it('formats cents to dollars', () => {
    expect(formatPrice(1000)).toBe('$10.00')
    expect(formatPrice(1599)).toBe('$15.99')
  })

  it('handles zero', () => {
    expect(formatPrice(0)).toBe('$0.00')
  })
})

describe('calculateDiscount', () => {
  it('applies percentage discount', () => {
    expect(calculateDiscount(100, 10)).toBe(90)
    expect(calculateDiscount(50, 50)).toBe(25)
  })

  it('returns original price for zero discount', () => {
    expect(calculateDiscount(100, 0)).toBe(100)
  })
})

describe('validateEmail', () => {
  it('accepts valid emails', () => {
    expect(validateEmail('user@example.com')).toBe(true)
    expect(validateEmail('user+tag@domain.co.uk')).toBe(true)
  })

  it('rejects invalid emails', () => {
    expect(validateEmail('invalid')).toBe(false)
    expect(validateEmail('no@domain')).toBe(false)
    expect(validateEmail('')).toBe(false)
  })
})

Testing React Components#

// components/button.test.tsx
import { describe, it, expect, vi } from 'vitest'
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './button'

describe('Button', () => {
  it('renders with children', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('calls onClick when clicked', () => {
    const handleClick = vi.fn()
    render(<Button onClick={handleClick}>Click</Button>)

    fireEvent.click(screen.getByText('Click'))
    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('is disabled when loading', () => {
    render(<Button loading>Submit</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
  })

  it('applies variant classes', () => {
    render(<Button variant="destructive">Delete</Button>)
    expect(screen.getByRole('button')).toHaveClass('bg-red-500')
  })
})

Testing Async Components#

// components/user-profile.test.tsx
import { describe, it, expect, vi } from 'vitest'
import { render, screen, waitFor } from '@testing-library/react'
import { UserProfile } from './user-profile'

// Mock the fetch function
vi.mock('@/lib/api', () => ({
  fetchUser: vi.fn()
}))

import { fetchUser } from '@/lib/api'

describe('UserProfile', () => {
  it('shows loading state initially', () => {
    vi.mocked(fetchUser).mockImplementation(() => new Promise(() => {}))

    render(<UserProfile userId="123" />)
    expect(screen.getByText('Loading...')).toBeInTheDocument()
  })

  it('displays user data after loading', async () => {
    vi.mocked(fetchUser).mockResolvedValue({
      name: 'John Doe',
      email: 'john@example.com'
    })

    render(<UserProfile userId="123" />)

    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument()
      expect(screen.getByText('john@example.com')).toBeInTheDocument()
    })
  })

  it('shows error state on failure', async () => {
    vi.mocked(fetchUser).mockRejectedValue(new Error('Failed'))

    render(<UserProfile userId="123" />)

    await waitFor(() => {
      expect(screen.getByText('Error loading profile')).toBeInTheDocument()
    })
  })
})

Testing Server Actions#

// actions/posts.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { createPost, deletePost } from './posts'
import { prisma } from '@/lib/db'
import { auth } from '@/lib/auth'

vi.mock('@/lib/db', () => ({
  prisma: {
    post: {
      create: vi.fn(),
      delete: vi.fn(),
      findUnique: vi.fn()
    }
  }
}))

vi.mock('@/lib/auth', () => ({
  auth: vi.fn()
}))

vi.mock('next/cache', () => ({
  revalidatePath: vi.fn()
}))

describe('createPost', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('creates post for authenticated user', async () => {
    vi.mocked(auth).mockResolvedValue({ userId: 'user-123' })
    vi.mocked(prisma.post.create).mockResolvedValue({
      id: 'post-1',
      title: 'Test Post',
      authorId: 'user-123'
    })

    const formData = new FormData()
    formData.set('title', 'Test Post')

    const result = await createPost(formData)

    expect(result.success).toBe(true)
    expect(prisma.post.create).toHaveBeenCalledWith({
      data: expect.objectContaining({
        title: 'Test Post',
        authorId: 'user-123'
      })
    })
  })

  it('returns error for unauthenticated user', async () => {
    vi.mocked(auth).mockResolvedValue({ userId: null })

    const formData = new FormData()
    formData.set('title', 'Test')

    const result = await createPost(formData)

    expect(result.success).toBe(false)
    expect(result.error).toBe('Not authenticated')
  })
})

Testing Hooks#

// hooks/use-debounce.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { renderHook, act } from '@testing-library/react'
import { useDebounce } from './use-debounce'

describe('useDebounce', () => {
  beforeEach(() => {
    vi.useFakeTimers()
  })

  afterEach(() => {
    vi.useRealTimers()
  })

  it('returns initial value immediately', () => {
    const { result } = renderHook(() => useDebounce('hello', 500))
    expect(result.current).toBe('hello')
  })

  it('debounces value changes', () => {
    const { result, rerender } = renderHook(
      ({ value }) => useDebounce(value, 500),
      { initialProps: { value: 'hello' } }
    )

    rerender({ value: 'world' })
    expect(result.current).toBe('hello') // Still old value

    act(() => {
      vi.advanceTimersByTime(500)
    })

    expect(result.current).toBe('world') // Now updated
  })
})

Usage Instructions#

Install dependencies: npm install -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom
Create config: Add vitest.config.ts with your settings
Add setup file: Create vitest.setup.ts for global mocks and cleanup
Add scripts: Add "test": "vitest" to package.json
Write tests: Create *.test.ts or *.test.tsx files

Running Tests#

# Run all tests
npm test

# Watch mode
npm test -- --watch

# Coverage report
npm test -- --coverage

# Run specific file
npm test -- button.test.tsx

# Run tests matching pattern
npm test -- --grep "createPost"

Best Practices#

Use globals - Enable globals: true for cleaner test files
Mock external dependencies - Mock Next.js modules in setup
Clean up after tests - Use cleanup() in afterEach
Group related tests - Use describe blocks for organization
Test behavior, not implementation - Focus on what components do
Use async utilities - Use waitFor for async operations
Keep tests fast - Mock slow dependencies like databases

Unit Testing - Unit testing best practices
Component Testing - React component testing
Mocking - Mocking strategies
Coverage - Code coverage setup