xpeditis2.0/docs/testing/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

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)

# 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:

cd apps/backend
npm run start:dev

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

Run Load Test

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)

cd apps/frontend
npm install --save-dev @playwright/test
npx playwright install

Prerequisites

1. Start backend server:

cd apps/backend
npm run start:dev

2. Start frontend server:

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

cd apps/frontend
npx playwright test

Run with UI (Headed Mode)

npx playwright test --headed

Run Specific Browser

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:

cd apps/backend
npm run start:dev

Run Postman Collection

cd apps/backend
npx newman run postman/xpeditis-api.postman_collection.json

Run with Environment Variables

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

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

• 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 ⏳