QUICKSTART.md

Quick Start Guide - POC Execution

🚀 Get Started in 5 Minutes

Step 1: Extract and Setup (2 minutes)

# Extract the project
unzip langgraph_ui_regression.zip
cd langgraph_ui_regression

# Run setup script
chmod +x setup.sh
./setup.sh

# Or manually install dependencies
pip install -r requirements.txt
playwright install chromium

Step 2: Configure Credentials (1 minute)

# Copy and edit environment file
cp .env.example .env
nano .env

Add your credentials:

FIGMA_FILE_KEY=your_figma_file_key
FIGMA_ACCESS_TOKEN=your_figma_access_token
WEBSITE_URL=https://v0-replicate-checkout-design.vercel.app/

Step 3: Run the System (2 minutes)

# Execute the workflow
python main.py

# Or with custom output directory
python main.py --output-dir ./my_reports --debug

Step 4: Check Results

Reports are generated in ./reports/ directory:

• report_YYYYMMDD_HHMMSS.json - Machine-readable report
• report_YYYYMMDD_HHMMSS.md - Human-readable report

---

📋 What Happens During Execution

1. Agent 0: Creates test plan
   ↓
2. Agent 1: Extracts design specs from Figma
   ↓
3. Agent 2: Extracts CSS specs from website
   ↓
4. Agent 3: Compares and generates findings
   ↓
5. Reports: JSON + Markdown output

---

🎯 Expected Output

Console Output

======================================================================
🚀 UI REGRESSION TESTING SYSTEM
======================================================================

📋 Configuration:
  Figma File Key: abc123def456...
  Website URL: https://v0-replicate-checkout-design.vercel.app/
  Output Directory: ./reports
  Debug Mode: False

======================================================================

🤖 Agent 0: Super Agent - Generating Test Plan...
  ✓ Configured 2 viewports
  ✓ Configured 7 test categories
  ✓ Test plan generated with 140 total tests

🎨 Agent 1: Design Inspector - Extracting Design Specs...
  ✓ Loaded Figma file: Checkout Design
  ✓ Extracted 156 design specifications
    - colors: 12 specs
    - typography: 24 specs
    - spacing: 18 specs
    - layout: 22 specs
    - borders: 15 specs
    - effects: 8 specs

🌐 Agent 2: Website Inspector - Extracting Website Specs...
  📱 Processing desktop viewport (1440px)...
    ✓ Loaded https://v0-replicate-checkout-design.vercel.app/
    ✓ Extracted specs for desktop
  📱 Processing mobile viewport (375px)...
    ✓ Extracted specs for mobile

🔍 Agent 3: Difference Analyzer - Comparing Specs...
  📊 Analyzing colors...
    ✓ Found 5 differences
  📊 Analyzing typography...
    ✓ Found 3 differences
  📊 Analyzing spacing...
    ✓ Found 2 differences
  ...

  ✓ Total findings: 15
    - High: 3
    - Medium: 7
    - Low: 5

📊 Generating Reports...

======================================================================
✅ EXECUTION COMPLETED SUCCESSFULLY
======================================================================

📄 Reports:
  JSON: ./reports/report_20240103_120000.json
  Markdown: ./reports/report_20240103_120000.md

📈 Summary:
  Total Findings: 15
  High Severity: 3
  Medium Severity: 7
  Low Severity: 5
  Overall Score: 75/100

======================================================================

Report Output

Markdown Report Preview:

# UI Regression Testing Report

**Generated**: 2024-01-03 12:00:00

## Summary
- **Total Findings**: 15
- **🔴 High Severity**: 3
- **🟡 Medium Severity**: 7
- **🟢 Low Severity**: 5
- **Overall Score**: 75/100

## High Severity Issues

#### submit_button - backgroundColor
**Category**: colors
**Design Value**: `#FF0000`
**Website Value**: `#FF0001`
**Analysis**: Significant color mismatch affecting brand consistency...

---

🔧 Troubleshooting

Problem: "ModuleNotFoundError: No module named 'langgraph'"

Solution:

pip install -r requirements.txt

Problem: "Figma API authentication failed"

Solution:

1. Verify your Figma access token is correct
2. Ensure the token has access to the file
3. Check token hasn't expired

Problem: "Website not loading"

Solution:

# Test the URL directly
curl https://v0-replicate-checkout-design.vercel.app/

# If it works, try running with debug mode
python main.py --debug

Problem: "Playwright browser not found"

Solution:

playwright install chromium

---

📊 Understanding the Reports

JSON Report Structure

{
  "metadata": { ... },
  "summary": {
    "total_findings": 15,
    "high_severity": 3,
    "medium_severity": 7,
    "low_severity": 5,
    "overall_score": 75
  },
  "findings": [
    {
      "component": "button",
      "category": "colors",
      "property": "backgroundColor",
      "severity": "high",
      "design_value": "#FF0000",
      "website_value": "#FF0001",
      "hf_analysis": "..."
    }
  ]
}

Severity Levels

• 🔴 High: Critical issues affecting functionality or brand consistency
• 🟡 Medium: Visual inconsistencies that should be addressed
• 🟢 Low: Minor differences that are visually acceptable

---

🎯 Next Steps After POC

1. Review Findings: Check the generated reports
2. Fix Issues: Address high and medium severity findings
3. Re-run Tests: Execute again to verify fixes
4. Add Gradio Dashboard: For visual comparison (Phase 7)
5. CI/CD Integration: Automate testing in your pipeline

---

📞 Need Help?

1. Check the main README.md for detailed documentation
2. Enable debug mode: python main.py --debug
3. Review the generated reports for specific issues
4. Check the troubleshooting section above

---

Ready to test? Run: python main.py 🚀