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:

{
  "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:

{
  "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:

{
  "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