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:

```bash

# 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)

```bash

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)

```bash

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):**
```bash

# 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)
   ```json

   {

     "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!** 🚀