agmission/Development/server/docs/archived/TEST_ORGANIZATION.md

Test Organization Strategy

Current Situation

You have 64+ test files in tests/ directory with these feature categories:

Feature Categories Identified:

1. Promo/Coupon (17 files)

• test_promo_details.js
• test_promo_enhancements.js
• test_promo_expired_email.js
• test_promo_expiry_workflow.js
• test_promo_priority_selection.js
• test_promo_selection_simple.js
• test_promo_usage_count.js
• test_active_promos_eligibility.js
• test_active_promos_endpoint.js
• test_coupon_endpoint.js
• test_coupon_resolution.js
• test_duplicate_promo_validation.js
• test_forever_coupon_validation.js
• test_trigger_promo_webhook.js

2. SatLoc/Partner Integration (15 files)

• test_satloc_all_endpoints.js
• test_satloc_application_processor.js
• test_satloc_auth.js
• test_satloc_error_responses.js
• test_satloc_errors_simple.js
• test_satloc_job_creation.js
• test_satloc_log_parser.js
• test_satloc_parser.js
• test_satloc_pattern.js
• test_satloc_pattern_brief.js
• test_read_satloc_log.js
• test_partner_sync_integration.js
• test_partner_upload_atomic.js

3. Job Processing (9 files)

• test_job_fallback_logic.js
• test_job_id_priority.js
• test_job_matching.js
• test_job_model.js
• test_job_verification_workflow.js
• test_job_worker_tasktracker.js
• test_enhanced_job_matching.js
• test_atomic_upload.js
• test_filename_job_extraction.js

4. Payment/Subscription (3 files)

• test_payment_failure_handling.js
• test_payment_verification_fix.js
• test_setup_intent.js
• test_multi_subscription_auth.js

5. DLQ (3 files)

• test_dlq_messages_direct.js
• test_dlq_mgmt_api.js
• test_dlq_routes.js

6. Parsing/Log Processing (7 files)

• test_parsing_logic.js
• test_corrected_parsing.js
• test_app_processor.js
• test_updated_parser.js
• test_updated_processor.js
• test_null_termination.js
• test_timestamp_rollover.js

7. Integration Tests (3 files)

• test_integration.js
• test_phase2_integration.js
• test_partner_sync_integration.js

8. Utilities/Other (7 files)

• test_fatal_error_reporter.js
• test_system_types.js
• test_utm_zone.js
• test_distance_accuracy.js
• test_metadata_storage.js
• test_task_tracker_2key.js
• test_filename_patterns.js

Recommended Organization

Option 1: Subdirectories (Comprehensive)

tests/
├── setup.js
├── run_all_tests.js
├── promo/
│   ├── test_promo_details.js
│   ├── test_coupon_endpoint.js
│   └── ...
├── satloc/
│   ├── test_satloc_parser.js
│   ├── test_partner_sync_integration.js
│   └── ...
├── job/
│   ├── test_job_matching.js
│   ├── test_job_worker_tasktracker.js
│   └── ...
├── payment/
│   ├── test_payment_failure_handling.js
│   └── ...
├── dlq/
│   ├── test_dlq_mgmt_api.js
│   └── ...
├── parsing/
│   ├── test_parsing_logic.js
│   └── ...
├── integration/
│   ├── test_integration.js
│   └── ...
└── utils/
    ├── test_fatal_error_reporter.js
    └── ...

Option 2: Naming Convention (Simpler - No File Moving)

Keep all files in tests/ but use consistent prefixes:

• promo.*.spec.js or test_promo_*.js
• satloc.*.spec.js or test_satloc_*.js
• job.*.spec.js or test_job_*.js

Then run by pattern:

npm test -- --grep "promo"
npm run test:all -- tests/test_promo_*.js

Option 3: Hybrid (Recommended)

Move to subdirectories but keep legacy test_*.js naming:

tests/
├── setup.js
├── promo/
│   ├── test_promo_details.js         # Keep existing names
│   ├── coupon_validation.spec.js     # New Mocha tests
│   └── ...
├── satloc/
│   ├── test_satloc_parser.js
│   ├── parser_integration.spec.js
│   └── ...

Benefits:

• ✅ Organized by feature
• ✅ No breaking changes (files keep original names)
• ✅ Can gradually convert to .spec.js
• ✅ Run by category or individually

Running Tests by Feature

With Subdirectories:

# Run all promo tests
npm run test:all -- tests/promo/**/*.js
npm test -- tests/promo/**/*.spec.js

# Run specific category
npm test -- tests/satloc/**/*.spec.js
npm test -- tests/job/**/*.spec.js
npm test -- tests/payment/**/*.spec.js

# Run all integration tests
npm test -- tests/integration/**/*.spec.js

# Run single test
npm run test:single tests/promo/test_promo_details.js

With Mocha's --grep (filter by test name):

// In your test files, use descriptive suite names:
describe('Promo: Coupon Validation', () => { ... });
describe('SatLoc: Log Parser', () => { ... });
describe('Job: Matching Logic', () => { ... });

# Run all tests with "Promo" in the name
npm test -- --grep "Promo"

# Run all SatLoc tests
npm test -- --grep "SatLoc"

# Run specific feature
npm test -- --grep "Coupon Validation"

# Exclude tests
npm test -- --grep "Promo" --invert

Package.json Scripts (Feature-based)

Add these to package.json:

{
  "scripts": {
    "test": "mocha --recursive --exit --require tests/setup.js 'tests/**/*.spec.js'",
    "test:all": "mocha --recursive --exit --require tests/setup.js 'tests/**/*.js'",
    
    "test:promo": "mocha --exit --require tests/setup.js 'tests/promo/**/*.js'",
    "test:satloc": "mocha --exit --require tests/setup.js 'tests/satloc/**/*.js'",
    "test:job": "mocha --exit --require tests/setup.js 'tests/job/**/*.js'",
    "test:payment": "mocha --exit --require tests/setup.js 'tests/payment/**/*.js'",
    "test:dlq": "mocha --exit --require tests/setup.js 'tests/dlq/**/*.js'",
    "test:integration": "mocha --exit --require tests/setup.js 'tests/integration/**/*.js'",
    
    "test:promo:watch": "mocha --watch --require tests/setup.js 'tests/promo/**/*.js'",
    "test:satloc:watch": "mocha --watch --require tests/setup.js 'tests/satloc/**/*.js'"
  }
}

Usage:

npm run test:promo      # All promo tests
npm run test:satloc     # All SatLoc tests
npm run test:job        # All job tests
npm run test:integration # Integration tests only

Migration Script (Optional)

I can create a script to automatically organize your tests:

• Analyzes each file
• Moves to appropriate subdirectory
• Updates any relative imports
• Creates backup before moving

Would you like me to create this?

Recommendation

Start with Option 3 (Hybrid):

1. Create subdirectories
2. Move existing files (keeping their names)
3. Add feature-specific npm scripts
4. Gradually convert to .spec.js as you update tests

This approach:

• ✅ Doesn't break existing scripts
• ✅ Organizes by feature immediately
• ✅ Allows running tests by category
• ✅ Supports gradual migration to Mocha format