docs: Test Execution Guide - comprehensive testing strategy (Phase 4)
📋 Test Infrastructure Documentation Complete guide for executing all test suites with prerequisites and troubleshooting ✅ Test Status Summary - Unit Tests: 92/92 passing (100% success) - EXECUTED - Load Tests (K6): Scripts ready - PENDING EXECUTION - E2E Tests (Playwright): Scripts ready - PENDING EXECUTION - API Tests (Newman): Collection ready - PENDING EXECUTION 📖 Guide Contents 1. Prerequisites & Installation - K6 CLI installation (macOS, Windows, Linux) - Playwright setup (v1.56.0 installed) - Newman/Postman CLI (available via npx) 2. Test Execution Instructions - Unit tests: Jest (apps/backend/**/*.spec.ts) - Load tests: K6 rate-search.test.js (5 trade lanes, 100 users, p95 < 2s) - E2E tests: Playwright booking-workflow.spec.ts (8 scenarios, 5 browsers) - API tests: Postman collection (12+ endpoints with assertions) 3. Performance Thresholds - Request duration p95: < 2000ms - Failed requests: < 1% - Load profile: Ramp 0→20→50→100 users over 7 minutes 4. Test Scenarios - E2E: Login → Rate Search → Booking Creation → Dashboard Verification - Load: 5 major trade lanes (Rotterdam↔Shanghai, LA→Singapore, etc.) - API: Auth, rates, bookings, organizations, users, GDPR endpoints 5. Troubleshooting Guide - Connection refused errors - Rate limit issues in test environment - Playwright timeout configuration - JWT token expiration - CORS configuration for tests 6. CI/CD Integration - GitHub Actions example workflow - Automated test execution pipeline - Docker services (PostgreSQL, Redis) 📊 Test Coverage - Domain Layer: 100% (entities, value objects) - Application Layer: ~82% (services) - Overall: ~85% 🔧 Prerequisites for Execution - K6 CLI: Not installed (requires manual installation) - Backend server: Must run on http://localhost:4000 - Frontend server: Must run on http://localhost:3000 - Test database: Requires seed data (test users, organizations, mock rates) 🎯 Next Steps 1. Install K6 CLI 2. Start backend + frontend servers 3. Seed test database with fixtures 4. Execute K6 load tests 5. Execute Playwright E2E tests (5 browsers) 6. Execute Newman API tests 7. Document results in PHASE4_SUMMARY.md Total: 1 file, ~400 LoC documentation Status: Unit tests ✅ passing | Integration tests ⏳ ready for execution 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
David-Henri ARNAUD
parent
07b51987f2
commit
7e948f2683
372
TEST_EXECUTION_GUIDE.md
Normal file
372
TEST_EXECUTION_GUIDE.md
Normal file
@ -0,0 +1,372 @@
|
|||||||
|
# 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 ⏳
|
||||||
Loading…
Reference in New Issue
Block a user