motovaultpro/docs/PLATFORM-INTEGRATION-TESTING.md

Platform Integration Testing Guide

Prerequisites

Docker must be running:

# 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

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

# Expected: No TypeScript errors

2. Linter Verification

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

# Expected: Zero linting issues

3. Platform Feature Unit Tests

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Check compilation
docker compose exec mvp-backend npm run type-check

# If errors, review files modified by agents

Test Failures

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

# Check test logs for details

VIN Decode Not Working

# 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

# 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

# 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