TESTING_GUIDE.md

🧪 Complete Testing Guide - Step by Step

Overview

Your system has two parts:

1. Python Backend (FastAPI) - Analyzes PowerPoints and generates alt text
2. Angular Frontend (Web UI) - Upload interface for users

✅ Prerequisites Check

Before starting, verify everything is installed:

# Backend packages installed?
cd "Cycle 2 Testing/Accessibility-Checker-BE/python-server"
python -c "import fastapi; import transformers; print('✅ Backend ready')"

# Frontend dependencies installed?
cd "Cycle 2 Testing/Accessibility-Checker"
npm list angular 2>/dev/null | head -3

---

🚀 Step 1: Start the Python Backend

Open Terminal 1 (Backend)

cd "e:\Local Senior Project\Cycle 2 Testing\Accessibility-Checker-BE\python-server"
python server2.py

Expected Output

✅ Local AI vision model loaded (BLIP - 100% FREE, No Costs)
📚 Loading ISO schema validation...
🚀 Uvicorn running on http://127.0.0.1:5000

First run will download BLIP model (~1-2GB, takes 5-15 minutes)

Wait for this line before proceeding:

Application startup complete

---

🚀 Step 2: Start the Angular Frontend

Open Terminal 2 (Frontend)

cd "e:\Local Senior Project\Cycle 2 Testing\Accessibility-Checker"
npm start

Expected Output

✔ Compiled successfully
ℹ Application bundle generation complete
    Initial Chunk Files   | Names         | Raw Size
    vendor.js             |               | 2.5 MB | 
    main.js               |               | 250 KB |
    ...
✔ Build at: YYYY-MM-DD HH:MM:SS
✔ Serving from: .\
Application bundle generation complete

Open in Browser

Once you see "Compiled successfully", open:

http://localhost:4200

You should see the Accessibility Checker web interface.

---

📄 Step 3: Create or Get a Test PowerPoint

Option A: Use Existing PowerPoint

• Look in: Cycle 2 Testing\Accessibility-Checker-BE\test-docs\
• Should contain sample PowerPoint files

Option B: Create Simple Test PowerPoint

For Windows (using PowerPoint):

1. Open PowerPoint
2. Create a new presentation
3. Add a slide with:
   • A title (e.g., "Test Slide")
   • An image (any image)
   • Leave the image WITHOUT alt text (that's what we're testing)
4. Save as: test-presentation.pptx
5. Save to a convenient location (e.g., Desktop)

For Windows (using LibreOffice):

# Install LibreOffice if needed
# Create presentation with libreoffice

No PowerPoint installed? Download a sample file from Microsoft Office templates or use the test files that might already exist.

---

📤 Step 4: Upload PowerPoint to System

In the Web Browser (localhost:4200)

1. Look for "Upload" button

   • Should be prominent on the page
   • Usually labeled: "Upload PowerPoint" or "Choose File"

2. Click and select your PowerPoint file

   • Navigate to your test-presentation.pptx
   • Select it and upload

3. Watch the Backend Console

   • You should see activity:

   🔧 Starting alt text remediation for: test-presentation.pptx
      AI Mode: LOCAL (100% FREE - No Costs)
   🤖 Using FREE local AI (BLIP) for slide 1
     ✅ AI generated alt text for Picture 1: 'A colorful chart showing...'
   ✅ Remediation complete: 1 images processed
      🤖 1 alt texts generated by FREE local AI (no cost)
   

---

📊 Step 5: View Results

In Web Browser

After upload completes, you should see:

1. Accessibility Report

   • Summary of issues found
   • Number of images without alt text
   • List of missing/bad alt text descriptions

2. Sample Report Output

   FILE ANALYSIS RESULTS
   ━━━━━━━━━━━━━━━━━━━━━━━━━
   
   ✅ Issues Fixed: 1
   ⚠️  Issues Flagged: 0
   
   Image Alt Text Status:
   • Slide 1 - Picture 1: "Bar chart with increasing values"
   

3. Response JSON (in browser console)

   {
     "fileName": "test-presentation.pptx",
     "suggestedFileName": "remediated-test-presentation.pptx",
     "report": {
       "summary": { "fixed": 1, "flagged": 0 },
       "details": {
         "imagesMissingOrBadAlt": []
       }
     }
   }
   

---

💾 Step 6: Download Remediated File

In Web Browser

1. Look for "Download" button

   • Usually appears after upload
   • Text might be: "Download Remediated PowerPoint" or "Download Fixed File"

2. Click to download

   • File will save locally as: remediated-test-presentation.pptx

3. Open downloaded file in PowerPoint

   Right-click image → Properties → Alt Text
   

4. Verify alt text was added

   • Should see the AI-generated description
   • Example: "Bar chart with increasing values"

---

✅ Verification Checklist

After completing all steps, check:

Backend Console Should Show

• ✅ ✅ Local AI vision model loaded
• ✅ 🤖 Using FREE local AI (BLIP) for slide X
• ✅ ✅ AI generated alt text for Picture X
• ✅ ✅ Remediation complete: X images processed
• ✅ 🤖 X alt texts generated by FREE local AI

Downloaded File Should Have

• ✅ Original PowerPoint content preserved
• ✅ New alt text on all previously missing images
• ✅ Alt text is descriptive (not just "image" or "picture")
• ✅ File can be opened normally in PowerPoint

Cost Should Be

• ✅ $0.00 - No API charges
• ✅ No internet calls after first model download
• ✅ Everything local and private

---

🐛 Troubleshooting

"Server not responding" / "Cannot connect to localhost:5000"

Solution:

1. Check Terminal 1 - is backend still running?
2. Look for errors in backend output
3. Restart backend: Ctrl+C then python server2.py
4. Wait for "Application startup complete"

"Frontend not loading" / "Cannot access localhost:4200"

Solution:

1. Check Terminal 2 - is frontend still running?
2. Open http://localhost:4200 in browser
3. Check browser console for errors (F12)
4. Restart frontend: Ctrl+C then npm start

"Model downloading..." for more than 20 minutes

This is normal for first run! Downloading 1-2GB takes time.

✔ First run: 5-15 minutes (downloading BLIP model)
✔ Subsequent runs: Instant (model cached)

"AI not generating alt text" / Empty descriptions

Check:

1. Are images in PowerPoint actually visible?
2. Are images in supported formats (PNG, JPG)?
3. Try python test_ai_setup.py to verify AI works
4. Check backend console for error messages

"Upload button doesn't appear"

Solution:

1. Check if frontend has compiled (look for "Compiled successfully")
2. Hard refresh browser: Ctrl+Shift+R
3. Open browser DevTools: F12 → Console
4. Look for JavaScript errors

"Downloaded file won't open"

Solution:

1. Check file size - should be similar to original
2. Try opening with different PowerPoint version
3. Check if file is corrupted - reupload
4. Look at backend logs for errors

---

📊 What to Expect: Real Example

Input PowerPoint

• 3 slides
• 5 images total
• 0 images have alt text

System Processing

🔧 Starting alt text remediation for: sample.pptx
   AI Mode: LOCAL (100% FREE - No Costs)
🤖 Using FREE local AI (BLIP) for slide 1
  ✅ AI generated alt text for Picture 1: 'Professional man in business suit'
  ✅ AI generated alt text for Picture 2: 'Bar graph with red and blue columns'
🤖 Using FREE local AI (BLIP) for slide 2
  ✅ AI generated alt text for Picture 3: 'Team meeting in conference room'
  ✅ AI generated alt text for Picture 4: 'Laptop displaying code editor'
🤖 Using FREE local AI (BLIP) for slide 3
  ✅ AI generated alt text for Picture 5: 'Company logo on blue background'
✅ Remediation complete: 5 images processed
   🤖 5 alt texts generated by FREE local AI (no cost)

Output PowerPoint

• Same 3 slides, all images
• All 5 images now have descriptive alt text
• File works exactly like original
• Cost: $0.00 🎉

---

🎯 Testing Scenarios

Test 1: Basic Image (Easy)

1. PowerPoint with 1 simple image
2. Expected: Describe what's in image
3. Example: "Logo design with blue colors"

Test 2: Multiple Images (Medium)

1. PowerPoint with 3-5 images on different slides
2. Expected: Each gets unique description
3. Verify: All descriptions are different

Test 3: Complex Presentation (Advanced)

1. Real presentation with charts, photos, logos
2. Expected: All get meaningful descriptions
3. Verify: Chart descriptions mention data/trends

---

📱 What The System Actually Does

Internally

1. Receives PowerPoint → Unzips to XML
2. Finds images → Extracts from ZIP
3. Analyzes images → Uses local BLIP AI model
4. Generates descriptions → Creates alt text
5. Updates XML → Adds alt text to image properties
6. Repackages → Zips back into PowerPoint
7. Delivers file → User downloads fixed PowerPoint

Data Flow

User PowerPoint
    ↓
Backend receives file
    ↓
Extract images from PowerPoint ZIP
    ↓
Send to LOCAL BLIP AI (runs on your computer)
    ↓
AI analyzes images
    ↓
AI generates descriptions
    ↓
Insert descriptions into PowerPoint XML
    ↓
Package back into PowerPoint file
    ↓
User downloads remediated file

Key Point: Everything runs locally - images never sent to internet!

---

💡 Tips for Best Results

1. Use clear, simple images - More likely to get good descriptions
2. Include variety - Test with photos, charts, logos
3. Check backend console - Understand what AI is doing
4. Read descriptions carefully - Verify they're accurate
5. Edit if needed - AI descriptions are starting point, not final

---

🚀 Next Steps After Testing

Once you verify everything works:

1. Test with real presentations from your team
2. Collect feedback - Is AI quality good enough?
3. Adjust if needed - Can tweak model in .env
4. Deploy - Set up on server for team to use
5. Monitor costs - Should always be $0 (local AI)

---

📞 Still Having Issues?

Check these in order:

1. Backend running? Terminal 1 shows "Application startup complete"
2. Frontend running? Terminal 2 shows "Compiled successfully"
3. Both on correct ports? Backend: 5000, Frontend: 4200
4. Firewall blocking? Windows Firewall might block local connections
5. AI downloaded? First run takes 5-15 min for BLIP model

If still stuck, check the console output - that's where errors appear!

---

🎉 Success Criteria

✅ Backend starts without errors
✅ Frontend loads in browser
✅ Can upload PowerPoint file
✅ System processes file (backend shows activity)
✅ Can download remediated file
✅ Downloaded file has alt text
✅ Alt text is descriptive (not generic)
✅ Cost is $0.00 (local AI only)

If all boxes checked → Your system works! 🚀