Testing with Vitest and Playwright: Ship with Confidence

$# Unit tests
$npm test

$# Unit tests in watch mode
$npm run test:watch

$# Unit tests with coverage
$npm run test:coverage

$# End-to-end tests
$npm run test:e2e

$# E2E with UI mode (interactive)
$npm run test:e2e:ui

$# E2E specific browser
$npm run test:e2e -- --project=chromium

$# Accessibility tests
$npm run test:a11y

$# All tests
$npm run test:all

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';
import { resolve } from 'path';

export default defineConfig({
  // Vite plugins for test environment
  plugins: [
    // Enable React JSX transformation
    react(),
    // Resolve TypeScript path aliases (@/...)
    tsconfigPaths(),
  ],

  test: {
    // Test environment - jsdom simulates browser APIs
    // Options: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime'
    environment: 'jsdom',

    // Enable global test APIs (describe, it, expect)
    // Without this, you'd need to import from 'vitest' in every file
    globals: true,

    // Files to run before each test file
    // Use for global mocks, polyfills, and test utilities
    setupFiles: ['./tests/setup.ts'],

    // File patterns to include as tests
    include: [
      'src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
      'tests/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
    ],

    // File patterns to exclude from tests
    exclude: [
      '**/node_modules/**',
      '**/dist/**',
      '**/e2e/**', // E2E tests use Playwright
      '**/.{idea,git,cache,output,temp}/**',
    ],

    // Coverage configuration
    coverage: {
      // v8 is faster than istanbul for native coverage
      provider: 'v8',

      // Output formats
      reporter: ['text', 'text-summary', 'html', 'lcov', 'json'],

      // Files to include in coverage
      include: ['src/**/*.{ts,tsx}'],

      // Files to exclude from coverage
      exclude: [
        'src/**/*.d.ts',
        'src/**/*.test.{ts,tsx}',
        'src/**/*.spec.{ts,tsx}',
        'src/**/index.ts', // Re-export files
        'src/types/**', // Type definitions
        'src/**/*.stories.tsx', // Storybook stories
      ],

      // Coverage thresholds - CI will fail below these
      thresholds: {
        global: {
          statements: 70,
          branches: 65,
          functions: 70,
          lines: 70,
        },
        // Per-file thresholds (stricter for critical files)
        'src/lib/auth.ts': {
          statements: 90,
          branches: 85,
        },
        'src/lib/payments/**': {
          statements: 85,
          branches: 80,
        },
      },

      // Fail if coverage drops below thresholds
      check: true,
    },

    // Reporter configuration
    reporters: ['default', 'html'],

    // Output directory for reports
    outputFile: {
      html: './coverage/test-report.html',
      json: './coverage/test-results.json',
    },

    // Timeout for each test (ms)
    testTimeout: 10000,

    // Timeout for hooks (beforeEach, afterEach, etc.)
    hookTimeout: 10000,

    // Run tests in parallel (per file)
    pool: 'threads',
    poolOptions: {
      threads: {
        // Use half of available CPUs
        minThreads: 1,
        maxThreads: 4,
      },
    },

    // Retry failed tests (useful in CI)
    retry: process.env.CI ? 2 : 0,

    // Fail fast - stop on first failure
    bail: process.env.CI ? 1 : 0,

    // Mock configuration
    mockReset: true, // Reset mocks before each test
    clearMocks: true, // Clear mock call history
    restoreMocks: true, // Restore original implementations

    // Dependency optimization
    deps: {
      // Inline dependencies for faster resolution
      inline: [
        /@testing-library/,
        /next/,
      ],
    },

    // Type checking in tests (slower but catches issues)
    typecheck: {
      enabled: false, // Enable for stricter checks
      checker: 'tsc',
    },
  },

  // Path resolution (mirrors tsconfig)
  resolve: {
    alias: {
      '@': resolve(__dirname, './src'),
      '@/tests': resolve(__dirname, './tests'),
    },
  },

  // Environment variables for tests
  define: {
    'process.env.NODE_ENV': '"test"',
  },
});

// tests/setup.ts
import '@testing-library/jest-dom/vitest';
import { cleanup } from '@testing-library/react';
import { afterEach, beforeAll, afterAll, vi } from 'vitest';
import { server } from './mocks/server';

// ============================================
// GLOBAL MOCKS
// ============================================

// Mock next/navigation - required for components using routing
vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: vi.fn(),
    replace: vi.fn(),
    refresh: vi.fn(),
    back: vi.fn(),
    forward: vi.fn(),
    prefetch: vi.fn(),
  }),
  usePathname: () => '/dashboard',
  useSearchParams: () => new URLSearchParams(),
  useParams: () => ({}),
  redirect: vi.fn(),
  notFound: vi.fn(),
}));

// Mock next/image - avoids issues with image optimization in tests
vi.mock('next/image', () => ({
  default: ({ src, alt, ...props }: { src: string; alt: string }) => {
    // eslint-disable-next-line @next/next/no-img-element
    return <img src={src} alt={alt} {...props} />;
  },
}));

// Mock next/link - simplifies link testing
vi.mock('next/link', () => ({
  default: ({ children, href, ...props }: { children: React.ReactNode; href: string }) => {
    return <a href={href} {...props}>{children}</a>;
  },
}));

// Mock next/headers - server component headers
vi.mock('next/headers', () => ({
  cookies: () => ({
    get: vi.fn(),
    set: vi.fn(),
    delete: vi.fn(),
    has: vi.fn(),
    getAll: vi.fn(() => []),
  }),
  headers: () => new Headers(),
}));

// Mock IntersectionObserver - for lazy loading components
const mockIntersectionObserver = vi.fn();
mockIntersectionObserver.mockReturnValue({
  observe: () => null,
  unobserve: () => null,
  disconnect: () => null,
});
window.IntersectionObserver = mockIntersectionObserver;

// Mock ResizeObserver - for responsive components
const mockResizeObserver = vi.fn();
mockResizeObserver.mockReturnValue({
  observe: () => null,
  unobserve: () => null,
  disconnect: () => null,
});
window.ResizeObserver = mockResizeObserver;

// Mock matchMedia - for responsive hooks
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: vi.fn().mockImplementation((query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: vi.fn(),
    removeListener: vi.fn(),
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    dispatchEvent: vi.fn(),
  })),
});

// Mock scrollTo - prevents errors in tests
window.scrollTo = vi.fn();

// Mock localStorage
const localStorageMock = {
  getItem: vi.fn(),
  setItem: vi.fn(),
  removeItem: vi.fn(),
  clear: vi.fn(),
  length: 0,
  key: vi.fn(),
};
Object.defineProperty(window, 'localStorage', { value: localStorageMock });

// Mock sessionStorage
Object.defineProperty(window, 'sessionStorage', { value: localStorageMock });

// ============================================
// MSW SERVER SETUP
// ============================================

// Start MSW server before all tests
beforeAll(() => {
  server.listen({
    onUnhandledRequest: 'warn', // Warn about unhandled requests
  });
});

// Reset handlers after each test
afterEach(() => {
  server.resetHandlers();
});

// Close server after all tests
afterAll(() => {
  server.close();
});

// ============================================
// CLEANUP
// ============================================

// Clean up after each test (unmount React components)
afterEach(() => {
  cleanup();
  vi.clearAllMocks();
});

// ============================================
// CUSTOM MATCHERS
// ============================================

// Add custom matchers for common assertions
expect.extend({
  toBeWithinRange(received: number, floor: number, ceiling: number) {
    const pass = received >= floor && received <= ceiling;
    if (pass) {
      return {
        message: () =>
          `expected ${received} not to be within range ${floor} - ${ceiling}`,
        pass: true,
      };
    } else {
      return {
        message: () =>
          `expected ${received} to be within range ${floor} - ${ceiling}`,
        pass: false,
      };
    }
  },
});

// ============================================
// TYPE DECLARATIONS
// ============================================

declare module 'vitest' {
  interface Assertion<T = unknown> {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface AsymmetricMatchersContaining {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
}

// ============================================
// TEST UTILITIES
// ============================================

// Re-export common utilities for convenience
export * from '@testing-library/react';
export { userEvent } from '@testing-library/user-event';
export { vi } from 'vitest';

// src/lib/utils.test.ts
import { describe, it, expect } from 'vitest';
import {
  formatCurrency,
  truncate,
  slugify,
  capitalize,
  debounce,
  deepMerge,
  isValidEmail,
  generateId,
  parseQueryString,
  formatRelativeTime,
} from '@/lib/utils';

describe('formatCurrency', () => {
  it('formats USD correctly', () => {
    expect(formatCurrency(1000)).toBe('$10.00');
  });

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

  it('handles negative amounts', () => {
    expect(formatCurrency(-500)).toBe('-$5.00');
  });

  it('formats with custom currency', () => {
    expect(formatCurrency(1000, 'EUR')).toBe('€10.00');
  });

  it('handles large numbers', () => {
    expect(formatCurrency(100000000)).toBe('$1,000,000.00');
  });

  it('rounds to two decimal places', () => {
    expect(formatCurrency(1234)).toBe('$12.34');
  });
});

describe('truncate', () => {
  it('truncates long strings', () => {
    expect(truncate('Hello World', 5)).toBe('Hello...');
  });

  it('returns short strings unchanged', () => {
    expect(truncate('Hi', 5)).toBe('Hi');
  });

  it('handles exact length strings', () => {
    expect(truncate('Hello', 5)).toBe('Hello');
  });

  it('uses custom suffix', () => {
    expect(truncate('Hello World', 5, '…')).toBe('Hello…');
  });

  it('handles empty strings', () => {
    expect(truncate('', 5)).toBe('');
  });
});

describe('slugify', () => {
  it('converts spaces to hyphens', () => {
    expect(slugify('Hello World')).toBe('hello-world');
  });

  it('removes special characters', () => {
    expect(slugify('Hello! World?')).toBe('hello-world');
  });

  it('handles multiple spaces', () => {
    expect(slugify('Hello   World')).toBe('hello-world');
  });

  it('converts to lowercase', () => {
    expect(slugify('HELLO WORLD')).toBe('hello-world');
  });

  it('handles unicode characters', () => {
    expect(slugify('Héllo Wörld')).toBe('hello-world');
  });
});

describe('isValidEmail', () => {
  it.each([
    ['test@example.com', true],
    ['user.name@domain.co.uk', true],
    ['user+tag@domain.com', true],
    ['invalid-email', false],
    ['@domain.com', false],
    ['user@', false],
    ['', false],
    ['user@domain', false],
  ])('validates %s as %s', (email, expected) => {
    expect(isValidEmail(email)).toBe(expected);
  });
});

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

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

  it('delays function execution', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 100);

    debounced();
    expect(fn).not.toHaveBeenCalled();

    vi.advanceTimersByTime(100);
    expect(fn).toHaveBeenCalledTimes(1);
  });

  it('only calls once for rapid invocations', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 100);

    debounced();
    debounced();
    debounced();

    vi.advanceTimersByTime(100);
    expect(fn).toHaveBeenCalledTimes(1);
  });

  it('passes arguments to debounced function', () => {
    const fn = vi.fn();
    const debounced = debounce(fn, 100);

    debounced('arg1', 'arg2');
    vi.advanceTimersByTime(100);

    expect(fn).toHaveBeenCalledWith('arg1', 'arg2');
  });
});

describe('deepMerge', () => {
  it('merges flat objects', () => {
    const a = { foo: 1 };
    const b = { bar: 2 };
    expect(deepMerge(a, b)).toEqual({ foo: 1, bar: 2 });
  });

  it('merges nested objects', () => {
    const a = { user: { name: 'John' } };
    const b = { user: { age: 30 } };
    expect(deepMerge(a, b)).toEqual({
      user: { name: 'John', age: 30 },
    });
  });

  it('overwrites primitive values', () => {
    const a = { value: 1 };
    const b = { value: 2 };
    expect(deepMerge(a, b)).toEqual({ value: 2 });
  });

  it('handles arrays', () => {
    const a = { items: [1, 2] };
    const b = { items: [3, 4] };
    expect(deepMerge(a, b)).toEqual({ items: [3, 4] });
  });
});

describe('formatRelativeTime', () => {
  beforeEach(() => {
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2024-01-15T12:00:00Z'));
  });

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

  it('formats seconds ago', () => {
    const date = new Date('2024-01-15T11:59:30Z');
    expect(formatRelativeTime(date)).toBe('30 seconds ago');
  });

  it('formats minutes ago', () => {
    const date = new Date('2024-01-15T11:55:00Z');
    expect(formatRelativeTime(date)).toBe('5 minutes ago');
  });

  it('formats hours ago', () => {
    const date = new Date('2024-01-15T09:00:00Z');
    expect(formatRelativeTime(date)).toBe('3 hours ago');
  });

  it('formats days ago', () => {
    const date = new Date('2024-01-13T12:00:00Z');
    expect(formatRelativeTime(date)).toBe('2 days ago');
  });
});

// src/hooks/use-local-storage.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { renderHook, act } from '@testing-library/react';
import { useLocalStorage } from '@/hooks/use-local-storage';

describe('useLocalStorage', () => {
  beforeEach(() => {
    // Clear localStorage before each test
    localStorage.clear();
    vi.clearAllMocks();
  });

  it('returns initial value when localStorage is empty', () => {
    const { result } = renderHook(() =>
      useLocalStorage('test-key', 'default')
    );

    expect(result.current[0]).toBe('default');
  });

  it('returns stored value from localStorage', () => {
    localStorage.setItem('test-key', JSON.stringify('stored'));

    const { result } = renderHook(() =>
      useLocalStorage('test-key', 'default')
    );

    expect(result.current[0]).toBe('stored');
  });

  it('updates localStorage when value changes', () => {
    const { result } = renderHook(() =>
      useLocalStorage('test-key', 'initial')
    );

    act(() => {
      result.current[1]('updated');
    });

    expect(result.current[0]).toBe('updated');
    expect(localStorage.getItem('test-key')).toBe(JSON.stringify('updated'));
  });

  it('handles function updates', () => {
    const { result } = renderHook(() =>
      useLocalStorage('count', 0)
    );

    act(() => {
      result.current[1]((prev: number) => prev + 1);
    });

    expect(result.current[0]).toBe(1);
  });

  it('handles complex objects', () => {
    const initialValue = { name: 'John', age: 30 };

    const { result } = renderHook(() =>
      useLocalStorage('user', initialValue)
    );

    act(() => {
      result.current[1]({ name: 'Jane', age: 25 });
    });

    expect(result.current[0]).toEqual({ name: 'Jane', age: 25 });
  });

  it('handles JSON parse errors gracefully', () => {
    localStorage.setItem('test-key', 'invalid-json');

    const { result } = renderHook(() =>
      useLocalStorage('test-key', 'default')
    );

    // Should fall back to default value
    expect(result.current[0]).toBe('default');
  });

  it('removes value from localStorage', () => {
    localStorage.setItem('test-key', JSON.stringify('stored'));

    const { result } = renderHook(() =>
      useLocalStorage<string | null>('test-key', null)
    );

    act(() => {
      result.current[1](null);
    });

    expect(localStorage.getItem('test-key')).toBe('null');
  });
});

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

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

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

  it('returns initial value immediately', () => {
    const { result } = renderHook(() => useDebounce('initial', 500));

    expect(result.current).toBe('initial');
  });

  it('updates value after delay', () => {
    const { result, rerender } = renderHook(
      ({ value, delay }) => useDebounce(value, delay),
      { initialProps: { value: 'initial', delay: 500 } }
    );

    rerender({ value: 'updated', delay: 500 });

    // Value should not update immediately
    expect(result.current).toBe('initial');

    // Advance time
    act(() => {
      vi.advanceTimersByTime(500);
    });

    // Now value should update
    expect(result.current).toBe('updated');
  });

  it('cancels previous timeout on rapid changes', () => {
    const { result, rerender } = renderHook(
      ({ value, delay }) => useDebounce(value, delay),
      { initialProps: { value: 'initial', delay: 500 } }
    );

    rerender({ value: 'update1', delay: 500 });
    act(() => vi.advanceTimersByTime(200));

    rerender({ value: 'update2', delay: 500 });
    act(() => vi.advanceTimersByTime(200));

    rerender({ value: 'update3', delay: 500 });
    act(() => vi.advanceTimersByTime(500));

    // Only the last value should be set
    expect(result.current).toBe('update3');
  });
});

// src/hooks/use-async.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { renderHook, waitFor } from '@testing-library/react';
import { useAsync } from '@/hooks/use-async';

describe('useAsync', () => {
  it('handles successful async operation', async () => {
    const asyncFn = vi.fn().mockResolvedValue({ data: 'success' });

    const { result } = renderHook(() => useAsync(asyncFn));

    expect(result.current.isLoading).toBe(true);
    expect(result.current.data).toBeNull();
    expect(result.current.error).toBeNull();

    await waitFor(() => {
      expect(result.current.isLoading).toBe(false);
    });

    expect(result.current.data).toEqual({ data: 'success' });
    expect(result.current.error).toBeNull();
  });

  it('handles failed async operation', async () => {
    const error = new Error('Failed');
    const asyncFn = vi.fn().mockRejectedValue(error);

    const { result } = renderHook(() => useAsync(asyncFn));

    await waitFor(() => {
      expect(result.current.isLoading).toBe(false);
    });

    expect(result.current.data).toBeNull();
    expect(result.current.error).toBe(error);
  });

  it('provides execute function for manual trigger', async () => {
    const asyncFn = vi.fn().mockResolvedValue('result');

    const { result } = renderHook(() =>
      useAsync(asyncFn, { immediate: false })
    );

    expect(result.current.isLoading).toBe(false);
    expect(asyncFn).not.toHaveBeenCalled();

    result.current.execute();

    await waitFor(() => {
      expect(result.current.data).toBe('result');
    });
  });
});

// src/components/auth/sign-in-form.test.tsx
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { SignInForm } from '@/components/auth/sign-in-form';

// Mock the signIn function
const mockSignIn = vi.fn();
vi.mock('next-auth/react', () => ({
  signIn: (...args: unknown[]) => mockSignIn(...args),
}));

// Mock useRouter
const mockPush = vi.fn();
vi.mock('next/navigation', () => ({
  useRouter: () => ({ push: mockPush }),
}));

describe('SignInForm', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    mockSignIn.mockResolvedValue({ ok: true });
  });

  it('renders email and password inputs', () => {
    render(<SignInForm />);

    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
  });

  it('shows validation errors for empty submission', async () => {
    const user = userEvent.setup();
    render(<SignInForm />);

    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
  });

  it('shows validation error for invalid email', async () => {
    const user = userEvent.setup();
    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'invalid-email');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(await screen.findByText(/invalid email/i)).toBeInTheDocument();
  });

  it('submits form with valid credentials', async () => {
    const user = userEvent.setup();
    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    await waitFor(() => {
      expect(mockSignIn).toHaveBeenCalledWith('credentials', {
        email: 'test@example.com',
        password: 'password123',
        redirect: false,
      });
    });
  });

  it('shows loading state during submission', async () => {
    const user = userEvent.setup();
    // Delay the response to test loading state
    mockSignIn.mockImplementation(
      () => new Promise((resolve) => setTimeout(() => resolve({ ok: true }), 100))
    );

    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(screen.getByRole('button', { name: /signing in/i })).toBeDisabled();

    await waitFor(() => {
      expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled();
    });
  });

  it('shows error message on failed sign in', async () => {
    const user = userEvent.setup();
    mockSignIn.mockResolvedValue({ ok: false, error: 'Invalid credentials' });

    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'wrongpassword');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(await screen.findByText(/invalid credentials/i)).toBeInTheDocument();
  });

  it('redirects to dashboard on successful sign in', async () => {
    const user = userEvent.setup();
    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    await waitFor(() => {
      expect(mockPush).toHaveBeenCalledWith('/dashboard');
    });
  });

  it('disables form inputs while submitting', async () => {
    const user = userEvent.setup();
    mockSignIn.mockImplementation(
      () => new Promise((resolve) => setTimeout(() => resolve({ ok: true }), 100))
    );

    render(<SignInForm />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(screen.getByLabelText(/email/i)).toBeDisabled();
    expect(screen.getByLabelText(/password/i)).toBeDisabled();
  });
});