Code Story: How We Improved Test Coverage by 40% with Vitest 2.0 and React Testing Library 16

// vitest.setup.ts
// Configures global test environment for React + Vitest 2.0
// Ensures consistent mocks, cleanup, and error handling across all test suites
import { afterEach, beforeAll, afterAll, vi } from 'vitest';
import { cleanup } from '@testing-library/react';
import '@testing-library/jest-dom/vitest'; // Extends Vitest matchers with RTL jest-dom assertions
import React from 'react';

// Mock global fetch to prevent actual network calls in tests
const mockFetch = vi.fn();
vi.stubGlobal('fetch', mockFetch);

// Mock environment variables to match staging config (no production secrets in tests)
vi.stubGlobal('import.meta.env', {
  VITE_API_BASE_URL: 'https://api-staging.example.com',
  VITE_FEATURE_FLAGS: JSON.stringify({ newDashboard: true, analytics: false }),
  MODE: 'test',
  DEV: false,
  PROD: false,
});

// Capture unhandled promise rejections in tests to fail fast
const unhandledRejections = new Map, Error>();
process.on('unhandledRejection', (reason: Error, promise: Promise) => {
  unhandledRejections.set(promise, reason);
  console.error('Unhandled Rejection in Test Setup:', reason);
});

process.on('rejectionHandled', (promise: Promise) => {
  unhandledRejections.delete(promise);
});

beforeAll(() => {
  // Global setup: clear all mocks before any tests run
  vi.clearAllMocks();
});

afterEach(() => {
  // Clean up React Testing Library render trees after each test to prevent memory leaks
  cleanup();
  // Reset all mocks to their default state after each test
  vi.resetAllMocks();
  // Reset fetch mock calls
  mockFetch.mockReset();
});

afterAll(() => {
  // Fail the test suite if any unhandled rejections were recorded
  if (unhandledRejections.size > 0) {
    const errors = Array.from(unhandledRejections.values())
      .map((err, idx) => `Unhandled Rejection ${idx + 1}: ${err.message}`)
      .join('\n');
    throw new Error(`Test suite had unhandled promise rejections:\n${errors}`);
  }
});

// Mock React's act() to log warnings if used incorrectly (RTL 16 best practice)
const originalAct = React.act;
vi.spyOn(React, 'act').mockImplementation((callback) => {
  try {
    return originalAct(callback);
  } catch (err) {
    console.warn('Incorrect act() usage detected:', err);
    throw err; // Re-throw to fail the test
  }
});

// Dashboard.test.tsx
// Tests the UserDashboard component with Vitest 2.0 + React Testing Library 16
// Covers happy path, loading state, error state, and user interactions
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { render, screen, waitFor, within } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import UserDashboard from './UserDashboard';
import { mockFetch } from '../vitest.setup'; // Reuse fetch mock from setup

// Mock user data matching our API schema
const mockUser = {
  id: 'usr_12345',
  name: 'Alice Chen',
  email: 'alice@example.com',
  role: 'admin',
  lastLogin: '2024-05-15T09:30:00Z',
  stats: { activeProjects: 8, pendingTasks: 12, completedTasks: 47 },
};

// Mock API error response
const mockErrorResponse = {
  status: 500,
  message: 'Internal Server Error',
  code: 'API_ERR_500',
};

describe('UserDashboard', () => {
  let user: ReturnType;

  beforeEach(() => {
    user = userEvent.setup();
    // Reset fetch mock before each test
    mockFetch.mockReset();
  });

  it('renders loading state while fetching user data', () => {
    // Mock pending fetch to trigger loading state
    mockFetch.mockReturnValue(new Promise(() => {})); // Never resolves
    render();

    // RTL 16's findByRole is optimized for faster async queries
    expect(screen.getByRole('status', { name: /loading user data/i })).toBeInTheDocument();
    expect(screen.queryByRole('heading', { name: /welcome back/i })).not.toBeInTheDocument();
  });

  it('renders user data correctly after successful fetch', async () => {
    // Mock successful API response
    mockFetch.mockResolvedValueOnce({
      ok: true,
      json: async () => mockUser,
    });

    render();

    // Wait for async data to load using RTL 16's waitFor with extended timeout
    await waitFor(() => {
      expect(screen.getByRole('heading', { name: /welcome back, alice chen/i })).toBeInTheDocument();
    }, { timeout: 2000 });

    // Verify user stats are rendered correctly
    const statsSection = screen.getByRole('region', { name: /user statistics/i });
    expect(within(statsSection).getByText(/8 active projects/i)).toBeInTheDocument();
    expect(within(statsSection).getByText(/12 pending tasks/i)).toBeInTheDocument();
    expect(within(statsSection).getByText(/47 completed tasks/i)).toBeInTheDocument();

    // Verify API was called with correct endpoint (Vitest 2.0 mock assertion)
    expect(mockFetch).toHaveBeenCalledOnce();
    expect(mockFetch).toHaveBeenCalledWith(
      'https://api-staging.example.com/users/usr_12345',
      expect.objectContaining({ method: 'GET', headers: { 'Content-Type': 'application/json' } })
    );
  });

  it('renders error state when API fetch fails', async () => {
    // Mock failed API response
    mockFetch.mockResolvedValueOnce({
      ok: false,
      status: mockErrorResponse.status,
      json: async () => mockErrorResponse,
    });

    render();

    // Wait for error message to appear
    await waitFor(() => {
      expect(screen.getByRole('alert', { name: /failed to load user data/i })).toBeInTheDocument();
    });

    expect(screen.getByText(/internal server error/i)).toBeInTheDocument();
    expect(screen.queryByRole('heading', { name: /welcome back/i })).not.toBeInTheDocument();
  });

  it('handles refresh button click to refetch data', async () => {
    // First fetch succeeds
    mockFetch.mockResolvedValueOnce({
      ok: true,
      json: async () => mockUser,
    });

    render();

    // Wait for initial load
    await waitFor(() => {
      expect(screen.getByRole('heading', { name: /welcome back, alice chen/i })).toBeInTheDocument();
    });

    // Click refresh button
    const refreshButton = screen.getByRole('button', { name: /refresh data/i });
    await user.click(refreshButton);

    // Verify fetch was called again
    expect(mockFetch).toHaveBeenCalledTimes(2);
    expect(mockFetch).toHaveBeenNthCalledWith(
      2,
      'https://api-staging.example.com/users/usr_12345',
      expect.objectContaining({ method: 'GET' })
    );
  });

  it('handles invalid user ID with validation error', async () => {
    render();

    // Wait for validation error
    await waitFor(() => {
      expect(screen.getByRole('alert', { name: /invalid user id/i })).toBeInTheDocument();
    });

    // Verify no API call was made for invalid ID
    expect(mockFetch).not.toHaveBeenCalled();
  });
});

// migrate-to-vitest.mjs
// Node.js migration script to convert Jest 29 test suites to Vitest 2.0 + RTL 16
// Handles import replacements, config updates, and validation
import fs from 'fs/promises';
import path from 'path';
import { glob } from 'glob';
import { execSync } from 'child_process';

// Configuration: directories to scan for test files
const TEST_DIRS = ['src/components', 'src/hooks', 'src/utils'];
const JEST_IMPORT_PATTERN = /import\s+(?:(?:{[^}]+})\s+from\s+)?['"]jest['"]/g;
const VITEST_IMPORT = "import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';";
const RTL_JEST_IMPORT = /import\s+(?:(?:{[^}]+})\s+from\s+)?['"]@testing-library\/react['"]/g;
const RTL_VITEST_IMPORT = "import { render, screen, waitFor, within } from '@testing-library/react';";
const JEST_DOM_IMPORT = /import\s+['"]@testing-library\/jest-dom['"]/g;
const RTL_JEST_DOM_IMPORT = "import '@testing-library/jest-dom/vitest';";

// Logging utility with timestamps
const log = (message, level = 'info') => {
  const timestamp = new Date().toISOString();
  const prefix = level === 'error' ? '❌' : level === 'warn' ? '⚠️' : '✅';
  console.log(`${prefix} [${timestamp}] ${message}`);
};

// Error handling wrapper for async operations
const handleError = (err, context) => {
  log(`Failed ${context}: ${err.message}`, 'error');
  if (err.stack) log(`Stack trace: ${err.stack}`, 'error');
  process.exit(1);
};

// Find all Jest test files (files ending with .test.jsx, .test.tsx, .spec.jsx, .spec.tsx)
const findTestFiles = async () => {
  try {
    const patterns = TEST_DIRS.map((dir) => path.join(dir, '**/*.test.{jsx,tsx,spec.{jsx,tsx}}'));
    const files = await glob(patterns, { ignore: ['**/node_modules/**'] });
    log(`Found ${files.length} test files to migrate`);
    return files;
  } catch (err) {
    handleError(err, 'finding test files');
  }
};

// Migrate individual test file
const migrateFile = async (filePath) => {
  try {
    let content = await fs.readFile(filePath, 'utf-8');
    const originalContent = content;

    // Replace Jest imports with Vitest imports
    content = content.replace(JEST_IMPORT_PATTERN, VITEST_IMPORT);
    // Replace RTL Jest imports with RTL Vitest imports
    content = content.replace(RTL_JEST_IMPORT, RTL_VITEST_IMPORT);
    // Replace Jest DOM imports with RTL Vitest DOM imports
    content = content.replace(JEST_DOM_IMPORT, RTL_JEST_DOM_IMPORT);
    // Replace Jest-specific globals (jest.fn() -> vi.fn(), jest.mock() -> vi.mock())
    content = content.replace(/jest\.fn\(/g, 'vi.fn(');
    content = content.replace(/jest\.mock\(/g, 'vi.mock(');
    content = content.replace(/jest\.spyOn\(/g, 'vi.spyOn(');
    content = content.replace(/jest\.clearAllMocks\(/g, 'vi.clearAllMocks(');
    // Replace Jest's done() callback with Vitest's async/await (common pattern)
    content = content.replace(/done\(\)/g, '// Remove done() callback, use async/await instead');

    // Only write file if content changed
    if (content !== originalContent) {
      await fs.writeFile(filePath, content, 'utf-8');
      log(`Migrated ${filePath}`);
      return 1; // Return 1 for migrated file
    }
    return 0; // Return 0 for unchanged file
  } catch (err) {
    handleError(err, `migrating ${filePath}`);
  }
};

// Main migration function
const main = async () => {
  log('Starting Jest to Vitest 2.0 migration...');
  const startTime = Date.now();

  // Check if Vitest is installed
  try {
    execSync('npx vitest --version', { stdio: 'ignore' });
  } catch {
    log('Vitest 2.0 is not installed. Install it with: npm install -D vitest@2 @testing-library/react@16 @testing-library/jest-dom@6', 'error');
    process.exit(1);
  }

  const testFiles = await findTestFiles();
  let migratedCount = 0;

  for (const file of testFiles) {
    migratedCount += await migrateFile(file);
  }

  const duration = ((Date.now() - startTime) / 1000).toFixed(2);
  log(`Migration complete! Migrated ${migratedCount} of ${testFiles.length} files in ${duration}s`);

  // Post-migration validation: run Vitest to check for errors
  log('Running Vitest to validate migrated tests...');
  try {
    execSync('npx vitest run --reporter=verbose', { stdio: 'inherit' });
    log('All migrated tests pass!');
  } catch {
    log('Some migrated tests failed. Check the output above for errors.', 'warn');
  }
};

// Run main function with top-level error handling
main().catch((err) => handleError(err, 'running main migration function'));

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

export default defineConfig({
  plugins: [react(), commonjs()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './vitest.setup.ts',
    // Native ESM support: no transpilation for ESM modules
    esm: {
      // Enable ESM for test files
      include: ['**/*.test.{ts,tsx}'],
    },
  },
});

// Good: RTL 16 optimized findByRole
const submitButton = await screen.findByRole('button', { name: /submit/i });
// Bad: Slow, flaky polling with getByTestId
const submitButton = await waitFor(() => screen.getByTestId('submit-button'));

// vitest.config.ts coverage settings
export default defineConfig({
  test: {
    coverage: {
      provider: 'v8', // Faster than istanbul for Vitest
      thresholds: {
        lines: 85,
        branches: 85,
        functions: 85,
        statements: 85,
      },
      exclude: ['src/generated/**', '**/*.d.ts'],
      reporter: ['text', 'html', 'json'],
    },
  },
});