xpeditis2.0/MANUAL_TEST_INSTRUCTIONS.md

Manual Test Instructions for CSV Rate System

Prerequisites

Before running tests, ensure you have:

1. ✅ PostgreSQL running (port 5432)
2. ✅ Redis running (port 6379)
3. ✅ Backend API started (port 4000)
4. ✅ A user account with credentials
5. ✅ An admin account (optional, for admin tests)

Step 1: Start Infrastructure

cd /Users/david/Documents/xpeditis/dev/xpeditis2.0

# Start PostgreSQL and Redis
docker-compose up -d

# Verify services are running
docker ps

Expected output should show postgres and redis containers running.

Step 2: Run Database Migration

cd apps/backend

# Run migrations to create csv_rate_configs table
npm run migration:run

This will:

• Create csv_rate_configs table
• Seed 5 companies: SSC Consolidation, ECU Worldwide, TCC Logistics, NVO Consolidation, Test Maritime Express

Step 3: Start Backend API

cd apps/backend

# Start development server
npm run dev

Expected output:

[Nest] INFO  [NestFactory] Starting Nest application...
[Nest] INFO  [InstanceLoader] AppModule dependencies initialized
[Nest] INFO  Application is running on: http://localhost:4000

Keep this terminal open and running.

Step 4: Get JWT Token

Open a new terminal and run:

# Login to get JWT token
curl -X POST http://localhost:4000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test4@xpeditis.com",
    "password": "SecurePassword123"
  }'

Copy the accessToken from the response and save it for later tests.

Example response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "...",
    "email": "test4@xpeditis.com"
  }
}

Step 5: Test Public Endpoints

Test 1: Get Available Companies

curl -X GET http://localhost:4000/api/v1/rates/companies \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Expected Result:

{
  "companies": [
    "SSC Consolidation",
    "ECU Worldwide",
    "TCC Logistics",
    "NVO Consolidation",
    "Test Maritime Express"
  ],
  "total": 5
}

✅ Verify: You should see 5 companies including "Test Maritime Express"

Test 2: Get Filter Options

curl -X GET http://localhost:4000/api/v1/rates/filters/options \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Expected Result:

{
  "companies": ["SSC Consolidation", "ECU Worldwide", "TCC Logistics", "NVO Consolidation", "Test Maritime Express"],
  "containerTypes": ["LCL"],
  "currencies": ["USD", "EUR"]
}

Test 3: Basic Rate Search (NLRTM → USNYC)

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL"
  }'

Expected Result:

• Multiple results from different companies
• Total price calculated based on max(volume × pricePerCBM, weight × pricePerKG)
• Match scores (0-100%) indicating relevance

Example response:

{
  "results": [
    {
      "companyName": "Test Maritime Express",
      "origin": "NLRTM",
      "destination": "USNYC",
      "totalPrice": {
        "amount": 950.00,
        "currency": "USD"
      },
      "transitDays": 22,
      "matchScore": 95,
      "hasSurcharges": false
    },
    {
      "companyName": "SSC Consolidation",
      "origin": "NLRTM",
      "destination": "USNYC",
      "totalPrice": {
        "amount": 1100.00,
        "currency": "USD"
      },
      "transitDays": 22,
      "matchScore": 92,
      "hasSurcharges": true
    }
    // ... more results
  ],
  "totalResults": 15,
  "matchedCompanies": 5
}

✅ Verify:

1. Results from multiple companies appear
2. Test Maritime Express has lower price than others (~$950 vs ~$1100+)
3. Match scores are calculated
4. Both "all-in" (no surcharges) and surcharged rates appear

Test 4: Filter by Company

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL",
    "filters": {
      "companies": ["Test Maritime Express"]
    }
  }'

✅ Verify: Only Test Maritime Express results appear

Test 5: Filter by Price Range

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL",
    "filters": {
      "minPrice": 900,
      "maxPrice": 1200,
      "currency": "USD"
    }
  }'

✅ Verify: All results have price between $900-$1200

Test 6: Filter by Transit Days

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "containerType": "LCL",
    "filters": {
      "maxTransitDays": 23
    }
  }'

✅ Verify: All results have transit ≤ 23 days

Test 7: Filter by Surcharges (All-in Prices Only)

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25.5,
    "weightKG": 3500,
    "containerType": "LCL",
    "filters": {
      "withoutSurcharges": true
    }
  }'

✅ Verify: All results have hasSurcharges: false

Step 6: Comparator Verification Test

This is the MAIN TEST to verify multiple companies appear with different prices.

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "NLRTM",
    "destination": "USNYC",
    "volumeCBM": 25,
    "weightKG": 3500,
    "palletCount": 10,
    "containerType": "LCL"
  }' | jq '.results[] | {company: .companyName, price: .totalPrice.amount, transit: .transitDays, match: .matchScore}'

Expected Output (sorted by price):

{
  "company": "Test Maritime Express",
  "price": 950.00,
  "transit": 22,
  "match": 95
}
{
  "company": "SSC Consolidation",
  "price": 1100.00,
  "transit": 22,
  "match": 92
}
{
  "company": "TCC Logistics",
  "price": 1120.00,
  "transit": 22,
  "match": 90
}
{
  "company": "NVO Consolidation",
  "price": 1130.00,
  "transit": 22,
  "match": 88
}
{
  "company": "ECU Worldwide",
  "price": 1150.00,
  "transit": 23,
  "match": 86
}

✅ Verification Checklist

• All 5 companies appear in results
• Test Maritime Express has lowest price (~$950)
• Other companies have higher prices (~$1100-$1200)
• Price difference is clearly visible (10-20% cheaper)
• Each company has different pricing
• Match scores are calculated
• Transit days are displayed
• Comparator shows multiple offers correctly ✓

Step 7: Alternative Routes Test

Test other routes to verify CSV data is loaded:

DEHAM → USNYC

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "DEHAM",
    "destination": "USNYC",
    "volumeCBM": 30,
    "weightKG": 4000,
    "containerType": "LCL"
  }'

FRLEH → CNSHG

curl -X POST http://localhost:4000/api/v1/rates/search-csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "origin": "FRLEH",
    "destination": "CNSHG",
    "volumeCBM": 50,
    "weightKG": 8000,
    "containerType": "LCL"
  }'

Step 8: Admin Endpoints (Optional)

Note: These endpoints require ADMIN role.

Get All CSV Configurations

curl -X GET http://localhost:4000/api/v1/admin/csv-rates/config \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Validate CSV File

curl -X POST http://localhost:4000/api/v1/admin/csv-rates/validate/Test%20Maritime%20Express \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Upload New CSV File

curl -X POST http://localhost:4000/api/v1/admin/csv-rates/upload \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -F "file=@/Users/david/Documents/xpeditis/dev/xpeditis2.0/apps/backend/src/infrastructure/storage/csv-storage/rates/test-maritime-express.csv" \
  -F "companyName=Test Maritime Express Updated" \
  -F "fileDescription=Updated fictional carrier rates"

Alternative: Use Automated Test Scripts

Instead of manual curl commands, you can use the automated test scripts:

Option 1: Bash Script

cd apps/backend
chmod +x test-csv-api.sh
./test-csv-api.sh

Option 2: Node.js Script

cd apps/backend
node test-csv-api.js

Both scripts will:

1. Authenticate automatically
2. Run all 9 test scenarios
3. Display results with color-coded output
4. Verify comparator functionality

Troubleshooting

Error: "Cannot connect to database"

# Check PostgreSQL is running
docker ps | grep postgres

# Restart PostgreSQL
docker-compose restart postgres

Error: "Unauthorized"

• Verify JWT token is valid (tokens expire after 15 minutes)
• Get a new token using the login endpoint
• Ensure token is correctly copied (no extra spaces)

Error: "CSV file not found"

• Verify CSV files exist in apps/backend/src/infrastructure/storage/csv-storage/rates/
• Check migration was run successfully
• Verify csv_rate_configs table has 5 records

No Results in Search

• Check that origin/destination match CSV data (e.g., NLRTM, USNYC)
• Verify containerType is "LCL"
• Check volume/weight ranges are within CSV limits
• Try without filters first

Test Maritime Express Not Appearing

• Run migration again: npm run migration:run
• Check database: SELECT company_name FROM csv_rate_configs;
• Verify CSV file exists: ls src/infrastructure/storage/csv-storage/rates/test-maritime-express.csv

Expected Results Summary

Test	Expected Result	Verification
Get Companies	5 companies including Test Maritime Express	✓ Count = 5
Filter Options	Companies, container types, currencies	✓ Data returned
Basic Search	Multiple results from different companies	✓ Multiple companies
Company Filter	Only filtered company appears	✓ Filter works
Price Filter	All results in price range	✓ Range correct
Transit Filter	All results ≤ max transit days	✓ Range correct
Surcharge Filter	Only all-in rates	✓ No surcharges
Comparator	All 5 companies with different prices	✓ Test Maritime Express cheapest
Alternative Routes	Results for DEHAM, FRLEH routes	✓ CSV data loaded

Success Criteria

The CSV rate system is working correctly if:

1. ✅ All 5 companies are available
2. ✅ Search returns results from multiple companies simultaneously
3. ✅ Test Maritime Express appears with lower prices (10-20% cheaper)
4. ✅ All filters work correctly (company, price, transit, surcharges)
5. ✅ Match scores are calculated (0-100%)
6. ✅ Total price includes freight + surcharges
7. ✅ Comparator shows clear price differences between companies
8. ✅ Results can be sorted by different criteria

Next Steps After Testing

Once all tests pass:

1. Frontend Integration: Test the Next.js frontend at http://localhost:3000/rates/csv-search
2. Admin Interface: Test CSV upload at http://localhost:3000/admin/csv-rates
3. Performance: Run load tests with k6
4. Documentation: Update API documentation
5. Deployment: Deploy to staging environment