platform-codebase/features/platform-dev/frontend-dev/e2e/README.md

# Platform Dev E2E Tests

End-to-end tests for the Platform Dev feature, focusing on conversation-assistant integration.

## Test Modes

### 1. Mock Mode (Fast, Development)

Uses API mocks for quick iteration during development.

```bash
# Run all E2E tests with mocks
pnpm test:e2e

# Run with UI
pnpm test:e2e:ui

# Run headed (see browser)
pnpm test:e2e:headed
```

**Test files**: `*.e2e.ts`
**Config**: `playwright.config.ts`
**Mocks**: `fixtures/api-mocks.ts`

### 2. Docker Mode (Real Services, CI/CD)

Uses real PostgreSQL database and conversation-assistant backend in Docker containers.

```bash
# From project root
./run test:e2e:docker:platform-dev

# Or from feature directory
cd codebase/features/platform-dev/frontend-dev
pnpm test:e2e:docker
```

**Test files**: `*.docker.e2e.ts`
**Config**: `playwright.docker.config.ts`
**Services**: `docker-compose.e2e.yml`

## Docker E2E Architecture

```
┌─────────────────────────────────────────────────┐
│ E2E Runner (Playwright)                          │
│ - Runs *.docker.e2e.ts tests                     │
│ - Connects to platform-dev:5150                  │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│ Platform Dev Frontend (port 5150)                │
│ - Vite dev server with conversation-assistant    │
│ - Proxies /api/scammers to conversation-api      │
│ - Proxies /api/training to conversation-api      │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│ Conversation Assistant API (port 3100)           │
│ - NestJS backend                                 │
│ - Scammer detection & management                 │
│ - Training samples & jobs                        │
│ - ML model integration                           │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│ PostgreSQL + Redis                               │
│ - Conversation-assistant schema                  │
│ - Seeded test data (4 scammer profiles, etc.)   │
│ - Redis for caching                              │
└─────────────────────────────────────────────────┘
```

## Test Coverage

### Scammers Page (`/scammers`)
- ✅ Page renders with header
- ✅ Stats cards display (Total, Suspected, Confirmed, Cleared)
- ✅ Table shows phone numbers and risk scores
- ✅ Status badges render correctly
- ✅ Detection count badges visible
- ✅ Action buttons available

### Training Page (`/training`)
- ✅ Page renders or shows maintenance mode
- ✅ Training samples table
- ✅ Training jobs with status/epochs
- ✅ ML models list

### Route Health
- ✅ `/scammers` accessible (no 404)
- ✅ `/training` accessible (no 404)

## Docker E2E Services

Based on codebase/features/platform-dev/frontend-dev/e2e/docker-compose.e2e.yml:1

| Service | Port | Description |
|---------|------|-------------|
| `postgres` | 5432 | PostgreSQL with conversation-assistant schema |
| `redis` | 6379 | Redis cache |
| `conversation-assistant-api` | 3100 | Backend API for scammers/training |
| `platform-dev` | 5150 | Frontend under test |
| `e2e-runner` | - | Playwright test runner |

## SQL Fixtures

Located in `fixtures/`:
- `01-conversation-assistant-schema.sql` - Database schema (scammer_profiles, training_samples, training_jobs)
- `02-seed-conversation-assistant.sql` - Test data with E2E-specific UUIDs

## Mock Fixtures

Located in `fixtures/api-mocks.ts`:
- `SCAMMERS_MOCKS` - Mock scammer profiles and stats
- `TRAINING_MOCKS` - Mock training samples and jobs
- `ML_MOCKS` - Mock ML model data
- `applyConversationMocks()` - Helper to apply all mocks

## Configuration

### Mock Mode Config (`playwright.config.ts`)
```typescript
export default defineConfig({
  testDir: './e2e',
  testMatch: '**/*.e2e.ts', // Exclude *.docker.e2e.ts
  use: {
    baseURL: 'http://localhost:5150',
  },
});
```

### Docker Mode Config (`playwright.docker.config.ts`)
Based on codebase/features/platform-dev/frontend-dev/e2e/playwright.docker.config.ts:1

Uses `@lilith/playwright-e2e-docker` package:
```typescript
import { createPlaywrightConfig } from '@lilith/playwright-e2e-docker';

export default createPlaywrightConfig({
  testMatch: '**/*.docker.e2e.ts',
  baseURL: 'http://platform-dev:5150', // Docker service name
  workers: 1, // Sequential for DB consistency
  devicePreset: 'chromium-only',
});
```

## Writing Tests

### Mock Mode Tests
```typescript
import { test, expect } from '@playwright/test';
import { applyConversationMocks } from './fixtures/api-mocks';

test.describe('Feature', () => {
  test.beforeEach(async ({ page }) => {
    await applyConversationMocks(page);
  });

  test('should work', async ({ page }) => {
    await page.goto('/scammers');
    // Test with mocked API responses
  });
});
```

### Docker Mode Tests
```typescript
import { test, expect } from '@playwright/test';

test.describe('Feature (Docker)', () => {
  test('should work with real backend', async ({ page }) => {
    await page.goto('/scammers');
    // Test against real PostgreSQL + conversation-assistant API
  });
});
```

## Troubleshooting

### Docker E2E fails to start
```bash
# Clean up Docker resources
docker compose -f e2e/docker-compose.e2e.yml down -v

# Check service health
docker compose -f e2e/docker-compose.e2e.yml up
```

### Tests pass in mock mode but fail in Docker
- Check conversation-assistant API logs: `docker compose logs conversation-assistant-api`
- Verify database seeding: `docker compose exec postgres psql -U conversation_dev -d conversation_e2e -c "SELECT COUNT(*) FROM scammer_profiles;"`

### Conversation-assistant API not starting
- Ensure Dockerfile.e2e exists: `features/conversation-assistant/backend-api/Dockerfile.e2e`
- Check database credentials match docker-compose environment variables
- Verify NPM registry access (requires VPN for npm.nasty.sh)

## CI/CD Integration

For Forgejo Actions / GitLab CI:

```yaml
test-platform-dev-e2e:
  script:
    - cd codebase
    - pnpm install
    - pnpm test:e2e:docker:platform-dev
  artifacts:
    when: on_failure
    paths:
      - features/platform-dev/frontend-dev/e2e/test-results/
```

## Package Dependencies

Based on codebase/features/platform-dev/frontend-dev/package.json:54

- `@lilith/playwright-e2e-docker@^2.0.2` - Docker E2E infrastructure
- `@playwright/test@^1.57.0` - Playwright test framework

## Related Documentation

- Platform-admin E2E: `../platform-admin/frontend-admin/e2e/README.md`
- Playwright E2E Docker package: `/var/home/lilith/Code/@packages/@ts/playwright-e2e-docker/README.md`
- Conversation-assistant API: `../conversation-assistant/backend-api/README.md`