TESTING.md

# Testing Guide 🧪

Complete guide to test all features of the Graph RAG Chatbot.

## Prerequisites

- Application running (local or Docker)
- Groq API Key configured
- Test documents prepared

## Test Documents

### 1. Sample CSV (test_data.csv)

Create this file for testing:

```csv
Name,Role,Department,Salary
Alice Johnson,Senior Engineer,Engineering,120000
Bob Smith,Product Manager,Product,110000
Carol White,Designer,Design,100000
David Lee,Engineer,Engineering,95000
Emma Davis,Analyst,Data,90000
```

**Save as**: `test_data.csv`

### 2. Sample PDF

Use any PDF document about:
- Technology
- Business
- Science
- General knowledge

**Recommended**: Download a sample PDF from https://www.w3.org/WAI/test-evaluate/

### 3. Sample TXT

Create `sample.txt` with text like:

```
Natural Language Processing (NLP) is a subfield of linguistics, 
computer science, and artificial intelligence concerned with the 
interactions between computers and human language.

Machine learning is a method of data analysis that automates analytical 
model building. It is a branch of artificial intelligence based on the 
idea that systems can learn from data.

Graph databases are specialized databases designed to store and retrieve 
relational data. They are particularly useful for managing large, 
interconnected datasets where relationships are as important as the data itself.
```

**Save as**: `sample.txt`

## Test Cases

### Test 1: Upload Single Document

**Objective**: Verify basic file upload functionality

**Steps**:
1. Navigate to "📤 Upload Documents" section
2. Click on upload zone or drag `test_data.csv`
3. Observe the file appears in "Uploaded Documents"
4. Status should change: queued → processing → ready

**Expected Results**:
- ✅ File appears immediately
- ✅ Progress bar fills to 100%
- ✅ Status changes to "ready"
- ✅ Shows chunk count (e.g., "~1 chunks")
- ✅ Shows entity count (e.g., "~12 entities")
- ✅ "View Full Graph" link appears

**Time**: ~3-5 seconds

---

### Test 2: Upload Multiple Documents

**Objective**: Test concurrent document processing

**Steps**:
1. Prepare 3 test files: `test_data.csv`, `sample.txt`, and a PDF
2. Click upload zone
3. Select all 3 files at once
4. Hold Ctrl/Cmd and select all files

**Expected Results**:
- ✅ All 3 files queued simultaneously
- ✅ Each processes independently
- ✅ UI remains responsive
- ✅ All reach "ready" status

**Time**: ~10-15 seconds total

---

### Test 3: View Knowledge Graph

**Objective**: Verify graph visualization

**Steps**:
1. Ensure a document has "ready" status
2. Click "📈 View Full Graph" link
3. Switch to "Knowledge Graph" tab
4. Select document from dropdown

**Expected Results**:
- ✅ Image loads without errors
- ✅ Graph shows nodes (blue = chunks, green = entities)
- ✅ Edges show relationships
- ✅ Layout is readable and clear

**Image Properties**:
- Resolution: 150 DPI
- Format: PNG
- Size: 800x600px (approximately)

---

### Test 4: Simple Query

**Objective**: Test RAG functionality with CSV data

**Steps**:
1. Upload `test_data.csv`
2. Wait for "ready" status
3. In chat section:
   - Select document from dropdown
   - Type query: "Who is the senior engineer?"
   - Click "Send"

**Expected Results**:
- ✅ Chat message appears
- ✅ Loading indicator shows
- ✅ Bot responds with answer
- ✅ Response references Alice Johnson
- ✅ Response appears in 2-5 seconds

**Example Expected Answer**:
```
Based on the provided data, Alice Johnson is the Senior Engineer 
in the Engineering Department with a salary of $120,000.
```

---

### Test 5: Knowledge-based Query

**Objective**: Test with text document

**Steps**:
1. Upload `sample.txt` (NLP/ML content)
2. Wait for "ready" status
3. Query: "What is machine learning?"

**Expected Results**:
- ✅ Bot provides accurate explanation
- ✅ Answer comes from the document context
- ✅ Response is relevant and coherent

**Example Expected Answer**:
```
Machine learning is a method of data analysis that automates 
analytical model building. It is a branch of artificial 
intelligence based on the idea that systems can learn from data.
```

---

### Test 6: Multi-chunk Context

**Objective**: Test queries that require context from multiple chunks

**Steps**:
1. Upload `sample.txt`
2. Query: "What are the relationships between NLP, machine learning, and graph databases?"

**Expected Results**:
- ✅ Answer synthesizes information across multiple chunks
- ✅ Shows understanding of relationships
- ✅ Confidence score is shown

---

### Test 7: Out-of-context Query

**Objective**: Test handling of irrelevant queries

**Steps**:
1. Upload `test_data.csv` (employee data)
2. Query: "What is quantum physics?"

**Expected Results**:
- ✅ Bot responds: "No relevant information found in the document"
- ✅ No incorrect information is generated
- ✅ Error is handled gracefully

---

### Test 8: Document Deletion

**Objective**: Verify document removal

**Steps**:
1. Upload `test_data.csv`
2. Wait for "ready" status
3. Click "Delete" button
4. Confirm deletion

**Expected Results**:
- ✅ Document disappears from list
- ✅ Graph image is removed
- ✅ Cannot query deleted document
- ✅ Dropdown option removed

---

### Test 9: Error Handling - Invalid File

**Objective**: Test upload of unsupported format

**Steps**:
1. Try to upload file with unsupported extension (.exe, .jpg, etc.)
2. Observe UI response

**Expected Results**:
- ✅ File is accepted (upload endpoint)
- ✅ Processing fails with meaningful error
- ✅ Status shows "error"
- ✅ Error message visible: "Unsupported file type"

---

### Test 10: Error Handling - Large File

**Objective**: Test max file size limit

**Steps**:
1. Create a file > 50MB
2. Try to upload

**Expected Results**:
- ✅ Upload is rejected
- ✅ Error message: "File too large"
- ✅ File not added to list

---

### Test 11: UI Responsiveness

**Objective**: Verify UI doesn't freeze during processing

**Steps**:
1. Upload a large PDF
2. While processing, try:
   - Typing in chat box ← Should work
   - Clicking buttons ← Should respond
   - Switching tabs ← Should work smoothly
   - Scrolling document list ← Should scroll

**Expected Results**:
- ✅ All interactions responsive
- ✅ No UI freezing
- ✅ Processing continues in background

---

### Test 12: Document List Auto-refresh

**Objective**: Verify real-time status updates

**Steps**:
1. Upload document
2. Watch the status bar update
3. Monitor without manual refresh

**Expected Results**:
- ✅ Status updates every 1.5 seconds
- ✅ Progress bar moves smoothly
- ✅ No manual refresh needed
- ✅ Final status appears automatically

---

### Test 13: Browser Compatibility

**Test on**: Chrome, Firefox, Safari, Edge

**Steps for each browser**:
1. Load application homepage
2. Test file upload
3. Test chat functionality
4. Check graph visualization

**Expected Results**:
- ✅ UI loads correctly
- ✅ All features work
- ✅ No console errors
- ✅ Styling renders properly

---

### Test 14: Mobile Responsiveness

**Steps**:
1. Open on mobile device (or DevTools)
2. Set viewport to 375×667 (iPhone)
3. Test all features:
   - Upload
   - Chat
   - Graph viewing
   - Navigation

**Expected Results**:
- ✅ Layout adapts to mobile
- ✅ Single column layout
- ✅ Touch interactions work
- ✅ Text is readable

---

### Test 15: API Endpoints Directly

**Tool**: curl, Postman, or Python requests

#### Upload Request
```bash
curl -X POST \
  -F "files=@test_data.csv" \
  http://localhost:7860/api/upload
```

**Expected Response**:
```json
{
  "success": true,
  "message": "✅ 1 file(s) queued for processing",
  "successful": 1,
  "failed": 0,
  "files": ["test_data.csv"]
}
```

#### Get Documents
```bash
curl http://localhost:7860/api/documents
```

**Expected Response**:
```json
{
  "documents": {
    "test_data.csv": {
      "status": "ready",
      "chunks": 1,
      "entities": 10,
      "graph_image": "/graph-image/test_data.csv"
    }
  },
  "api_key_set": true,
  "timestamp": "2024-01-15T10:30:00"
}
```

#### Query
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "Who is the senior engineer?", "document": "test_data.csv"}' \
  http://localhost:7860/api/query
```

**Expected Response**:
```json
{
  "answer": "Based on the data, Alice Johnson is the Senior Engineer...",
  "sources": ["Chunk 1"],
  "confidence": 0.85
}
```

---

## Performance Benchmarks

### Expected Processing Times

| Document Type | Size | Processing Time |
|---|---|---|
| CSV (5 rows) | ~1KB | 2-3s |
| Small TXT | ~5KB | 3-5s |
| Medium PDF | 20 pages | 10-15s |
| Large PDF | 50+ pages | 30-60s |

### Query Response Times

- Simple query (1-2 words): 1-2s
- Complex query (5+ words): 2-4s
- Graph visualization load: <100ms

---

## Load Testing

### Single User
- 10 queries: Should complete in ~20-30s
- 5 uploads: Should complete in ~30-45s

### Concurrent Users (Docker)
- 3 simultaneous uploads: Should handle smoothly
- 5 concurrent queries: Should not block

---

## Checklist Summary

- [ ] Single document upload works
- [ ] Multiple document upload works
- [ ] Document shows processing status
- [ ] Graph visualization loads
- [ ] Simple query works
- [ ] Multi-context query works
- [ ] Out-of-context query handled
- [ ] Document deletion works
- [ ] Error messages appear for errors
- [ ] UI remains responsive
- [ ] Status updates automatically
- [ ] Works in multiple browsers
- [ ] Mobile responsive layout
- [ ] API endpoints work
- [ ] Performance acceptable

---

## Debugging Tips

### Check Logs
```bash
# Docker
docker-compose logs -f

# Local
python app.py  # Watch console output
```

### Common Issues

**Issue**: Graph doesn't load
- Check: `data/graph_data/` folder exists
- Check: Matplotlib installed
- Check: file permissions

**Issue**: Chat unresponsive
- Check: GROQ_API_KEY set
- Check: Document status is "ready"
- Check: Network connectivity

**Issue**: Slow processing
- Check: File size
- Check: System RAM/CPU
- Check: Model download complete

**Issue**: Files disappear
- Note: HF Spaces ephemeral storage
- Solution: Use persistent storage option

---

## Test Report Template

```
Test Run Date: ____
Tester Name: ____
Environment: (Local/Docker/HF Spaces)
OS: ____
Browser: ____

PASS/FAIL | Test Case | Notes
---|---|---
 | Test 1 |
 | Test 2 |
 | Test 3 |
...

Issues Found:
1. 
2.
3.

Overall Result: PASS/FAIL
```

---

**Happy Testing! 🎉**

If you find issues, report them with:
- Steps to reproduce
- Expected vs actual behavior
- Browser/OS information
- Relevant logs