TESTING_GUIDE.md

# Testing Guide for Deployed Space

## Quick Status Check

Your Space is deployed at: **https://huggingface.co/spaces/ocx2025/basicsearch**

### Check Build Status

1. Visit https://huggingface.co/spaces/ocx2025/basicsearch
2. Look for the build status indicator at the top
3. If building, you'll see "Building..." with logs
4. If running, you'll see "Running" status

### View Build Logs

1. Go to https://huggingface.co/spaces/ocx2025/basicsearch/logs
2. Check for any errors during Docker build
3. Common issues:
   - Missing dependencies
   - Python version mismatch
   - Docker build timeout

## Testing Methods

### Method 1: Automated Test Scripts (Recommended)

#### Using Python Script
```bash
cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch

# Run all tests
python test_deployment.py

# Or test a custom URL
python test_deployment.py https://your-space-url.hf.space
```

#### Using Bash Script
```bash
cd /Users/marjorie/Documents/GitHub/xctopus/mcp2/basicsearch

# Run all tests
./test_deployment.sh

# Or test a custom URL
./test_deployment.sh https://your-space-url.hf.space
```

The scripts will test:
- ✅ Health check endpoint
- ✅ Service info endpoint
- ✅ Tools listing
- ✅ YouTube search functionality
- ✅ Error handling

### Method 2: Manual cURL Commands

#### 1. Health Check
```bash
curl https://ocx2025-basicsearch.hf.space/health
```

**Expected Response:**
```json
{"status": "ok"}
```

#### 2. Service Information
```bash
curl https://ocx2025-basicsearch.hf.space/
```

**Expected Response:**
```json
{
  "status": "healthy",
  "service": "basicsearch-mcp-server",
  "tools": ["search_youtube_videos"]
}
```

#### 3. List Available Tools
```bash
curl https://ocx2025-basicsearch.hf.space/tools
```

**Expected Response:**
```json
{
  "tools": [
    {
      "name": "search_youtube_videos",
      "description": "Searches YouTube for videos based on a query.",
      "parameters": {
        "query": "string (required)",
        "max_results": "integer (optional, default: 5)"
      }
    }
  ]
}
```

#### 4. Search YouTube Videos
```bash
curl -X POST https://ocx2025-basicsearch.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Python programming tutorial",
    "max_results": 3
  }'
```

**Expected Response (if API key is set):**
```json
{
  "results": [
    {
      "title": "Python Tutorial for Beginners",
      "video_id": "abc123xyz",
      "description": "Learn Python programming..."
    },
    ...
  ]
}
```

**Expected Error (if API key NOT set):**
```json
{
  "error": "YOUTUBE_API_KEY environment variable is not set"
}
```

### Method 3: Using Python `requests` Library

```python
import requests
import json

BASE_URL = "https://ocx2025-basicsearch.hf.space"

# Test health
response = requests.get(f"{BASE_URL}/health")
print(f"Health: {response.json()}")

# Test search
payload = {"query": "Python", "max_results": 2}
response = requests.post(f"{BASE_URL}/search", json=payload)
print(f"Search Results: {json.dumps(response.json(), indent=2)}")
```

### Method 4: Using Browser

Simply visit these URLs in your browser:

1. **Health Check:** https://ocx2025-basicsearch.hf.space/health
2. **Service Info:** https://ocx2025-basicsearch.hf.space/
3. **Tools List:** https://ocx2025-basicsearch.hf.space/tools

For POST requests, use a browser extension like:
- [Postman](https://www.postman.com/)
- [Thunder Client](https://www.thunderclient.com/) (VS Code extension)
- [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) (VS Code extension)

## Troubleshooting

### Space Returns 404
**Cause:** Space is still building or failed to start
**Solution:**
1. Check build logs at https://huggingface.co/spaces/ocx2025/basicsearch/logs
2. Wait for build to complete (can take 5-10 minutes)
3. Look for error messages in logs

### API Key Error
**Cause:** `YOUTUBE_API_KEY` not set or invalid
**Solution:**
1. Go to https://huggingface.co/spaces/ocx2025/basicsearch/settings
2. Click "Repository secrets"
3. Add secret: Name=`YOUTUBE_API_KEY`, Value=`your_actual_key`
4. Restart the Space

### Build Timeout
**Cause:** Docker build taking too long
**Solution:**
1. Check Dockerfile for optimization opportunities
2. Verify all dependencies are necessary
3. Consider using a lighter base image

### Connection Timeout
**Cause:** Space is sleeping (free tier) or overloaded
**Solution:**
1. Visit the Space page to wake it up
2. Wait a few seconds and retry
3. Check Space status

### Rate Limiting
**Cause:** Too many requests to YouTube API
**Solution:**
1. Check your Google Cloud Console quota
2. Default is 10,000 units/day
3. Each search costs ~100 units

## Monitoring

### Real-time Logs
```bash
# Using curl to monitor health
watch -n 5 'curl -s https://ocx2025-basicsearch.hf.space/health'
```

### Check Space Status
```bash
# Simple status check
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" \
  https://ocx2025-basicsearch.hf.space/health
```

### Continuous Testing
```bash
# Run tests every minute
while true; do
  echo "Testing at $(date)"
  python test_deployment.py
  sleep 60
done
```

## Performance Testing

### Load Test with Apache Bench
```bash
# Test 100 requests with 10 concurrent connections
ab -n 100 -c 10 https://ocx2025-basicsearch.hf.space/health
```

### Load Test with Python
```python
import time
import requests
from concurrent.futures import ThreadPoolExecutor

def test_endpoint():
    start = time.time()
    response = requests.get("https://ocx2025-basicsearch.hf.space/health")
    end = time.time()
    return response.status_code, end - start

# Run 50 concurrent requests
with ThreadPoolExecutor(max_workers=10) as executor:
    results = list(executor.map(lambda _: test_endpoint(), range(50)))

successful = sum(1 for status, _ in results if status == 200)
avg_time = sum(t for _, t in results) / len(results)

print(f"Successful: {successful}/50")
print(f"Average response time: {avg_time:.3f}s")
```

## Expected Response Times

| Endpoint | Expected Time |
|----------|--------------|
| `/health` | < 100ms |
| `/` | < 100ms |
| `/tools` | < 100ms |
| `/search` | 500ms - 2s (depends on YouTube API) |

## Security Testing

### Test Invalid Input
```bash
# Test with missing query
curl -X POST https://ocx2025-basicsearch.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{}'

# Test with invalid JSON
curl -X POST https://ocx2025-basicsearch.hf.space/search \
  -H "Content-Type: application/json" \
  -d 'invalid json'

# Test with excessive max_results
curl -X POST https://ocx2025-basicsearch.hf.space/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "max_results": 1000}'
```

## Integration Testing

### Test in Claude Desktop

If using with Claude Desktop, add to your MCP settings:

```json
{
  "mcpServers": {
    "basicsearch": {
      "url": "https://ocx2025-basicsearch.hf.space"
    }
  }
}
```

### Test with Python SDK

```python
from mcp import ClientSession
from mcp.client.stdio import stdio_client

# Connect to your MCP server
async with stdio_client() as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize
        await session.initialize()
        
        # Call search tool
        result = await session.call_tool(
            "search_youtube_videos",
            arguments={"query": "Python", "max_results": 3}
        )
        print(result)
```

## Next Steps

1. ✅ Run automated test script: `python test_deployment.py`
2. ✅ Check build logs if tests fail
3. ✅ Set YOUTUBE_API_KEY if not already set
4. ✅ Monitor Space status
5. ✅ Test all endpoints manually
6. ✅ Perform load testing if needed
7. ✅ Integrate with your applications

## Useful Links

- **Your Space:** https://huggingface.co/spaces/ocx2025/basicsearch
- **Logs:** https://huggingface.co/spaces/ocx2025/basicsearch/logs
- **Settings:** https://huggingface.co/spaces/ocx2025/basicsearch/settings
- **HF Spaces Docs:** https://huggingface.co/docs/hub/spaces
- **YouTube API Console:** https://console.cloud.google.com/apis/dashboard