portfolio/TESTING_GUIDE.md

# 🧪 Automated Testing Guide

This guide explains how to run automated tests for critical paths, hydration, emails, and more.

## 📋 Test Types

### 1. Unit Tests (Jest)
Tests individual components and functions in isolation.

```bash
npm run test              # Run all unit tests
npm run test:watch        # Watch mode
npm run test:coverage    # With coverage report
```

### 2. E2E Tests (Playwright)
Tests complete user flows in a real browser.

```bash
npm run test:e2e          # Run all E2E tests
npm run test:e2e:ui       # Run with UI mode (visual)
npm run test:e2e:headed   # Run with visible browser
npm run test:e2e:debug    # Debug mode
```

### 3. Critical Path Tests
Tests the most important user flows.

```bash
npm run test:critical     # Run critical path tests only
```

### 4. Hydration Tests
Ensures React hydration works without errors.

```bash
npm run test:hydration    # Run hydration tests only
```

### 5. Email Tests
Tests email API endpoints.

```bash
npm run test:email        # Run email tests only
```

### 6. Performance Tests
Checks page load times and performance.

```bash
npm run test:performance  # Run performance tests
```

### 7. Accessibility Tests
Basic accessibility checks.

```bash
npm run test:accessibility # Run accessibility tests
```

## 🚀 Running All Tests

### Quick Test (Recommended)
```bash
npm run test:all
```

This runs:
- ✅ TypeScript check
- ✅ ESLint
- ✅ Build
- ✅ Unit tests
- ✅ Critical paths
- ✅ Hydration tests
- ✅ Email tests
- ✅ Performance tests
- ✅ Accessibility tests

### Individual Test Suites
```bash
# Unit tests only
npm run test

# E2E tests only
npm run test:e2e

# Both
npm run test && npm run test:e2e
```

## 📝 What Gets Tested

### Critical Paths
- ✅ Home page loads correctly
- ✅ Projects page displays projects
- ✅ Individual project pages work
- ✅ Admin dashboard is accessible
- ✅ API health endpoint
- ✅ API projects endpoint

### Hydration
- ✅ No hydration errors in console
- ✅ No duplicate React key warnings
- ✅ Client-side navigation works
- ✅ Server and client HTML match
- ✅ Interactive elements work after hydration

### Email
- ✅ Email API accepts requests
- ✅ Required field validation
- ✅ Email format validation
- ✅ Rate limiting (if implemented)
- ✅ Email respond endpoint

### Performance
- ✅ Page load times (< 5s)
- ✅ No large layout shifts
- ✅ Images are optimized
- ✅ API response times (< 1s)

### Accessibility
- ✅ Proper heading structure
- ✅ Images have alt text
- ✅ Links have descriptive text
- ✅ Forms have labels

## 🎯 Pre-Push Testing

Before pushing to main, run:

```bash
# Full test suite
npm run test:all

# Or manually:
npm run build
npm run lint
npx tsc --noEmit
npm run test
npm run test:critical
npm run test:hydration
```

## 🔧 Configuration

### Playwright Config
Located in `playwright.config.ts`

- **Base URL**: `http://localhost:3000` (or set `PLAYWRIGHT_TEST_BASE_URL`)
- **Browsers**: Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari
- **Retries**: 2 retries in CI, 0 locally
- **Screenshots**: On failure
- **Videos**: On failure

### Jest Config
Located in `jest.config.ts`

- **Environment**: jsdom
- **Coverage**: v8 provider
- **Setup**: `jest.setup.ts`

## 🐛 Debugging Tests

### Playwright Debug Mode
```bash
npm run test:e2e:debug
```

This opens Playwright Inspector where you can:
- Step through tests
- Inspect elements
- View console logs
- See network requests

### UI Mode (Visual)
```bash
npm run test:e2e:ui
```

Shows a visual interface to:
- See all tests
- Run specific tests
- Watch tests execute
- View results

### Headed Mode
```bash
npm run test:e2e:headed
```

Runs tests with visible browser (useful for debugging).

## 📊 Test Reports

### Playwright HTML Report
After running E2E tests:
```bash
npx playwright show-report
```

Shows:
- Test results
- Screenshots on failure
- Videos on failure
- Timeline of test execution

### Jest Coverage Report
```bash
npm run test:coverage
```

Generates coverage report in `coverage/` directory.

## 🚨 Common Issues

### Tests Fail Locally But Pass in CI
- Check environment variables
- Ensure database is set up
- Check for port conflicts

### Hydration Errors
- Check for server/client mismatches
- Ensure no conditional rendering based on `window`
- Check for date/time differences

### Email Tests Fail
- Email service might not be configured
- Check environment variables
- Tests are designed to handle missing email service

### Performance Tests Fail
- Network might be slow
- Adjust thresholds in test file
- Check for heavy resources loading

## 📝 Writing New Tests

### E2E Test Example
```typescript
import { test, expect } from '@playwright/test';

test('My new feature works', async ({ page }) => {
  await page.goto('/my-page');
  await expect(page.locator('h1')).toContainText('Expected Text');
});
```

### Unit Test Example
```typescript
import { render, screen } from '@testing-library/react';
import MyComponent from './MyComponent';

test('renders correctly', () => {
  render(<MyComponent />);
  expect(screen.getByText('Hello')).toBeInTheDocument();
});
```

## 🎯 CI/CD Integration

### GitHub Actions Example
```yaml
- name: Run tests
  run: |
    npm install
    npm run test:all
```

### Pre-Push Hook
Add to `.git/hooks/pre-push`:
```bash
#!/bin/bash
npm run test:all
```

## 📚 Resources

- [Playwright Docs](https://playwright.dev)
- [Jest Docs](https://jestjs.io)
- [Testing Library](https://testing-library.com)

---

**Remember**: Tests should be fast, reliable, and easy to understand! 🚀