Skip to main content

Task System Manual Testing Guide

Overview​

This guide provides comprehensive instructions for manually testing the Task Management System. It covers automated testing scripts, API endpoint testing, mobile app testing, and database verification.

Prerequisites​

Before testing, ensure you have:

  1. Database Access: MongoDB connection with test data
  2. API Running: Backend API server running locally or on staging
  3. Authentication: Valid JWT tokens for API testing
  4. Mobile App: Development build of the mobile app
  5. Test Data: At least one leg/job in the system

Quick Start - Automated Testing​

1. Run the Automated Test Script​

The easiest way to test the entire system:

# Navigate to API directory
cd /path/to/attunelogic-api

# Run the comprehensive test script
node scripts/test-task-system.js

This script will:

  • ✅ Test template creation and retrieval
  • ✅ Test rule engine condition evaluation
  • ✅ Test automatic task assignment
  • ✅ Test task completion workflows
  • ✅ Verify analytics and progress tracking
  • ✅ Clean up test data

2. Seed System Templates​

First, populate your database with system templates:

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

Expected output:

🔗 Connecting to MongoDB...
✅ Connected to MongoDB
🌱 Seeding task templates...

📊 Seeding Summary:
   Templates created: 8
   Templates skipped: 0
   Total templates: 8

Manual API Testing​

Setup Environment​

Create a .env.test file with your test configuration:

# Test environment variables
MONGODB_URI=mongodb://localhost:27017/attunelogic-test
JWT_SECRET=your-test-jwt-secret
API_BASE_URL=http://localhost:3001/api/v1

Get Authentication Token​

First, get a valid JWT token:

# Login to get token
curl -X POST http://localhost:3001/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpassword"
  }'

Save the token for subsequent requests:

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

1. Template Management Testing​

List Available Templates​

curl -X GET "http://localhost:3001/api/v1/task-templates" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json"

Expected Response:

{
  "data": [
    {
      "_id": "template_id",
      "name": "Pre-Delivery Inspection",
      "industry": "trucking",
      "category": "safety",
      "steps": [...],
      "assignmentRules": {...},
      "analytics": {...}
    }
  ]
}

Create Custom Template​

curl -X POST "http://localhost:3001/api/v1/task-templates" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Safety Check",
    "description": "Organization-specific safety checklist",
    "industry": "trucking",
    "category": "safety",
    "steps": [
      {
        "id": "custom_step_1",
        "title": "Check custom equipment",
        "type": "checkbox",
        "required": true,
        "instructions": "Inspect organization-specific equipment"
      }
    ],
    "assignmentRules": {
      "triggers": ["status_change:loaded"],
      "conditions": {
        "loadValue": { "min": 5000 }
      }
    }
  }'

Filter Templates​

# Filter by industry
curl -X GET "http://localhost:3001/api/v1/task-templates?industry=trucking" \
  -H "Authorization: Bearer $JWT_TOKEN"

# Filter by category
curl -X GET "http://localhost:3001/api/v1/task-templates?category=safety" \
  -H "Authorization: Bearer $JWT_TOKEN"

2. Leg Task Management Testing​

Get Leg Tasks​

# Replace LEG_ID with actual leg ID
curl -X GET "http://localhost:3001/api/v1/legs/LEG_ID/tasks" \
  -H "Authorization: Bearer $JWT_TOKEN"

Get Available Templates for Leg​

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

Expected Response:

{
  "data": [
    {
      "_id": "template_id",
      "name": "High-Value Load Security",
      "conditionsMet": {
        "loadValue": true,
        "equipmentType": true,
        "existingTask": false
      },
      "wouldAutoAssign": true
    }
  ]
}

Apply Template to Leg​

curl -X POST "http://localhost:3001/api/v1/legs/LEG_ID/apply-template" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "TEMPLATE_ID"
  }'

Create Manual Task​

curl -X POST "http://localhost:3001/api/v1/legs/LEG_ID/tasks" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Manual Task",
    "description": "Manually created task for testing",
    "category": "documentation",
    "priority": "HIGH",
    "steps": [
      {
        "id": "manual_step_1",
        "title": "Complete documentation",
        "type": "text",
        "required": true,
        "instructions": "Fill out required forms"
      }
    ],
    "estimatedDuration": 15
  }'

Update Task Status​

# Complete a task
curl -X PUT "http://localhost:3001/api/v1/legs/LEG_ID/tasks/TASK_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED",
    "completionNotes": "All steps completed successfully",
    "actualDuration": 12
  }'

# Complete a task step
curl -X PUT "http://localhost:3001/api/v1/legs/LEG_ID/tasks/TASK_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "stepId": "step_id",
    "stepAction": "complete",
    "stepData": {
      "notes": "Step completed successfully"
    }
  }'

3. Rule Engine Testing​

Test Automatic Assignment​

To test the rule engine, change a leg's status and observe automatic task assignment:

# Change leg 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 output:

🔧 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

Test Rule Conditions​

Create a leg with specific characteristics to test rule conditions:

# Update leg with high value to trigger high-value templates
curl -X PUT "http://localhost:3001/api/v1/legs/LEG_ID" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 15000,
    "equipment": {
      "type": "dry_van"
    },
    "loadType": "general"
  }'

4. Analytics Testing​

Get Template Analytics​

curl -X GET "http://localhost:3001/api/v1/task-templates/analytics?timeframe=30d" \
  -H "Authorization: Bearer $JWT_TOKEN"

Expected Response:

{
  "data": [
    {
      "_id": "template_id",
      "name": "Pre-Delivery Inspection",
      "analytics": {
        "totalAssignments": 45,
        "totalCompletions": 42,
        "averageDuration": 12,
        "completionRate": 93.3
      },
      "usage": {
        "totalUsage": 45,
        "completedTasks": 42,
        "avgDuration": 12.5
      }
    }
  ]
}

Mobile App Testing​

1. Task Display Testing​

Load Details Screen​

  1. Navigate to any load in the mobile app
  2. Verify the "Load Status Card" displays:
    • Load information (status, type, etc.)
    • Current task section with:
      • Task name and status
      • Progress indicator
      • Completion percentage
      • Clickable area

Expected UI Behavior:​

  • ✅ Current task shows status-based styling (blue for in-progress, green for completed)
  • ✅ Progress displays as "X of Y tasks completed (Z%)"
  • ✅ Tapping current task navigates to task checklist
  • ✅ Shows "No active tasks" when no tasks assigned

2. Task Checklist Testing​

Access Task Checklist​

  1. Tap on current task in load details
  2. Verify modal opens with:
    • Header showing overall progress
    • Progress bar
    • List of all tasks for the load

Task Interaction Testing​

  1. Tap on individual tasks to expand/collapse
  2. Complete task steps by tapping checkboxes
  3. Verify real-time progress updates
  4. Test different step types:
    • ✅ Checkbox steps
    • 📷 Photo steps (placeholder)
    • ✍️ Signature steps (placeholder)
    • 📝 Text steps (placeholder)

Task Status Changes​

  1. Complete all steps in a task
  2. Verify task status changes to "COMPLETED"
  3. Test skip functionality:
    • Tap "Skip" button
    • Enter skip reason
    • Verify approval workflow (if applicable)

3. Offline Testing​

Offline Task Completion​

  1. Disable device internet connection
  2. Complete task steps
  3. Verify optimistic UI updates
  4. Re-enable internet
  5. Verify changes sync to backend

4. Real-time Updates Testing​

Multi-device Testing​

  1. Open same load on multiple devices/browsers
  2. Complete tasks on one device
  3. Verify other devices update automatically
  4. Test RTK Query cache invalidation

Database Verification​

1. Verify Task Data Structure​

Connect to MongoDB and inspect the data:

// MongoDB Shell Commands

// Check leg with tasks
db.legs.findOne(
  { "tasks.0": { $exists: true } },
  { loadNumber: 1, tasks: 1, taskProgress: 1 }
);

// Check template usage analytics
db.tasktemplates.find(
  { "analytics.totalAssignments": { $gt: 0 } },
  { name: 1, analytics: 1 }
);

// Verify task progress calculation
db.legs.aggregate([
  { $match: { "tasks.0": { $exists: true } } },
  {
    $project: {
      loadNumber: 1,
      totalTasks: { $size: "$tasks" },
      completedTasks: {
        $size: {
          $filter: {
            input: "$tasks",
            cond: { $eq: ["$$this.status", "COMPLETED"] },
          },
        },
      },
      taskProgress: 1,
    },
  },
]);

2. Verify Rule Engine Results​

Check that templates are being assigned correctly:

// Find auto-assigned tasks
db.legs.find(
  { "tasks.autoAssigned": true },
  { loadNumber: 1, "tasks.name": 1, "tasks.autoAssigned": 1 }
);

// Check template assignment patterns
db.legs.aggregate([
  { $unwind: "$tasks" },
  { $match: { "tasks.templateId": { $exists: true } } },
  {
    $group: {
      _id: "$tasks.templateId",
      count: { $sum: 1 },
      autoAssigned: { $sum: { $cond: ["$tasks.autoAssigned", 1, 0] } },
    },
  },
  {
    $lookup: {
      from: "tasktemplates",
      localField: "_id",
      foreignField: "_id",
      as: "template",
    },
  },
]);

Performance Testing​

1. Load Testing​

Use the provided test script to create multiple tasks:

# Run load test with multiple iterations
for i in {1..10}; do
  echo "Running test iteration $i"
  node scripts/test-task-system.js
done

2. Database Query Performance​

Test query performance with larger datasets:

// Test template lookup performance
db.tasktemplates
  .find({
    $or: [
      { organizationId: ObjectId("your-org-id") },
      { organizationId: null },
    ],
    isActive: true,
  })
  .explain("executionStats");

// Test task aggregation performance
db.legs
  .aggregate([
    { $unwind: "$tasks" },
    {
      $group: {
        _id: "$tasks.status",
        count: { $sum: 1 },
      },
    },
  ])
  .explain("executionStats");

Troubleshooting Common Issues​

1. Templates Not Appearing​

Issue: Templates don't show in available templates Check:

  • Template isActive: true
  • Template organizationId matches or is null
  • Assignment conditions are met
  • No existing task from same template

2. Rule Engine Not Triggering​

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

  • Template has correct trigger (status_change:new_status)
  • Assignment conditions are met
  • Server logs for rule engine output
  • Rule engine integration in setLegStatus function

3. Task Progress Not Updating​

Issue: Task progress percentage not calculating correctly Check:

  • leg.updateTaskProgress() is called after task changes
  • Task status values are correct
  • Step completion status is properly set

4. Mobile App Not Syncing​

Issue: Mobile app doesn't reflect backend changes Check:

  • RTK Query cache invalidation tags
  • Network connectivity
  • Authentication token validity
  • API response format matches expected structure

Test Data Cleanup​

After testing, clean up test data:

# Remove test templates (manual cleanup)
node -e "
const mongoose = require('mongoose');
const { TaskTemplate } = require('./src/models/Task');
require('dotenv').config();

mongoose.connect(process.env.MONGODB_URI).then(async () => {
  await TaskTemplate.deleteMany({ name: /Manual Test/ });
  console.log('Test templates cleaned up');
  process.exit(0);
});
"

# Or use MongoDB shell
mongo your-database-name --eval "
db.tasktemplates.deleteMany({ name: /Manual Test/ });
db.legs.updateMany(
  {},
  { \$pull: { tasks: { name: /Manual Test/ } } }
);
"

Continuous Testing​

1. Integration with Development Workflow​

Add testing to your development process:

# Add to package.json scripts
{
  "scripts": {
    "test:tasks": "node scripts/test-task-system.js",
    "test:seed": "node scripts/seed-templates.js",
    "test:manual": "echo 'Run manual tests from docs/testing/manual-testing-guide.md'"
  }
}

2. Automated Testing Schedule​

Set up regular testing:

# Create a cron job for daily testing
0 2 * * * cd /path/to/attunelogic-api && npm run test:tasks >> /var/log/task-tests.log 2>&1

This comprehensive testing guide ensures the Task Management System works correctly across all components and scenarios. Follow these procedures regularly to maintain system reliability and catch issues early.