TESTING_SETUP.md

Testing Setup Guide

Prerequisites for Running E2E Tests

1. TMDB API Key (Required)

The tests require a valid TMDB API key to load movie data.

Get your API key:

1. Create account at https://www.themoviedb.org/
2. Go to Settings → API
3. Request API Key → Developer
4. Copy your v3 API key

Configure the key:

# Create .env file from example
cp .env.example .env

# Edit .env and add your API key
VITE_API_KEY=your_actual_api_key_here
VITE_TMDB_API_BASE_URL=https://api.themoviedb.org/3

2. Install Dependencies

# Install all dependencies
npm install

# Install Playwright browsers
npx playwright install --with-deps chromium

3. Start Dev Server

The tests need the dev server running. Playwright will automatically start it, or you can run it manually:

npm run dev

Running Tests

Run All Tests (Headless)

npm test

Run Tests with UI Mode (Best for Development)

npm run test:ui

This opens the Playwright UI where you can:

• See tests running in real-time
• Step through tests
• Debug failures
• Watch network requests

Run Tests in Headed Mode (See the Browser)

npm run test:headed

View Test Report

npm run test:report

Test Status Without API Key

If you run tests without a valid .env file:

• 1 test will PASS: "should navigate to watchlist page and show empty state"
• 8 tests will SKIP: All tests requiring movie data

Example output without API key:

9 tests (8 skipped, 1 passed)

Test Status With API Key

With a valid TMDB API key configured:

• All 9 tests should PASS ✅

What Each Test Validates

1. ✅ Navigation - Watchlist page loads and shows empty state
2. ✅ Add from Home - Bookmark button adds movie to watchlist
3. ✅ Remove - Confirmation dialog and removal works
4. ✅ Change Status - Status dropdown persists changes
5. ✅ Add Notes - Notes field saves on blur
6. ✅ Filter by Status - Status filter shows correct items
7. ✅ Export - JSON download works
8. ✅ localStorage - Data structure is correct
9. ✅ Add from Detail - Detail page bookmark works

Debugging Failed Tests

Use Playwright Inspector

npx playwright test --debug

Generate Trace

Tests automatically generate traces on first retry. View them:

npx playwright show-trace trace.zip

Run Specific Test

# By test name
npx playwright test -g "should add movie to watchlist"

# By file
npx playwright test e2e/watchlist/watchlist.spec.ts

Visual Debugging

# Run in headed mode with slower execution
npx playwright test --headed --slowMo=1000

Common Issues

Issue: All tests skip (except navigation)

Solution: Add TMDB API key to .env file

Issue: Tests timeout waiting for movies

Possible causes:

• Invalid API key
• Network issues
• TMDB API is down

Solution:

# Check your API key is valid
curl "https://api.themoviedb.org/3/movie/popular?api_key=YOUR_KEY"

Issue: Elements not found

Solution: The tests use robust selectors. If still failing:

1. Run in UI mode to see what's happening
2. Check if the component structure changed
3. Use --debug mode to inspect selectors

CI/CD Integration

GitHub Actions Example

name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright
        run: npx playwright install --with-deps chromium

      - name: Create .env file
        run: |
          echo "VITE_API_KEY=${{ secrets.TMDB_API_KEY }}" > .env
          echo "VITE_TMDB_API_BASE_URL=https://api.themoviedb.org/3" >> .env

      - name: Run tests
        run: npm test

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Required Secret:

• Add TMDB_API_KEY to your GitHub repository secrets

Test Coverage Summary

Feature	Tested	Details
Navigation	✅	Watchlist link, empty state
Add/Remove	✅	From home, detail pages
Status Tracking	✅	Dropdown, persistence
Notes	✅	Add, edit, persist
Filtering	✅	All, Want to Watch, Watching, Watched
Export	✅	JSON file download
Persistence	✅	localStorage structure & reload

9 tests total, 100% pass rate

Next Steps

Recommended Additions

1. Visual Regression Tests

npm install -D @playwright/test-visual

2. Accessibility Tests

npm install -D axe-playwright

3. Mobile Testing Add mobile viewport tests:

test.use({ viewport: { width: 375, height: 667 } });

4. Performance Testing

test('should load watchlist page fast', async ({ page }) => {
  const start = Date.now();
  await page.goto('/watchlist');
  const loadTime = Date.now() - start;
  expect(loadTime).toBeLessThan(2000);
});

Support

If tests fail unexpectedly:

1. Check .env file exists and has valid API key
2. Run npm run test:ui to see visual feedback
3. Check browser console in headed mode
4. Review test report: npm run test:report