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:
```bash
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:

```bash
# 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):

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

```bash
# 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:

```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:
```bash
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