DEPLOYMENT_GUIDE.md

Deployment Guide - Hugging Face Spaces

This guide walks you through deploying the UI Regression Testing System to Hugging Face Spaces.

Prerequisites

• Hugging Face account (https://huggingface.co)
• GitHub account (for repository)
• Git installed locally

Step 1: Create a GitHub Repository

1. Go to https://github.com/new
2. Create a new repository named ui-regression-testing
3. Clone it locally:

   git clone https://github.com/YOUR_USERNAME/ui-regression-testing.git
   cd ui-regression-testing
   

Step 2: Prepare Your Files

Copy all project files to your repository:

ui-regression-testing/
├── app.py                          # Main Gradio app
├── requirements.txt                # Python dependencies
├── README.md                       # Documentation
├── .gitignore                      # Git ignore file
├── state_schema.py                 # Workflow state
├── report_generator.py             # Report generation
├── screenshot_annotator.py         # Screenshot annotation
├── image_comparison_enhanced.py    # Image comparison
├── workflow.py                     # LangGraph workflow
├── agents/
│   ├── __init__.py
│   ├── agent_0_super_agent.py
│   ├── agent_1_design_inspector.py
│   ├── agent_2_website_inspector.py
│   └── agent_3_difference_analyzer.py
└── utils/
    ├── __init__.py
    ├── figma_client.py
    └── website_capturer.py

Step 3: Create .gitignore

Create a .gitignore file:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Environment
.env
.env.local

# Data
data/
reports/
*.png
*.jpg

# OS
.DS_Store
Thumbs.db

Step 4: Update requirements.txt

Ensure your requirements.txt includes:

# Core Dependencies
python-dotenv>=1.0.0
requests>=2.31.0

# LangGraph & LangChain
langgraph>=0.0.50
langchain>=0.1.0
langchain-core>=0.1.0

# Web Automation
playwright>=1.40.0

# Data Processing
numpy>=1.24.3
pandas>=2.1.3
pillow>=11.0.0

# Async Support
aiohttp>=3.9.1

# Utilities
python-dateutil>=2.8.2
scipy>=1.11.0

# Gradio
gradio>=4.0.0

# Hugging Face
huggingface-hub>=0.19.0
transformers>=4.30.0
torch>=2.0.0

# Image processing
opencv-python>=4.8.0
scikit-image>=0.21.0

Step 5: Push to GitHub

git add .
git commit -m "Initial commit: UI Regression Testing System"
git push origin main

Step 6: Create HF Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in:
   • Space name: ui-regression-testing
   • License: mit
   • Space SDK: Docker (for better control)
   • Space storage: Small (minimum)
   • Visibility: Public (or Private)
4. Click "Create Space"

Step 7: Configure Space

Option A: Using Docker (Recommended)

1. In your Space settings, select "Docker" as SDK
2. Create a Dockerfile in your repository:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Playwright browsers
RUN pip install --no-cache-dir playwright && \
    playwright install

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY . .

# Expose port
EXPOSE 7860

# Run the app
CMD ["python", "app.py"]

Option B: Using Gradio SDK (Simpler)

1. In your Space settings, select "Gradio" as SDK
2. The space will automatically use app.py as entry point

Step 8: Connect GitHub Repository

1. In Space settings, go to "Repository"
2. Connect your GitHub repository
3. Enable "Persistent Storage" (optional, for saving results)

Step 9: Configure Environment Variables

In your Space settings, add these secrets:

FIGMA_ACCESS_TOKEN=your_token_here
HUGGINGFACE_TOKEN=your_token_here

Note: Users will provide these through the UI, so these are optional defaults.

Step 10: Deploy

1. Push your code to GitHub
2. The Space will automatically rebuild
3. Monitor the build logs in the Space settings
4. Once deployed, your Space will be live at:

   https://huggingface.co/spaces/YOUR_USERNAME/ui-regression-testing
   

Step 11: Test Your Deployment

1. Open your Space URL
2. Fill in test credentials
3. Click "Start Regression Test"
4. Verify all features work correctly

Monitoring & Maintenance

View Logs

• Go to Space settings → "Logs"
• Check for errors or warnings

Update Code

• Push changes to GitHub
• Space will automatically rebuild

Monitor Performance

• Track execution time
• Monitor memory usage
• Check error rates

Troubleshooting

Build Fails

• Check Docker build logs
• Verify all dependencies in requirements.txt
• Ensure Python version compatibility

App Crashes

• Check Space logs
• Verify all imports are correct
• Test locally before deploying

Slow Performance

• Optimize image processing
• Cache results
• Consider upgrading Space resources

Memory Issues

• Reduce image resolution
• Implement garbage collection
• Use persistent storage

Optimization Tips

1. Reduce Image Size

# In image_comparison_enhanced.py
img = img.resize((img.width // 2, img.height // 2))

2. Cache Results

from functools import lru_cache

@lru_cache(maxsize=10)
def expensive_operation(key):
    # Your code here
    pass

3. Use Persistent Storage

import os
storage_dir = "/data"  # HF Spaces persistent storage
os.makedirs(storage_dir, exist_ok=True)

Advanced Configuration

Custom Domain

1. Go to Space settings → "Custom Domain"
2. Add your domain (requires DNS configuration)

Webhooks

1. Set up GitHub webhooks for automatic deploys
2. Configure in repository settings

Secrets Management

1. Use HF Spaces secrets for sensitive data
2. Never commit credentials to GitHub

Performance Benchmarks

Expected performance on HF Spaces:

Task	Time
Figma capture	5-10s
Website capture	10-15s
Difference analysis	5-10s
Report generation	2-5s
Total	30-50s

Scaling Considerations

For higher traffic:

1. Upgrade Space: Use larger instance
2. Add Caching: Cache comparison results
3. Optimize Images: Reduce resolution
4. Async Processing: Use background jobs
5. Load Balancing: Use multiple instances

Support & Resources

• HF Spaces Documentation
• Gradio Documentation
• Docker Documentation
• GitHub Actions

Next Steps

1. Deploy to HF Spaces
2. Share with team
3. Gather feedback
4. Iterate and improve
5. Monitor performance
6. Scale as needed

---

Happy deploying! 🚀