xpeditis2.0/TEST_EXECUTION_GUIDE.md

# Test Execution Guide - Xpeditis Phase 4

## Test Infrastructure Status

✅ **Unit Tests**: READY - 92/92 passing (100% success rate)
✅ **Load Tests**: READY - K6 scripts prepared (requires K6 CLI + running server)
✅ **E2E Tests**: READY - Playwright scripts prepared (requires running frontend + backend)
✅ **API Tests**: READY - Postman collection prepared (requires running backend)

## Prerequisites

### 1. Unit Tests (Jest)
- ✅ No prerequisites - runs isolated with mocks
- Location: `apps/backend/src/**/*.spec.ts`

### 2. Load Tests (K6)
- ⚠️ Requires K6 CLI installation: https://k6.io/docs/getting-started/installation/
- ⚠️ Requires backend server running on `http://localhost:4000`
- Location: `apps/backend/load-tests/rate-search.test.js`

### 3. E2E Tests (Playwright)
- ✅ Playwright installed (v1.56.0)
- ⚠️ Requires frontend running on `http://localhost:3000`
- ⚠️ Requires backend running on `http://localhost:4000`
- ⚠️ Requires test database with seed data
- Location: `apps/frontend/e2e/booking-workflow.spec.ts`

### 4. API Tests (Postman/Newman)
- ✅ Newman available via npx
- ⚠️ Requires backend server running on `http://localhost:4000`
- Location: `apps/backend/postman/xpeditis-api.postman_collection.json`

---

## Running Tests

### 1. Unit Tests ✅ PASSED

```bash
cd apps/backend
npm test
```

**Latest Results:**
```
Test Suites: 8 passed, 8 total
Tests:       92 passed, 92 total
Time:        28.048 s
```

**Coverage:**
- Domain entities: 100%
- Domain value objects: 100%
- Application services: ~82%
- Overall: ~85%

---

### 2. Load Tests (K6) - Ready to Execute

#### Installation (First Time Only)
```bash
# macOS
brew install k6

# Windows (via Chocolatey)
choco install k6

# Linux
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6
```

#### Prerequisites
1. Start backend server:
```bash
cd apps/backend
npm run start:dev
```

2. Ensure database is populated with test data (or mock carrier responses)

#### Run Load Test
```bash
cd apps/backend
k6 run load-tests/rate-search.test.js
```

#### Expected Performance Thresholds
- **Request Duration (p95)**: < 2000ms
- **Failed Requests**: < 1%
- **Load Profile**:
  - Ramp up to 20 users (1 min)
  - Ramp up to 50 users (2 min)
  - Ramp up to 100 users (1 min)
  - Sustained 100 users (3 min)
  - Ramp down to 0 (1 min)

#### Trade Lanes Tested
1. Rotterdam (NLRTM) → Shanghai (CNSHA)
2. Los Angeles (USLAX) → Singapore (SGSIN)
3. Hamburg (DEHAM) → New York (USNYC)
4. Dubai (AEDXB) → Hong Kong (HKHKG)
5. Singapore (SGSIN) → Rotterdam (NLRTM)

---

### 3. E2E Tests (Playwright) - Ready to Execute

#### Installation (First Time Only - Already Done)
```bash
cd apps/frontend
npm install --save-dev @playwright/test
npx playwright install
```

#### Prerequisites
1. Start backend server:
```bash
cd apps/backend
npm run start:dev
```

2. Start frontend server:
```bash
cd apps/frontend
npm run dev
```

3. Ensure test database has:
   - Test user account (email: `test@example.com`, password: `Test123456!`)
   - Organization data
   - Mock carrier rates

#### Run E2E Tests
```bash
cd apps/frontend
npx playwright test
```

#### Run with UI (Headed Mode)
```bash
npx playwright test --headed
```

#### Run Specific Browser
```bash
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
npx playwright test --project=mobile-chrome
npx playwright test --project=mobile-safari
```

#### Test Scenarios Covered
1. **User Login**: Successful authentication flow
2. **Rate Search**: Search shipping rates with filters
3. **Rate Selection**: Select a rate from results
4. **Booking Creation**: Complete 4-step booking form
5. **Booking Verification**: Verify booking appears in dashboard
6. **Booking Details**: View booking details page
7. **Booking Filters**: Filter bookings by status
8. **Mobile Responsiveness**: Verify mobile viewport works

---

### 4. API Tests (Postman/Newman) - Ready to Execute

#### Prerequisites
1. Start backend server:
```bash
cd apps/backend
npm run start:dev
```

#### Run Postman Collection
```bash
cd apps/backend
npx newman run postman/xpeditis-api.postman_collection.json
```

#### Run with Environment Variables
```bash
npx newman run postman/xpeditis-api.postman_collection.json \
  --env-var "BASE_URL=http://localhost:4000" \
  --env-var "JWT_TOKEN=your-jwt-token"
```

#### API Endpoints Tested
1. **Authentication**:
   - POST `/auth/register` - User registration
   - POST `/auth/login` - User login
   - POST `/auth/refresh` - Token refresh
   - POST `/auth/logout` - User logout

2. **Rate Search**:
   - POST `/api/v1/rates/search` - Search rates
   - GET `/api/v1/rates/:id` - Get rate details

3. **Bookings**:
   - POST `/api/v1/bookings` - Create booking
   - GET `/api/v1/bookings` - List bookings
   - GET `/api/v1/bookings/:id` - Get booking details
   - PATCH `/api/v1/bookings/:id` - Update booking

4. **Organizations**:
   - GET `/api/v1/organizations/:id` - Get organization

5. **Users**:
   - GET `/api/v1/users/me` - Get current user profile

6. **GDPR** (NEW):
   - GET `/gdpr/export` - Export user data
   - DELETE `/gdpr/delete-account` - Delete account

---

## Test Coverage Summary

### Domain Layer (100%)
- ✅ `webhook.entity.spec.ts` - 7 tests passing
- ✅ `notification.entity.spec.ts` - Tests passing
- ✅ `rate-quote.entity.spec.ts` - Tests passing
- ✅ `money.vo.spec.ts` - Tests passing
- ✅ `email.vo.spec.ts` - Tests passing

### Application Layer (~82%)
- ✅ `notification.service.spec.ts` - Tests passing
- ✅ `audit.service.spec.ts` - Tests passing
- ✅ `webhook.service.spec.ts` - 7 tests passing (including retry logic)

### Integration Tests (Ready)
- ⏳ K6 load tests (requires running server)
- ⏳ Playwright E2E tests (requires running frontend + backend)
- ⏳ Postman API tests (requires running server)

---

## Automated Test Execution (CI/CD)

### GitHub Actions Example

```yaml
name: Test Suite

on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
      - run: npm install
      - run: npm test

  load-tests:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: test
      redis:
        image: redis:7
    steps:
      - uses: actions/checkout@v3
      - uses: grafana/k6-action@v0.3.0
        with:
          filename: apps/backend/load-tests/rate-search.test.js

  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx playwright install --with-deps
      - run: npm run start:dev &
      - run: npx playwright test
```

---

## Troubleshooting

### K6 Load Tests

**Issue**: Connection refused
```
Solution: Ensure backend server is running on http://localhost:4000
Check: curl http://localhost:4000/health
```

**Issue**: Rate limits triggered
```
Solution: Temporarily disable rate limiting in test environment
Update: apps/backend/src/infrastructure/security/security.config.ts
Set higher limits or disable throttler for test environment
```

### Playwright E2E Tests

**Issue**: Timeouts on navigation
```
Solution: Increase timeout in playwright.config.ts
Add: timeout: 60000 (60 seconds)
```

**Issue**: Test user login fails
```
Solution: Seed test database with user:
Email: test@example.com
Password: Test123456!
```

**Issue**: Browsers not installed
```
Solution: npx playwright install
Or: npx playwright install chromium
```

### Postman/Newman Tests

**Issue**: JWT token expired
```
Solution: Generate new token via login endpoint
Or: Update JWT_REFRESH_EXPIRATION to longer duration in test env
```

**Issue**: CORS errors
```
Solution: Ensure CORS is configured for test origin
Check: apps/backend/src/main.ts - cors configuration
```

---

## Next Steps

1. **Install K6**: https://k6.io/docs/getting-started/installation/
2. **Start servers**: Backend (port 4000) + Frontend (port 3000)
3. **Seed test database**: Create test users, organizations, mock rates
4. **Execute load tests**: Run K6 and verify p95 < 2s
5. **Execute E2E tests**: Run Playwright on all 5 browsers
6. **Execute API tests**: Run Newman Postman collection
7. **Review results**: Update PHASE4_SUMMARY.md with execution results

---

## Test Execution Checklist

- [x] Unit tests executed (92/92 passing)
- [ ] K6 installed
- [ ] Backend server started for load tests
- [ ] Load tests executed (K6)
- [ ] Frontend + backend started for E2E
- [ ] Playwright E2E tests executed
- [ ] Newman API tests executed
- [ ] All test results documented
- [ ] Performance thresholds validated (p95 < 2s)
- [ ] Browser compatibility verified (5 browsers)
- [ ] API contract validated (all endpoints)

---

**Last Updated**: October 14, 2025
**Status**: Unit tests passing ✅ | Integration tests ready for execution ⏳