motovaultpro/docs/PLATFORM-INTEGRATION-TESTING.md

# Platform Integration Testing Guide

## Prerequisites

Docker must be running:
```bash
# Check Docker status
docker compose ps

# If not running, start containers
make rebuild  # Rebuilds with all changes
make start    # Starts all services
```

## Testing Sequence

### 1. TypeScript Compilation Verification

```bash
# In backend container
docker compose exec mvp-backend npm run type-check

# Expected: No TypeScript errors
```

### 2. Linter Verification

```bash
# In backend container
docker compose exec mvp-backend npm run lint

# Expected: Zero linting issues
```

### 3. Platform Feature Unit Tests

```bash
# Run all platform unit tests
docker compose exec mvp-backend npm test -- features/platform/tests/unit

# Expected tests:
# - vin-decode.service.test.ts (VIN validation, circuit breaker, caching)
# - vehicle-data.service.test.ts (dropdown data, caching)
```

### 4. Platform Feature Integration Tests

```bash
# Run platform integration tests
docker compose exec mvp-backend npm test -- features/platform/tests/integration

# Expected tests:
# - GET /api/platform/years
# - GET /api/platform/makes?year=2024
# - GET /api/platform/models?year=2024&make_id=1
# - GET /api/platform/trims?year=2024&model_id=1
# - GET /api/platform/engines?year=2024&trim_id=1
# - GET /api/platform/vehicle?vin=1HGCM82633A123456
# - Authentication (401 without JWT)
# - Validation (400 for invalid params)
```

### 5. Vehicles Feature Integration Tests

```bash
# Run vehicles integration tests
docker compose exec mvp-backend npm test -- features/vehicles/tests/integration

# Expected: VIN decode now uses platform feature
```

### 6. End-to-End Workflow Tests

#### VIN Decode Workflow
```bash
# 1. Start containers
make start

# 2. Get auth token (via frontend or Auth0 test token)

# 3. Test VIN decode endpoint
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/vehicle?vin=1HGCM82633A123456

# Expected:
# {
#   "vin": "1HGCM82633A123456",
#   "success": true,
#   "result": {
#     "make": "Honda",
#     "model": "Accord",
#     "year": 2003,
#     ...
#   }
# }
```

#### Dropdown Cascade Workflow
```bash
# 1. Get years
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/years

# Expected: [2024, 2023, 2022, ...]

# 2. Get makes for 2024
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/makes?year=2024

# Expected: {"makes": [{"id": 1, "name": "Honda"}, ...]}

# 3. Get models for Honda 2024
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/models?year=2024&make_id=1

# Expected: {"models": [{"id": 101, "name": "Civic"}, ...]}
```

### 7. Frontend Testing

#### Desktop Testing
```bash
# 1. Open browser
open https://motovaultpro.com

# 2. Navigate to Vehicles → Add Vehicle

# 3. Test VIN decode:
# - Enter VIN: 1HGCM82633A123456
# - Click "Decode VIN"
# - Verify auto-population of make/model/year

# 4. Test manual selection:
# - Select Year: 2024
# - Select Make: Honda
# - Select Model: Civic
# - Verify cascading dropdowns work
```

#### Mobile Testing
```bash
# Use Chrome DevTools responsive mode

# Test at widths:
# - 320px (iPhone SE)
# - 375px (iPhone 12)
# - 768px (iPad)
# - 1920px (Desktop)

# Verify:
# - 44px minimum touch targets
# - No iOS zoom on input focus (16px font)
# - Dropdowns work on touch devices
# - VIN decode button accessible
# - Both workflows functional
```

### 8. Performance Testing

```bash
# Monitor response times
time curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/years

# Expected: < 500ms (first call, cache miss)
# Expected: < 100ms (second call, cache hit)
```

### 9. Cache Verification

```bash
# Connect to Redis
docker compose exec mvp-redis redis-cli

# Check cache keys
KEYS mvp:platform:*

# Expected keys:
# - mvp:platform:years
# - mvp:platform:vehicle-data:makes:2024
# - mvp:platform:vin-decode:1HGCM82633A123456

# Check TTL
TTL mvp:platform:vehicle-data:makes:2024
# Expected: ~21600 seconds (6 hours)

TTL mvp:platform:vin-decode:1HGCM82633A123456
# Expected: ~604800 seconds (7 days)

# Get cached value
GET mvp:platform:years
# Expected: JSON array of years
```

### 10. Error Handling Tests

```bash
# Test invalid VIN (wrong length)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/vehicle?vin=INVALID

# Expected: 400 Bad Request

# Test missing auth
curl http://localhost:3001/api/platform/years

# Expected: 401 Unauthorized

# Test invalid year
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/makes?year=3000

# Expected: 400 Bad Request or empty array
```

### 11. Circuit Breaker Testing

```bash
# Monitor backend logs
make logs-backend | grep "circuit breaker"

# Should see:
# - State transitions (open/half-open/close)
# - Timeout events
# - Fallback executions

# Test with invalid VIN that requires vPIC API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3001/api/platform/vehicle?vin=UNKNOWNVIN1234567

# Check logs for circuit breaker activity
```

### 12. Container Health Check

```bash
# Verify 5 containers running
docker compose ps

# Expected output:
# mvp-traefik    - running
# mvp-frontend   - running
# mvp-backend    - running
# mvp-postgres   - running
# mvp-redis      - running

# No mvp-platform container should exist

# Check backend health
curl http://localhost:3001/health

# Expected:
# {
#   "status": "healthy",
#   "features": ["vehicles", "documents", "fuel-logs", "stations", "maintenance", "platform"]
# }
```

## Success Criteria

- TypeScript compilation: Zero errors
- Linter: Zero issues
- Unit tests: All passing
- Integration tests: All passing
- VIN decode workflow: Functional
- Dropdown cascade workflow: Functional
- Mobile + desktop: Both responsive and functional
- Cache hit rate: >80% after warm-up
- Response times: <500ms VIN decode, <100ms dropdowns
- 5 containers: Running healthy
- Zero errors: In logs after 1 hour

## Troubleshooting

### TypeScript Errors
```bash
# Check compilation
docker compose exec mvp-backend npm run type-check

# If errors, review files modified by agents
```

### Test Failures
```bash
# Run specific test
docker compose exec mvp-backend npm test -- path/to/test.ts

# Check test logs for details
```

### VIN Decode Not Working
```bash
# Check backend logs
make logs-backend | grep -E "vin|platform"

# Verify vPIC API accessible
curl https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVin/1HGCM82633A123456?format=json

# Check circuit breaker state in logs
```

### Dropdowns Empty
```bash
# Check PostgreSQL vehicles schema
docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "\\dt vehicles.*"

# Query makes table
docker compose exec mvp-postgres psql -U postgres -d motovaultpro -c "SELECT COUNT(*) FROM vehicles.make;"

# Should have data
```

### Frontend Not Loading
```bash
# Check frontend logs
make logs-frontend

# Rebuild frontend
docker compose build mvp-frontend
docker compose restart mvp-frontend
```

## Next Steps After Testing

If all tests pass:
1. Create git tag: `v1.0-platform-integrated`
2. Document any issues in GitHub
3. Monitor production logs for 24 hours
4. Archive Python platform service directory

If tests fail:
1. Review failure logs
2. Fix issues
3. Re-run tests
4. Consider rollback if critical failures