firefrost-operations-manual/docs/tasks/modpack-version-checker/TESTING-GUIDE.md

# MODPACK VERSION CHECKER - TESTING GUIDE

**Complete quality assurance procedures before launch**

---

## ⚠️ CRITICAL SAFETY RULE

**DO NOT TEST ON LIVE FIREFROST NODES (TX1 Dallas or NC1 Charlotte)**

**Why:**
- One bad database query = panel lockup
- Risk to 11 production servers
- Potential data corruption

**Solution:**
- Use $5/month test VPS with fresh Pterodactyl install
- Test on isolated environment
- Only deploy to Firefrost after complete validation

---

## 🧪 TESTING ENVIRONMENT SETUP

### Test VPS Requirements

**Minimum specs:**
- 2GB RAM
- 20GB SSD
- Ubuntu 22.04 LTS
- Fresh Pterodactyl Panel v1.11.x or v1.12.x
- Blueprint Framework (latest)
- PHP 8.1, 8.2, or 8.3

**Recommended providers:**
- Vultr ($5/month)
- Hetzner Cloud (€4/month)
- DigitalOcean ($6/month)

### Installation Steps

1. Deploy Ubuntu 22.04 VPS
2. Install Pterodactyl Panel (clean)
3. Install Blueprint Framework
4. Create 3-5 test servers with different modpacks
5. Upload sample modpack files (manifest.json, instance.json, modrinth.index.json)

---

## ✅ ESSENTIAL TEST CASES (Critical Priority)

**All must pass before BuiltByBit launch**

### Test 1: Clean Installation

**Objective:** Verify extension installs without errors

**Steps:**
1. Upload `.blueprint` file to test panel
2. Run `blueprint -install modpackmonitor.blueprint`
3. Check for any error messages
4. Verify database variables created

**Expected Result:**
- ✅ Installation completes successfully
- ✅ Success message displayed
- ✅ No errors in logs
- ✅ Database contains `MODPACK_PLATFORM` and `MODPACK_ID` variables

**Pass Criteria:**
- Zero errors during installation
- Variables exist in `egg_variables` table
- UI loads without breaking

**If Fails:**
- Check install.sh script syntax
- Verify database credentials parsed correctly
- Check MySQL permissions

---

### Test 2: CurseForge Detection

**Objective:** Verify CurseForge modpack detection works

**Steps:**
1. Create test server with CurseForge modpack
2. Upload `manifest.json` to server root
3. Load server page in panel
4. Check status badge

**Expected Result:**
- ✅ Platform detected as "curseforge"
- ✅ Project ID extracted from manifest
- ✅ Badge displays on server page
- ✅ Egg Variables populated correctly

**Sample manifest.json:**
```json
{
  "minecraft": {
    "version": "1.20.1"
  },
  "manifestType": "minecraftModpack",
  "manifestVersion": 1,
  "name": "Test Pack",
  "version": "1.0.0",
  "projectID": 123456
}
```

**Pass Criteria:**
- Auto-detection works
- Correct project ID stored
- No manual configuration needed

---

### Test 3: Modrinth Detection

**Objective:** Verify Modrinth modpack detection works

**Steps:**
1. Create test server with Modrinth modpack
2. Upload `modrinth.index.json` to server root
3. Load server page
4. Check status badge

**Expected Result:**
- ✅ Platform detected as "modrinth"
- ✅ Version ID extracted
- ✅ Badge displays correctly
- ✅ Works without API key

**Sample modrinth.index.json:**
```json
{
  "formatVersion": 1,
  "game": "minecraft",
  "versionId": "abc123xyz",
  "name": "Test Modrinth Pack"
}
```

**Pass Criteria:**
- Auto-detection works
- No API key required
- Instant functionality

---

### Test 4: FTB Detection

**Objective:** Verify FTB modpack detection works

**Steps:**
1. Create test server with FTB modpack
2. Upload `instance.json` to server root
3. Load server page
4. Check status badge

**Expected Result:**
- ✅ Platform detected as "ftb"
- ✅ Modpack ID extracted
- ✅ Professional tier feature works
- ✅ No API key required

**Sample instance.json:**
```json
{
  "modpackId": 789,
  "versionId": 1234,
  "name": "FTB Test Pack"
}
```

**Pass Criteria:**
- Auto-detection works
- Correct modpack ID stored
- Works immediately

---

### Test 5: API Timeout Handling

**Objective:** Verify graceful degradation when API is unreachable

**Steps:**
1. Block internet access temporarily on test server
2. OR use invalid API endpoint in code
3. Load server page
4. Check error handling

**Expected Result:**
- ✅ Panel doesn't crash
- ✅ Badge shows "API Offline" or similar
- ✅ Yellow/gray color (not green/red)
- ✅ User can still access panel

**Pass Criteria:**
- No white screen of death
- Clear error message to user
- Panel remains functional

**If Fails:**
- Add try/catch around all API calls
- Implement timeout handling
- Add default fallback values

---

### Test 6: Clean Uninstallation

**Objective:** Verify extension removes cleanly without breaking panel

**Steps:**
1. Run `blueprint -remove modpackmonitor`
2. Check database for leftover variables
3. Check UI for broken elements
4. Verify panel still functions

**Expected Result:**
- ✅ Database variables removed
- ✅ UI restored to original state
- ✅ No orphaned data in database
- ✅ Panel functions normally

**Pass Criteria:**
- Complete cleanup
- No broken UI elements
- No database errors

**If Fails:**
- Check remove.sh script
- Verify CASCADE foreign keys working
- Manually clean database if needed

---

## 🔄 SECONDARY TEST CASES (High Priority)

### Test 7: Force Re-scan Button

**Steps:**
1. Load server with detected modpack
2. Click "Force Re-scan" button
3. Verify re-detection occurs

**Expected:**
- Egg Variable resets to "auto"
- Fresh detection runs
- Cache updates with new result

---

### Test 8: Manual Override

**Steps:**
1. Go to server Startup tab
2. Manually set MODPACK_PLATFORM to "curseforge"
3. Manually set MODPACK_ID to "123456"
4. Load server page

**Expected:**
- Manual values used (not auto-detected)
- Badge shows manually configured platform
- Wrench icon (🔧) indicates manual config

---

### Test 9: API Key Configuration (CurseForge)

**Steps:**
1. Access admin panel
2. Navigate to extension settings
3. Add CurseForge API key
4. Test CurseForge modpack server

**Expected:**
- API key saves correctly
- CurseForge detection works
- Multiple users can use same key

---

### Test 10: Multiple Servers Performance

**Steps:**
1. Create 10 test servers with different modpacks
2. Load server list page
3. Check for performance issues
4. Monitor database query count

**Expected:**
- Page loads in <2 seconds
- Database caching prevents redundant queries
- No performance degradation

---

## 🐛 EDGE CASE TESTING

### Edge Case 1: No Manifest Files

**Scenario:** Server has no modpack manifest files

**Expected:**
- Platform detected as "unknown"
- Yellow badge: "Platform Unknown"
- Manual override option available
- No crashes

---

### Edge Case 2: Corrupted JSON

**Scenario:** manifest.json is malformed/corrupted

**Expected:**
- JSON parse error caught
- Yellow badge: "JSON Parse Error"
- Helpful error message
- Panel remains functional

---

### Edge Case 3: Multiple Platform Files

**Scenario:** Server has both manifest.json AND modrinth.index.json

**Expected:**
- Detection priority followed (FTB > Modrinth > CurseForge)
- Most recently modified file wins
- Clear indication which was detected

---

### Edge Case 4: Custom Modpack (No Public ID)

**Scenario:** Private/custom modpack with no public project ID

**Expected:**
- Auto-detection fails gracefully
- Manual override works
- User can link to public ID if desired
- Or leave as "unknown" without issues

---

## 📊 PERFORMANCE TESTING

### Load Test: 50 Servers

**Objective:** Ensure extension scales to hosting company size

**Steps:**
1. Create 50 test servers
2. Mix of CurseForge, Modrinth, FTB
3. Load server list page
4. Monitor response time and resource usage

**Acceptable Performance:**
- Page load: <3 seconds
- Memory usage: No significant increase
- Database queries: Cached (not 50 queries per page)

---

### Stress Test: API Rate Limiting

**Objective:** Verify rate limit protection works

**Steps:**
1. Configure cron job to check 100 servers simultaneously
2. Monitor API request rate
3. Check for rate limit errors

**Expected:**
- Randomized delays between requests (sleep function)
- No rate limit blocks
- Graceful handling if limits hit

---

## ✅ BETA TESTING PROGRAM

### Beta Tester Recruitment

**Target:** 3-5 experienced Pterodactyl users
**Source:** Pterodactyl Discord community
**Duration:** 1 week
**Incentive:** Free Professional tier license

### Beta Test Objectives

**Primary goals:**
1. Identify bugs in real-world environments
2. Test edge cases (weird modpack configs)
3. Validate user experience
4. Gather feature requests for v2.0

### Beta Tester Feedback Form

**Questions:**
1. How easy was installation? (1-5 scale)
2. Did auto-detection work for your modpacks? (Yes/No)
3. Did you encounter any errors? (Describe)
4. How useful is this extension? (1-5 scale)
5. What features would you want added? (Open)
6. Would you recommend to others? (Yes/No)

### Beta Test Success Criteria

**Required for launch:**
- ✅ 3+ beta testers complete testing
- ✅ No critical bugs reported
- ✅ 4+ average "usefulness" rating
- ✅ 80%+ "would recommend" rate

---

## 📝 PRE-LAUNCH FINAL CHECKLIST

**Complete before clicking "Publish" on BuiltByBit:**

### Functionality Tests
- [ ] Clean install on fresh Pterodactyl VPS
- [ ] CurseForge detection works
- [ ] Modrinth detection works
- [ ] FTB detection works
- [ ] API timeout handling (no crashes)
- [ ] Clean uninstall (restores UI)
- [ ] Force re-scan button functional
- [ ] Manual override works
- [ ] API key admin panel functional
- [ ] Multiple servers perform well

### Code Quality
- [ ] All PHP code follows PSR-12 standards
- [ ] All React components use TypeScript
- [ ] No console errors in browser
- [ ] No PHP errors in logs
- [ ] Database queries optimized

### Documentation
- [ ] README.md complete
- [ ] Installation guide written
- [ ] Troubleshooting guide written
- [ ] User documentation published
- [ ] API documentation complete

### Beta Testing
- [ ] 3-5 beta testers recruited
- [ ] 1 week testing period complete
- [ ] Feedback collected and addressed
- [ ] Critical bugs fixed
- [ ] Feature requests documented for v2.0

---

## 🚨 CRITICAL BUGS VS. MINOR BUGS

### CRITICAL (Block launch)
- Panel crashes or becomes unusable
- Database corruption
- Data loss
- Security vulnerabilities
- Installation fails on supported versions

### MINOR (Launch with known issues)
- Visual glitches (cosmetic)
- Edge case detection failures
- Slow performance on 100+ servers
- Missing features (can be v2.0)

**Document known minor issues in changelog**

---

## 📊 POST-LAUNCH MONITORING

### Week 1 Monitoring

**Monitor daily:**
- BuiltByBit reviews/ratings
- Discord support tickets
- Error reports
- Installation success rate

**Respond to:**
- All support tickets within 24 hours
- All negative reviews with solutions
- All bug reports immediately

### Month 1 Monitoring

**Track:**
- Total sales
- Average rating
- Support ticket volume
- Common issues/questions

**Actions:**
- Create FAQ from common questions
- Fix high-frequency bugs
- Plan v1.1.0 update if needed

---

## 🔧 TROUBLESHOOTING COMMON ISSUES

### Issue: "Blueprint not found"

**Cause:** User doesn't have Blueprint installed
**Solution:** Add to FAQ, require Blueprint in listing
**Prevention:** Big red warning on BuiltByBit page

---

### Issue: "Database variables not created"

**Cause:** MySQL permissions issue
**Solution:** Check user has CREATE/INSERT permissions
**Prevention:** Add permission check to install.sh

---

### Issue: "API timeout" for all servers

**Cause:** Firewall blocking outbound connections
**Solution:** Document firewall requirements
**Prevention:** Add connectivity check during install

---

### Issue: "Detection not working"

**Cause:** Modpack files in non-standard location
**Solution:** Manual override documentation
**Prevention:** Support multiple file locations in v2.0

---

## ✅ TESTING COMPLETION CRITERIA

**This testing phase is COMPLETE when:**

✅ All 10 essential test cases pass  
✅ All 4 edge cases handled gracefully  
✅ Performance tests pass (50 servers <3 sec)  
✅ Beta testing complete (3+ testers, positive feedback)  
✅ No critical bugs remain  
✅ Documentation complete  
✅ Pre-launch checklist 100% complete  

---

**Fire + Frost + Foundation = Where Testing Ensures Quality** 💙🔥❄️

**Testing guide created:** February 22, 2026  
**Created by:** The Chronicler #21  
**Purpose:** Ensure bug-free commercial launch