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

Test Infrastructure Complete Setup Guide

🎯 Overview

Your AgMission project now has a complete test infrastructure with:

• ✅ Mocha test framework installed
• ✅ Feature-based organization ready
• ✅ 61 test files identified and categorized
• ✅ Automated migration script to organize tests
• ✅ npm scripts for running tests by feature
• ✅ Coverage tooling configured

📊 Your Test Files (61 total)

Category	Files	Description
Promo	14	Promo codes, coupons, validation
SatLoc	13	SatLoc integration, partner sync
Job	9	Job processing, matching, verification
Parsing	7	Log parsing, data processing
Utils	9	Utilities, helpers, system functions
Payment	4	Payment processing, subscriptions
DLQ	3	Dead Letter Queue management
Integration	2	Full integration tests

🚀 Quick Start (3 Steps)

Step 1: Preview Organization

npm run organize-tests:dry-run

This shows where each file will be moved (no changes made).

Step 2: Execute Organization

npm run organize-tests

This moves all test files into feature subdirectories:

tests/
├── promo/          (14 files)
├── satloc/         (13 files)
├── job/            (9 files)
├── parsing/        (7 files)
├── utils/          (9 files)
├── payment/        (4 files)
├── dlq/            (3 files)
└── integration/    (2 files)

Step 3: Run Tests by Feature

npm run test:promo      # Run all promo tests
npm run test:satloc     # Run all SatLoc tests
npm run test:job        # Run all job tests
# etc.

📝 Available Commands

Run by Feature

npm run test:promo          # Promo/coupon tests
npm run test:satloc         # SatLoc integration
npm run test:job            # Job processing
npm run test:payment        # Payment tests
npm run test:dlq            # DLQ tests
npm run test:parsing        # Parsing tests
npm run test:integration    # Integration tests
npm run test:utils          # Utility tests

Watch Mode (auto re-run)

npm run test:promo:watch
npm run test:satloc:watch
npm run test:job:watch

Run All Tests

npm test                # All .spec.js tests
npm run test:all        # ALL test files
npm run test:coverage   # With coverage report

Run Single Test

npm run test:single tests/promo/test_promo_details.js
node tests/promo/test_promo_details.js

🔍 How Mocha Handles Failures

✅ Key Features:

1. Runs ALL tests (doesn't stop at first failure)
2. Clear failure identification:
   • Numbered list: 1), 2), 3)...
   • Full hierarchy: Suite > Subsuite > Test Name
   • Clickable line numbers to jump to code
3. Visual diff showing expected vs actual
4. Exit code indicates pass/fail (for CI/CD)

Example Output:

  Promo Tests
    ✔ should validate coupon code
    ✔ should apply discount
    1) should reject expired coupon (FAIL)

  10 passing (106ms)
  1 failing

  1) Promo Tests
       should reject expired coupon (FAIL):
      AssertionError: expected true to equal false
      + expected - actual
      -true
      +false
      at Context.<anonymous> (tests/promo/test_promo_details.js:125:25)

Click the link tests/promo/test_promo_details.js:125:25 to jump directly to the failing line!

📁 What Happens During Organization

The organize_tests.js script:

1. Analyzes each test file name
2. Categorizes by feature (promo, satloc, job, etc.)
3. Creates subdirectories
4. Moves files to appropriate subdirectory
5. Creates README.md in each subdirectory
6. Preserves original filenames (no breaking changes)

Safety Features:

• Dry-run mode (preview before moving)
• Backup option (--backup flag)
• Excludes setup files and helpers
• No code changes (just file moves)

🎨 Converting to Mocha Format (Optional)

You can gradually convert your existing test_*.js files to Mocha format:

Before (current format):

console.log('Testing feature...');
const result = doSomething();
if (result !== expected) {
  console.error('❌ FAILED');
  process.exit(1);
}
console.log('✅ PASSED');

After (Mocha format):

const { expect } = require('chai');

describe('Feature Name', () => {
  it('should do something', () => {
    const result = doSomething();
    expect(result).to.equal(expected);
  });
});

Advantages:

• Better error messages
• Automatic test discovery
• Built-in assertions with Chai
• Watch mode support
• Coverage integration

📚 Documentation

All documentation available in docs/:

• TESTING_GUIDE.md - Complete testing guide
• TEST_COMMANDS.md - Quick command reference
• TEST_ORGANIZATION.md - Organization strategies

🔄 Migration Workflow

Option A: Organize Now

# 1. Preview
npm run organize-tests:dry-run

# 2. Execute (with backup)
node tests/organize_tests.js --backup

# 3. Test it works
npm run test:promo
npm run test:satloc

# 4. Commit changes
git add tests/ package.json
git commit -m "Organize tests by feature"

Option B: Keep Current Structure

If you prefer NOT to move files, you can still:

# Run all tests
npm run test:all

# Filter by pattern
npm test -- --grep "promo"
npm test -- --grep "satloc"

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

🎯 Recommendations

1. Start with organization: Run npm run organize-tests to group by feature
2. Test by feature: Use npm run test:promo, npm run test:satloc, etc.
3. Gradually convert: Convert test_*.js to *.spec.js with Mocha format over time
4. Use watch mode: npm run test:promo:watch during development
5. Add coverage: Run npm run test:coverage before commits

⚠️ Important Notes

• No code changes needed: Organization just moves files
• Original names preserved: test_*.js names unchanged
• Environment auto-loaded: tests/setup.js handles environment.env
• Works with current tests: No conversion required to use new commands
• Gradual migration: Convert to Mocha format at your own pace

🤔 FAQ

Q: Will this break my existing test scripts? A: No! Files keep their names, just moved to subdirectories.

Q: Do I have to convert all tests to Mocha format? A: No! Both formats work. Convert gradually as needed.

Q: What if I don't want to organize? A: Keep current structure, use npm run test:all and --grep filters.

Q: How do I run just one test? A: npm run test:single tests/promo/test_promo_details.js (after organization) or node tests/test_promo_details.js (before organization)

Q: Can I undo the organization? A: Yes! Use --backup flag, or just git revert if committed.

🎉 What You Get

Before:

# Had to run each test individually
node tests/test_promo_details.js
node tests/test_satloc_parser.js
node tests/test_job_matching.js
# ... 61 files ...

After:

# Run by feature
npm run test:promo      # 14 promo tests
npm run test:satloc     # 13 SatLoc tests
npm run test:job        # 9 job tests

# Or run everything
npm test               # All tests, clear failures

🚀 Next Steps

1. ✅ Run npm run organize-tests:dry-run to preview
2. ✅ Run npm run organize-tests to organize
3. ✅ Test with npm run test:promo (or any feature)
4. ✅ Add to your workflow: npm run test:promo:watch during dev
5. ✅ Consider converting a few tests to Mocha format (see TESTING_GUIDE.md)

---

Questions? See:

• TESTING_GUIDE.md - Full testing guide
• TEST_COMMANDS.md - Command reference
• TEST_ORGANIZATION.md - Organization details