TEST_GUIDE.md

Testing Guide for Level Generator Application

This guide helps you test the application to ensure everything is working correctly.

Pre-Testing Checklist

✅ Dependencies Installed

pip install -r backend/requirements.txt

✅ Google API Key Set

# Windows CMD
set GOOGLE_API_KEY=your_actual_api_key_here

# Windows PowerShell
$env:GOOGLE_API_KEY="your_actual_api_key_here"

# macOS/Linux
export GOOGLE_API_KEY="your_actual_api_key_here"

Test 1: Verify Dependencies

Run this command to check if all dependencies are installed:

pip list | findstr "flask requests google-generativeai"

Expected output should show:

• flask (version 3.0.0 or higher)
• flask-cors (version 4.0.0 or higher)
• requests (version 2.31.0 or higher)
• google-generativeai (version 0.3.2 or higher)

Test 2: Backend API Health Check

1. Start the backend server:

   python backend/app.py

2. Expected console output:

   * Running on http://127.0.0.1:5000
   * Debug mode: on
   

3. Test the health endpoint:

   Open a new terminal and run:

   curl http://localhost:5000/api/health

   Or open in browser: http://localhost:5000/api/health

   Expected response:

   {
     "status": "ok",
     "message": "Level Generator API is running"
   }

Test 3: Frontend Interface

1. Keep backend running (from Test 2)

2. Open frontend:

   • Navigate to the frontend folder
   • Double-click index.html OR
   • Open with browser OR
   • Use local server:

     cd frontend
     python -m http.server 8000
     # Then visit http://localhost:8000

3. Visual checks:

   • ✅ Page loads without errors
   • ✅ Header displays "🎓 Level Generator"
   • ✅ One level input form is visible
   • ✅ "Add Level" button is present
   • ✅ "Generate New Level" and "Clear All" buttons are visible
   • ✅ Styling looks correct (gradient header, clean layout)

Test 4: Add/Remove Levels Functionality

1. Click "Add Level" button

   • ✅ New level form appears
   • ✅ Level number increments (Example Level 2, 3, etc.)
   • ✅ Each has name input and type dropdown

2. Click "Remove" on a level

   • ✅ Level is removed
   • ✅ At least one level always remains

3. Click "Clear All"

   • ✅ All levels are removed
   • ✅ One new empty level appears

Test 5: Form Validation

1. Try to generate without entering any level name:

   • ✅ Error message appears: "Please fill in all level names"
   • ✅ Focus moves to empty input

2. Enter invalid characters in level name:

   • This should be accepted (API will validate)

Test 6: Full Generation Test (Requires API Key)

1. Add test levels:

   Level 1:

   • Name: programming-fundamentals-lesson6-level1_2025-launch_2025
   • Type: Level

   Level 2:

   • Name: programming-fundamentals-lesson6-level2_2025-launch_2025
   • Type: Level

2. Click "Generate New Level"

3. Expected behavior:

   • ✅ Loading spinner appears
   • ✅ Button is disabled during generation
   • ✅ Console shows "Fetching data..." messages (check backend terminal)
   • ✅ Wait 10-30 seconds for generation

4. Expected results:

   • ✅ Output section appears below
   • ✅ Info shows "Generated using 2 example levels"
   • ✅ Instructions box contains markdown text
   • ✅ Starter code box contains Python code
   • ✅ Both boxes have scrollbars if content is long

5. Test copy functionality:

   • ✅ Click "Copy" button on instructions
   • ✅ Button shows "Copied!" briefly
   • ✅ Paste into text editor - content should match
   • ✅ Repeat for starter code

Test 7: Bubble Choice Level Test

1. Clear all levels

2. Add a bubble choice level:

   • Name: programming-fundamentals-lesson4-level3_2025-launch_2025
   • Type: Bubble Choice

3. Generate

4. Expected behavior:

   • ✅ Backend console shows multiple sub-levels being fetched
   • ✅ Results include examples from all sub-levels

Test 8: Error Handling

1. Test with invalid level name:

   • Name: invalid-level-name-that-does-not-exist
   • Type: Level
   • ✅ Error message appears (level not found)

2. Test with backend offline:

   • Stop backend server
   • Try to generate
   • ✅ Error message about connection failure

3. Test with missing API key:

   • Remove GOOGLE_API_KEY environment variable
   • Restart backend
   • ✅ Backend shows error and exits

Test 9: Cross-Browser Testing

Test in multiple browsers:

• ✅ Chrome/Edge
• ✅ Firefox
• ✅ Safari (macOS)

All features should work identically.

Test 10: Responsive Design

1. Resize browser window to mobile size (< 768px)
   • ✅ Layout adapts to narrow screen
   • ✅ Buttons stack vertically
   • ✅ All functionality still works

Common Issues and Solutions

Issue: "CORS error" in browser console

Solution:

• Ensure backend is running on port 5000
• Try using a local server for frontend instead of opening HTML directly

Issue: "Failed to fetch" error

Solution:

• Verify backend is running
• Check that API URL in frontend/app.js matches backend port
• Check firewall settings

Issue: "API key not set" error

Solution:

• Set GOOGLE_API_KEY environment variable
• Restart backend after setting the variable

Issue: Generation takes too long

Solution:

• This is normal for Gemini API (10-30 seconds)
• Check your internet connection
• Reduce number of example levels if needed

Success Criteria

All tests pass when:

• ✅ Backend starts without errors (with API key set)
• ✅ Frontend loads and displays correctly
• ✅ Level management (add/remove) works smoothly
• ✅ Form validation catches empty inputs
• ✅ Full generation cycle completes successfully
• ✅ Copy functionality works for both outputs
• ✅ Error handling works for invalid inputs
• ✅ Application works across different browsers

Performance Benchmarks

Expected timings:

• Backend startup: < 1 second
• Frontend load: < 1 second
• Single level fetch: 1-3 seconds
• Gemini API generation: 10-30 seconds
• Total generation (3 levels): 15-40 seconds

Notes

• The application preserves all original level_generator.py functionality
• Level names must exactly match Code.org repository entries
• Bubble choice levels automatically expand to include sub-levels
• The frontend is purely client-side (no server needed except for API calls)