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

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

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

curl https://ocx2025-basicsearch.hf.space/health

Expected Response:

{"status": "ok"}

2. Service Information

curl https://ocx2025-basicsearch.hf.space/

Expected Response:

{
  "status": "healthy",
  "service": "basicsearch-mcp-server",
  "tools": ["search_youtube_videos"]
}

3. List Available Tools

curl https://ocx2025-basicsearch.hf.space/tools

Expected Response:

{
  "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

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

{
  "results": [
    {
      "title": "Python Tutorial for Beginners",
      "video_id": "abc123xyz",
      "description": "Learn Python programming..."
    },
    ...
  ]
}

Expected Error (if API key NOT set):

{
  "error": "YOUTUBE_API_KEY environment variable is not set"
}

Method 3: Using Python requests Library

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
• Thunder Client (VS Code extension)
• 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

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

Check Space Status

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

Continuous Testing

# 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

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

Load Test with 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

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

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

Test with Python SDK

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