# jam-ui Testing Plan - Session Flow Verification

**Date:** ${new Date().toLocaleString()}
**Objective:** Verify jam-ui conforms to legacy app API sequence, patterns, and timings

## Overview

This testing plan compares the new jam-ui React application with the legacy Rails application to ensure:
1. API calls match in sequence, timing, and payloads
2. WebSocket connections are established correctly
3. UI components function as expected
4. End-to-end flow works seamlessly

## Testing Layers

### 1. API Sequence Verification Tests
**Purpose:** Ensure jam-ui makes the exact same API calls as the legacy app

**Approach:**
- Intercept all API requests during user flow
- Compare against captured legacy API sequence
- Verify request order, methods, URLs, and payloads
- Check response handling

**Test Files:**
- `test/api-verification/login-api.spec.ts`
- `test/api-verification/session-creation-api.spec.ts`
- `test/api-verification/session-join-api.spec.ts`

### 2. WebSocket Verification Tests
**Purpose:** Ensure WebSocket connections match legacy behavior

**Approach:**
- Monitor WebSocket connection establishment
- Verify connection URLs and parameters
- Check message sequences
- Validate dual connections (native + server)

**Test Files:**
- `test/websocket-verification/ws-connection.spec.ts`
- `test/websocket-verification/ws-messages.spec.ts`

### 3. UI Component Tests
**Purpose:** Test individual UI components in isolation

**Approach:**
- Unit tests for Login, Session Creation, Session Interface components
- Test user interactions
- Validate form submissions
- Check error handling

**Test Files:**
- `test/unit/LoginForm.test.tsx` (using React Testing Library)
- `test/unit/SessionCreationForm.test.tsx`
- `test/unit/SessionInterface.test.tsx`

### 4. E2E Integration Tests
**Purpose:** Test complete user journeys

**Approach:**
- Full flow from login to session join
- Real browser automation with Playwright
- Visual verification with screenshots
- Performance timing checks

**Test Files:**
- `test/e2e/complete-session-flow.spec.ts`
- `test/e2e/login-flow.spec.ts`
- `test/e2e/session-creation-flow.spec.ts`

## Test Environment

**jam-ui Application:**
- URL: http://beta.jamkazam.local:4000/
- Credentials: nuwan@jamkazam.com / jam123

**Legacy Application:**
- URL: http://www.jamkazam.local:3100/
- Used for baseline comparison

## Expected API Sequences (from verification)

### Login Flow (12 API calls)
```
POST /api/sessions (or similar login endpoint)
GET /api/users/{user_id}
GET /api/countries
GET /api/shopping_carts
GET /api/jamtracks/purchased
GET /api/teacher_distributions
GET /api/regions
GET /api/genres
GET /api/users/{user_id}/broadcast_notification
```

### Session Creation Flow (38 API calls)
```
# Dashboard reload (Ctrl+Shift+0 or equivalent)
GET /api/users/{user_id} (2x)
GET /api/countries
GET /api/shopping_carts
GET /api/genres (3x)
GET /api/instruments (3x)
GET /api/users/{user_id}/friends (2x)
GET /api/jamtracks/purchased (3x)
GET /api/languages
GET /api/subjects
GET /api/chat (2x)
GET /api/sessions/scheduled
GET /api/users/{user_id}/notifications
GET /api/regions
GET /api/teacher_distributions
GET /api/versioncheck (3x)
GET /api/config/client

# Session creation
POST /api/sessions
POST /api/sessions/{session_id}/participants
GET /api/sessions/{session_id}/history
GET /api/sessions/{session_id} (3x)
PUT /api/sessions/{session_id}/tracks (3x)
GET /api/chat?...&channel=session&music_session={session_id}
POST /api/users/{user_id}/udp_reachable
GET /api/users/{user_id}/broadcast_notification
```

### WebSocket Connections
```
1. Dashboard connection: ws://www.jamkazam.local:6767/websocket?...
2. Native client: ws://localhost:3060/
3. Session connection: ws://www.jamkazam.local:6767/websocket?...&client_id=...
```

## Test Implementation Strategy

### Phase 1: Setup & Infrastructure (Day 1)
- [ ] Set up test utilities and helpers
- [ ] Create API interception utilities
- [ ] Create WebSocket monitoring utilities
- [ ] Set up test data fixtures
- [ ] Create comparison utilities for API sequences

### Phase 2: API Verification Tests (Day 1-2)
- [ ] Login API sequence test
- [ ] Session creation API sequence test
- [ ] Session join API sequence test
- [ ] WebSocket connection tests
- [ ] WebSocket message sequence tests

### Phase 3: UI Component Tests (Day 2)
- [ ] LoginForm unit tests
- [ ] Session creation form unit tests
- [ ] Session interface component tests

### Phase 4: E2E Tests (Day 3)
- [ ] Complete login flow E2E
- [ ] Complete session creation flow E2E
- [ ] Complete session join flow E2E
- [ ] Error scenarios and edge cases

### Phase 5: Documentation & Reporting (Day 3)
- [ ] Test execution guide
- [ ] Failure analysis reports
- [ ] Recommendations for fixes

## Success Criteria

### API Compliance
- ✅ All API calls in correct order
- ✅ Request payloads match legacy
- ✅ Response handling is correct
- ✅ Error cases handled properly

### WebSocket Compliance
- ✅ Connections established to correct endpoints
- ✅ Connection parameters match legacy
- ✅ Message sequences match
- ✅ Dual connections work correctly

### UI Functionality
- ✅ All forms submit correctly
- ✅ Navigation works as expected
- ✅ Error messages display properly
- ✅ Loading states work correctly

### E2E Flow
- ✅ User can log in successfully
- ✅ User can create a session
- ✅ User can join a session
- ✅ Session interface loads completely
- ✅ No console errors

## Test Execution

### Run All Tests
```bash
npm test
```

### Run Specific Test Suites
```bash
# API verification only
npm run test:api

# UI component tests only
npm run test:unit

# E2E tests only
npm run test:e2e

# WebSocket tests only
npm run test:ws
```

### Run with Coverage
```bash
npm run test:coverage
```

### Run in CI/CD
```bash
npm run test:ci
```

## Test Data Management

### User Accounts
- Primary test user: nuwan@jamkazam.com
- Additional test users from `test/data/users.js`

### Session Data
- Test session templates in `test/fixtures/sessions.json`
- Mock API responses in `test/fixtures/api-responses.json`

### Legacy Baseline
- API sequences captured in `test-results/step-verification/`
- Use as reference for comparison

## Reporting

### Test Reports Location
- HTML reports: `test-results/html/`
- JSON reports: `test-results/json/`
- Screenshots: `test-results/screenshots/`
- HAR files: `test-results/har/`
- Comparison reports: `test-results/comparison/`

### Metrics Tracked
1. API call count per flow
2. API call timing/latency
3. WebSocket message count
4. WebSocket connection timing
5. UI rendering time
6. E2E flow completion time
7. Error rates

## Next Steps

1. Review this plan
2. Create test utility infrastructure
3. Implement API verification tests
4. Implement UI unit tests
5. Implement E2E tests
6. Run tests and generate reports
7. Analyze discrepancies
8. Provide recommendations for fixes

---

**Status:** Planning Phase
**Estimated Effort:** 3 days
**Priority:** High
