# E2E Test Suite - LLMHosts.com Frontend

Comprehensive end-to-end tests covering critical user journeys using Playwright.

## Overview

This test suite validates 6 complete user flows with browser automation, screenshot capture, console error monitoring, and database state verification.

## Test Journeys

### Journey 1: Registration → Email Verification → Login
**File**: `01-registration-verification-login.spec.ts`
**Tests**: 2
**Coverage**:
- Full registration flow with email verification
- Login prevention for unverified emails
- Token creation and consumption
- Database state verification

### Journey 2: Stripe Checkout → Upgrade to Pro → Billing Portal
**File**: `02-stripe-checkout-upgrade-portal.spec.ts`
**Tests**: 4
**Coverage**:
- Upgrade button visibility on free plan
- Stripe checkout flow (UI-only, mocked)
- Billing portal access
- Simulated Pro plan upgrade via database

### Journey 3: CRUD Cost Entries with Filters
**File**: `03-cost-entries-crud-filters.spec.ts`
**Tests**: 5
**Coverage**:
- Create new cost entry via UI
- Read and display multiple entries
- Update existing entry
- Delete entry
- Filter by period

### Journey 4: CRUD API Keys with Plan Limits
**File**: `04-api-keys-crud-limits.spec.ts`
**Tests**: 6
**Coverage**:
- Create new API key
- Display keys with masked values
- Revoke/delete keys
- Enforce free plan limits (2 keys)
- Allow more keys on Pro plan (10 keys)
- Track lastUsed timestamp

### Journey 5: Password Reset Full Flow
**File**: `05-password-reset-flow.spec.ts`
**Tests**: 5
**Coverage**:
- Complete password reset flow
- Invalid token handling
- Expired token handling
- Email enumeration prevention
- Password validation enforcement

### Journey 6: Dashboard Navigation + Data Accuracy
**File**: `06-dashboard-navigation-data.spec.ts`
**Tests**: 7
**Coverage**:
- Navigate all dashboard pages
- Cost data accuracy
- API key count and usage display
- User profile information
- Empty state handling
- Session persistence
- Logout flow

## Running Tests

```bash
# Run all E2E tests
npm run test:e2e

# Run with UI mode
npm run test:e2e:ui

# Run in debug mode
npm run test:e2e:debug

# Run specific test file
npx playwright test 01-registration-verification-login

# Run specific test
npx playwright test -g "should complete full registration"
```

## Test Infrastructure

### Configuration
- **File**: `playwright.config.ts`
- **Browser**: Chromium (Desktop Chrome)
- **Base URL**: http://localhost:3000
- **Automatic server start**: Next.js dev server launches before tests
- **Screenshots**: Captured on all tests
- **Video**: Retained on failure
- **Retries**: 2 retries in CI, 0 locally

### Test Helpers
**File**: `e2e/utils/test-helpers.ts`

**Functions**:
- `createTestUser()` - Create verified test user
- `createUnverifiedTestUser()` - Create user without email verification
- `deleteTestUser(email)` - Clean up test user
- `cleanupTestUsers()` - Delete all test users
- `loginUser(page, email, password)` - Login via UI
- `takeScreenshot(page, name)` - Capture screenshot
- `setupConsoleErrorTracking(page)` - Monitor console errors
- `closeDatabaseConnection()` - Clean up database
- `getDatabase()` - Get Prisma client instance

## Screenshots

All screenshots are saved to `e2e/screenshots/` with descriptive names:

```
e2e/screenshots/
  01-registration-page.png
  02-registration-form-filled.png
  03-registration-submitted.png
  ...
  147-logout-not-found.png
```

**Total Screenshots**: ~150 screenshots across all journeys

## Database Setup

Tests use the same SQLite database as the dev environment:

```env
DATABASE_URL="file:./prisma/dev.db"
```

**Important**: Tests create and clean up their own data, but use the real database schema.

## Test Patterns

### AAA Pattern (Arrange-Act-Assert)
All tests follow this structure:

```typescript
test('should do something', async ({ page }) => {
  // Arrange - Set up test data
  const testUser = await createTestUser();
  await loginUser(page, testUser.email, testUser.password);

  // Act - Perform action
  await page.goto('/dashboard/spending');
  await page.click('button:has-text("Add Entry")');
  await page.fill('input[name="amount"]', '49.99');
  await page.click('button[type="submit"]');

  // Assert - Verify results
  const entry = await db.costEntry.findFirst({ where: { userId: testUser.id } });
  expect(entry?.amount).toBe(49.99);

  // Cleanup
  await deleteTestUser(testUser.email);
});
```

### Console Error Tracking
Every test monitors console errors:

```typescript
test.beforeEach(async ({ page }) => {
  consoleErrors = setupConsoleErrorTracking(page);
});

test('...', async ({ page }) => {
  // ... test code ...

  // Verify no errors
  expect(consoleErrors).toHaveLength(0);
});
```

### Screenshot Strategy
Screenshots are taken at key points:
- Page load
- Form filled
- After submission
- Success/error states
- Database state changes

## CI/CD Integration

Tests are designed to run in CI environments:

```yaml
# .github/workflows/e2e.yml example
- name: Install dependencies
  run: npm ci

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

- name: Run E2E tests
  run: npm run test:e2e
```

## Troubleshooting

### Tests timing out
- Increase timeout in `playwright.config.ts`
- Check if Next.js dev server started properly

### Screenshots not saving
- Ensure `e2e/screenshots/` directory exists
- Check file permissions

### Database errors
- Run `npx prisma migrate dev` to ensure schema is up to date
- Check `DATABASE_URL` in `.env.local`

### Login failures
- Verify `NEXTAUTH_URL` and `NEXTAUTH_SECRET` are set
- Check if email verification is enforced

## Coverage Summary

| Journey | Tests | Screenshots | Database Checks |
|---------|-------|-------------|-----------------|
| 1. Registration/Verification | 2 | 14 | ✅ |
| 2. Stripe Upgrade | 4 | 13 | ✅ |
| 3. Cost Entries CRUD | 5 | 25 | ✅ |
| 4. API Keys CRUD | 6 | 29 | ✅ |
| 5. Password Reset | 5 | 30 | ✅ |
| 6. Dashboard Navigation | 7 | ~35 | ✅ |
| **Total** | **29** | **~146** | **All** |

## Next Steps

To run the full test suite:

1. Ensure dev environment is set up:
   ```bash
   npm install
   npx prisma generate
   npx prisma migrate dev
   ```

2. Create `.env.local` with required variables:
   ```env
   DATABASE_URL="file:./prisma/dev.db"
   NEXTAUTH_URL="http://localhost:3000"
   NEXTAUTH_SECRET="dev-secret-change-in-production"
   ```

3. Run tests:
   ```bash
   npm run test:e2e
   ```

## Maintenance

- **Add new journeys**: Create new `.spec.ts` files following the existing pattern
- **Update helpers**: Modify `test-helpers.ts` for reusable functionality
- **Screenshot cleanup**: Periodically review and remove outdated screenshots
- **Database cleanup**: Tests clean up after themselves, but manual cleanup may be needed if tests crash

## Notes

- Tests are designed to be **idempotent** - can run multiple times safely
- Each test creates its own test user with timestamp-based email
- Cleanup happens in `afterEach` hooks
- Screenshots provide visual regression testing capability
- All tests validate zero console errors
- Database state is verified for data integrity
