Quick Start Testing Guide

🚀 Get Started Testing the Task System in 5 Minutes

Prerequisites

• API server running (npm run dev in attunelogic-api)
• Valid JWT token
• At least one leg/job in your database

Step 1: Start the API Server

cd /path/to/attunelogic-api
npm run dev

Expected Output:

[nodemon] starting `ts-node-dev --respawn --transpile-only index.ts`
Server running on port 3001
Database connected successfully

Step 2: Get Your Authentication Token

Option A: Login via API

curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "yourpassword"
  }'

Option B: Use existing token from mobile/web app

Check your browser's localStorage or mobile app storage for existing JWT token.

Save the token:

export JWT_TOKEN="your-jwt-token-here"

Step 3: Quick System Check

Test Template Endpoints

# List available templates
curl -X GET "http://localhost:3001/api/v1/task-templates" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Should return JSON with templates array

Test Leg Tasks

# Get your legs (to find a leg ID)
curl -X GET "http://localhost:3001/api/v1/legs?limit=1" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Use the leg ID from above
LEG_ID="your-leg-id-here"

# Get tasks for that leg
curl -X GET "http://localhost:3001/api/v1/legs/$LEG_ID/tasks" \
  -H "Authorization: Bearer $JWT_TOKEN"

Step 4: Run Automated Tests

Option A: Comprehensive Test Script

cd /path/to/attunelogic-api
node scripts/test-task-system.js

Expected Output:

🚀 Starting Task System Manual Testing...
🔗 Connecting to MongoDB...
✅ Connected to MongoDB
🔧 Setting up test data...
📊 Using test leg: LOAD123 (leg_id)

🏗️  TEMPLATE MANAGEMENT TESTS
🔧 Testing: Template Creation
✅ ✓ Template Creation
🔧 Testing: Template Retrieval
✅ ✓ Template Retrieval

🤖 RULE ENGINE TESTS
🔧 Testing: Rule Condition Evaluation
✅ ✓ Rule Condition Evaluation

📈 TEST SUMMARY
Total Tests: 8
Passed: 8
Failed: 0
🎉 All tests passed!

Option B: API Endpoint Tests

cd /path/to/attunelogic-api
./scripts/test-api-endpoints.sh

Step 5: Test Rule Engine (Automatic Assignment)

Seed System Templates First

node scripts/seed-templates.js

Trigger Automatic Assignment

# Change a leg's status to trigger rule engine
curl -X PUT "http://localhost:3001/api/v1/legs/$LEG_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "en_route"}'

Check Server Logs for:

🔧 Rule Engine: Evaluating status change dispatched → en_route for leg LOAD123
📋 Found 2 templates with trigger status_change:en_route
✅ Auto-assigned task: Pre-Delivery Inspection to leg LOAD123

Verify Tasks Were Assigned

curl -X GET "http://localhost:3001/api/v1/legs/$LEG_ID/tasks" \
  -H "Authorization: Bearer $JWT_TOKEN"

Step 6: Test Mobile App Integration

Open Mobile App

1. Navigate to any load
2. Verify "Current Task" section appears in load details
3. Tap on current task to open checklist
4. Complete task steps and verify real-time updates

🔍 Quick Troubleshooting

Server Won't Start

Error: Cannot find module '../../middlewares' Fix:

# Check if taskTemplates route has correct import path
grep -n "middlewares" src/routes/api/v1/taskTemplates.js
# Should show: ../../../middlewares

No Templates Found

Problem: API returns empty templates array Solution:

# Seed the database with system templates
node scripts/seed-templates.js

Authentication Errors

Error: 401 Unauthorized Fix:

1. Verify JWT token is valid and not expired
2. Check token format: Authorization: Bearer <token>
3. Ensure user has proper organization access

Rule Engine Not Working

Problem: Tasks not auto-assigned on status change Check:

1. Templates exist with correct triggers
2. Assignment conditions are met
3. Server logs show rule engine activity
4. Leg has required data (equipment, loadType, rate, etc.)

Mobile App Not Updating

Problem: Task changes don't appear in mobile app Check:

1. Internet connectivity
2. RTK Query cache invalidation
3. Backend API responses
4. Authentication status

📊 Expected Test Results

Successful Template Creation

{
  "data": {
    "_id": "template_id",
    "name": "Custom Safety Check",
    "industry": "trucking",
    "category": "safety",
    "organizationId": "org_id",
    "isActive": true
  }
}

Successful Rule Engine Execution

{
  "data": {
    "id": "task_instance_id",
    "templateId": "template_id",
    "name": "Pre-Delivery Inspection",
    "status": "PENDING",
    "autoAssigned": true
  },
  "progress": {
    "total": 3,
    "completed": 0,
    "pending": 3,
    "percentage": 0
  }
}

Successful Task Completion

{
  "data": {
    "id": "task_id",
    "status": "COMPLETED",
    "completedAt": "2025-09-14T16:30:00Z",
    "steps": [
      {
        "id": "step_1",
        "completed": true,
        "completedAt": "2025-09-14T16:25:00Z"
      }
    ]
  },
  "progress": {
    "total": 3,
    "completed": 1,
    "pending": 2,
    "percentage": 33.3
  }
}

🎯 Key Features to Verify

✅ Template Management

• List system and custom templates
• Create organization-specific templates
• Update and delete custom templates
• Filter templates by industry/category

✅ Automatic Task Assignment

• Templates auto-assign on status changes
• Rule conditions properly evaluated
• Template analytics updated
• Progress tracking works

✅ Manual Task Management

• Apply templates to legs manually
• Create custom tasks
• Complete task steps
• Update task status

✅ Mobile Integration

• Current task displays in load details
• Task checklist modal works
• Real-time progress updates
• Offline task completion

✅ Analytics and Monitoring

• Template usage analytics
• Task completion rates
• Rule engine performance logs
• Progress calculations

🆘 Get Help

If tests fail or you encounter issues:

1. Check Logs: Server console for detailed error messages
2. Verify Data: Ensure test legs and templates exist
3. Test Isolation: Run individual test functions
4. Documentation: Refer to full manual testing guide
5. Support: Contact development team with specific error messages

---

Next Steps: Once basic testing passes, proceed to the comprehensive testing guide for advanced scenarios and edge cases.