SETUP.md

Setup Guide - UI Regression Testing System

Complete setup instructions for local development and HF Spaces deployment.

Local Development Setup

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)
• Git
• 2GB RAM minimum

Step 1: Clone Repository

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

Step 2: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate it
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Install Playwright Browsers

playwright install

Step 5: Create .env File

Create a .env file in the project root:

cat > .env << 'EOF'
FIGMA_ACCESS_TOKEN=your_figma_token_here
FIGMA_FILE_KEY=your_figma_file_id_here
WEBSITE_URL=https://your-website.com
HUGGINGFACE_TOKEN=your_hf_token_here
EOF

Step 6: Run the Application

Option A: Run Gradio UI (Recommended)

python app.py

Then open http://localhost:7860 in your browser.

Option B: Run CLI Version

python main.py --execution-id test_001 --output-dir reports

Configuration

Environment Variables

Variable	Required	Description
FIGMA_ACCESS_TOKEN	Yes	Figma API token
FIGMA_FILE_KEY	Yes	Figma file ID
WEBSITE_URL	Yes	Website URL to test
HUGGINGFACE_TOKEN	No	HF token for vision models

Project Structure

ui-regression-testing/
├── app.py                          # Gradio UI application
├── main.py                         # CLI entry point
├── requirements.txt                # Python dependencies
├── Dockerfile                      # Docker configuration
├── README.md                       # Documentation
├── SETUP.md                        # This file
├── DEPLOYMENT_GUIDE.md             # HF Spaces deployment
├── .env                            # Environment variables (local only)
├── .gitignore                      # Git ignore rules
│
├── state_schema.py                 # Workflow state definition
├── workflow.py                     # LangGraph workflow
├── report_generator.py             # Report generation
├── screenshot_annotator.py         # Screenshot annotation
├── image_comparison_enhanced.py    # Image comparison
│
├── agents/                         # AI agents
│   ├── __init__.py
│   ├── agent_0_super_agent.py      # Test planning
│   ├── agent_1_design_inspector.py # Figma capture
│   ├── agent_2_website_inspector.py # Website capture
│   └── agent_3_difference_analyzer.py # Difference detection
│
├── utils/                          # Utility modules
│   ├── __init__.py
│   ├── figma_client.py             # Figma API client
│   └── website_capturer.py         # Website screenshot
│
├── data/                           # Data directory
│   ├── figma/                      # Figma screenshots
│   └── website/                    # Website screenshots
│
└── reports/                        # Generated reports
    ├── report_summary.md
    ├── report_detailed.md
    └── report_json.json

Development Workflow

1. Make Changes

Edit files as needed:

# Edit an agent
nano agents/agent_1_design_inspector.py

# Edit the UI
nano app.py

2. Test Locally

# Run the app
python app.py

# Or run tests
python -m pytest tests/

3. Commit Changes

git add .
git commit -m "Description of changes"
git push origin main

4. Deploy to HF Spaces

The space will automatically rebuild when you push to GitHub.

Troubleshooting

Issue: "ModuleNotFoundError: No module named 'playwright'"

Solution:

pip install playwright
playwright install

Issue: "Figma API Key is invalid"

Solution:

1. Verify token starts with figd_
2. Check token hasn't expired
3. Generate a new token from https://www.figma.com/developers/api#access-tokens

Issue: "Website URL is not accessible"

Solution:

1. Verify URL is correct and publicly accessible
2. Check internet connection
3. Try opening URL in browser manually

Issue: "No frames found in Figma file"

Solution:

1. Verify Figma File ID is correct
2. Ensure file contains frames
3. Check file sharing permissions

Issue: "Screenshots are blank or gray"

Solution:

1. Verify website loads correctly
2. Check for JavaScript errors
3. Ensure website doesn't require authentication
4. Try with a different website

Issue: "Out of memory error"

Solution:

1. Reduce image resolution
2. Process smaller batches
3. Close other applications
4. Upgrade system RAM

Performance Optimization

1. Reduce Image Size

Edit image_comparison_enhanced.py:

# Resize images for faster processing
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. Async Processing

import asyncio

async def process_images():
    # Async code here
    pass

Debugging

Enable Debug Logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug("Debug message")

Check Logs

# View app logs
tail -f app.log

# View error logs
tail -f error.log

Test Individual Components

# Test Figma client
python -c "from utils.figma_client import FigmaClient; print('OK')"

# Test website capturer
python -c "from utils.website_capturer import capture_website_sync; print('OK')"

Advanced Configuration

Custom Figma Frames

Edit agents/agent_1_design_inspector.py:

# Specify custom frame names
frame_names = ["CustomFrame1", "CustomFrame2"]

Custom Website Viewports

Edit agents/agent_2_website_inspector.py:

# Add custom viewport sizes
viewports = {
    "desktop": {"width": 1920, "height": 1080},
    "tablet": {"width": 768, "height": 1024},
    "mobile": {"width": 375, "height": 667}
}

Custom Comparison Thresholds

Edit image_comparison_enhanced.py:

# Adjust sensitivity
threshold = 0.90  # Higher = more sensitive

Testing

Run Unit Tests

python -m pytest tests/ -v

Run Integration Tests

python -m pytest tests/integration/ -v

Test with Sample Data

python main.py --test-mode --sample-data

Deployment Checklist

Before deploying to HF Spaces:

• All dependencies listed in requirements.txt
• .env file not committed to git
• Dockerfile builds successfully
• App runs locally without errors
• README.md is up to date
• DEPLOYMENT_GUIDE.md is followed
• All credentials are environment variables
• Tests pass
• No hardcoded secrets in code

Resources

• Python Documentation
• Gradio Documentation
• Playwright Documentation
• LangGraph Documentation
• Figma API Documentation
• HF Spaces Documentation

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review the documentation
3. Open an issue on GitHub
4. Contact the maintainers

---

Happy coding! 🚀