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.

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.

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.

npm run test:critical     # Run critical path tests only

4. Hydration Tests

Ensures React hydration works without errors.

npm run test:hydration    # Run hydration tests only

5. Email Tests

Tests email API endpoints.

npm run test:email        # Run email tests only

6. Performance Tests

Checks page load times and performance.

npm run test:performance  # Run performance tests

7. Accessibility Tests

Basic accessibility checks.

npm run test:accessibility # Run accessibility tests

🚀 Running All Tests

Quick Test (Recommended)

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

# 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:

# 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

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)

npm run test:e2e:ui

Shows a visual interface to:

• See all tests
• Run specific tests
• Watch tests execute
• View results

Headed Mode

npm run test:e2e:headed

Runs tests with visible browser (useful for debugging).

📊 Test Reports

Playwright HTML Report

After running E2E tests:

npx playwright show-report

Shows:

• Test results
• Screenshots on failure
• Videos on failure
• Timeline of test execution

Jest Coverage Report

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

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

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

- name: Run tests
  run: |
    npm install
    npm run test:all

Pre-Push Hook

Add to .git/hooks/pre-push:

#!/bin/bash
npm run test:all

📚 Resources

• Playwright Docs
• Jest Docs
• Testing Library

---

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