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

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

### Step 2: Create Virtual Environment

```bash
# 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

```bash
pip install -r requirements.txt
```

### Step 4: Install Playwright Browsers

```bash
playwright install
```

### Step 5: Create .env File

Create a `.env` file in the project root:

```bash
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)**

```bash
python app.py
```

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

**Option B: Run CLI Version**

```bash
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:

```bash
# Edit an agent
nano agents/agent_1_design_inspector.py

# Edit the UI
nano app.py
```

### 2. Test Locally

```bash
# Run the app
python app.py

# Or run tests
python -m pytest tests/
```

### 3. Commit Changes

```bash
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:**
```bash
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`:

```python
# Resize images for faster processing
img = img.resize((img.width // 2, img.height // 2))
```

### 2. Cache Results

```python
from functools import lru_cache

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

### 3. Async Processing

```python
import asyncio

async def process_images():
    # Async code here
    pass
```

## Debugging

### Enable Debug Logging

```python
import logging

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

### Check Logs

```bash
# View app logs
tail -f app.log

# View error logs
tail -f error.log
```

### Test Individual Components

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

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

### Custom Website Viewports

Edit `agents/agent_2_website_inspector.py`:

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

```python
# Adjust sensitivity
threshold = 0.90  # Higher = more sensitive
```

## Testing

### Run Unit Tests

```bash
python -m pytest tests/ -v
```

### Run Integration Tests

```bash
python -m pytest tests/integration/ -v
```

### Test with Sample Data

```bash
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](https://docs.python.org/3/)
- [Gradio Documentation](https://www.gradio.app/)
- [Playwright Documentation](https://playwright.dev/)
- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
- [Figma API Documentation](https://www.figma.com/developers/api)
- [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)

## 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! 🚀**