astro44/qa-performance

qa-performance - Web Performance Validation

Validates performance metrics against budgets. Catches performance regressions before deployment.

Input Schema

{
  "project_dir": "/path/to/project",
  "ticket_id": "TICKET-XXX",
  "url": "http://localhost:8080",
  "budgets": {
    "lcp_ms": 2500,
    "fid_ms": 100,
    "cls": 0.1,
    "bundle_size_kb": 500,
    "total_requests": 50,
    "lighthouse_performance": 90
  }
}

Metrics Checked

Core Web Vitals

| Metric | Good | Needs Improvement | Poor | |--------|------|-------------------|------| | LCP (Largest Contentful Paint) | ≤2.5s | 2.5s - 4s | >4s | | FID (First Input Delay) | ≤100ms | 100ms - 300ms | >300ms | | CLS (Cumulative Layout Shift) | ≤0.1 | 0.1 - 0.25 | >0.25 |

Bundle Size

# Check JS bundle size
du -sh dist/js/*.js

# Check CSS bundle size
du -sh dist/css/*.css

# Check total dist size
du -sh dist/

Resource Counts

// Count resources by type
const resources = performance.getEntriesByType('resource');
const counts = {
  scripts: resources.filter(r => r.initiatorType === 'script').length,
  stylesheets: resources.filter(r => r.initiatorType === 'link').length,
  images: resources.filter(r => r.initiatorType === 'img').length,
  fonts: resources.filter(r => r.initiatorType === 'css' && r.name.includes('font')).length
};

Lighthouse Score

npx lighthouse $url --output=json --only-categories=performance

Instructions

1. Measure Core Web Vitals

// Using web-vitals library or Performance API
const { getLCP, getFID, getCLS } = require('web-vitals');

getLCP(metric => results.lcp = metric.value);
getFID(metric => results.fid = metric.value);
getCLS(metric => results.cls = metric.value);

2. Check Bundle Sizes

# Find all JS bundles
find dist -name "*.js" -exec du -k {} \; | awk '{sum += $1} END {print sum}'

# Check individual bundles
ls -la dist/js/*.js

3. Count Resources

# Count images
find src -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.svg" -o -name "*.webp" \) | wc -l

# Check for unoptimized images
find src -type f -name "*.png" -size +100k

4. Run Lighthouse

npx lighthouse http://localhost:8080 \
  --output=json \
  --output-path=./lighthouse-report.json \
  --only-categories=performance \
  --chrome-flags="--headless"

Output Format

{
  "skill": "qa-performance",
  "status": "pass|fail|warning",
  "metrics": {
    "core_web_vitals": {
      "lcp_ms": 1800,
      "lcp_status": "good",
      "fid_ms": 45,
      "fid_status": "good",
      "cls": 0.05,
      "cls_status": "good"
    },
    "bundle_size": {
      "js_kb": 320,
      "css_kb": 45,
      "total_kb": 365,
      "budget_kb": 500,
      "within_budget": true
    },
    "resources": {
      "total_requests": 28,
      "scripts": 8,
      "stylesheets": 3,
      "images": 12,
      "fonts": 2,
      "other": 3
    },
    "lighthouse": {
      "performance": 94,
      "budget": 90,
      "passed": true
    }
  },
  "violations": [
    {
      "metric": "images",
      "message": "3 images over 100KB found",
      "files": ["hero-bg.png", "team-photo.jpg", "map.png"],
      "recommendation": "Compress or convert to WebP"
    }
  ],
  "next_action": "proceed|fix|optimize"
}

Budget Thresholds

| Metric | Default Budget | Severity if Exceeded | |--------|---------------|---------------------| | LCP | 2500ms | HIGH | | FID | 100ms | HIGH | | CLS | 0.1 | MEDIUM | | Bundle Size | 500KB | MEDIUM | | Total Requests | 50 | LOW | | Lighthouse Perf | 90 | MEDIUM |

Decision Logic

Any HIGH severity violation?
    YES → status: "fail", next_action: "fix"

Any MEDIUM severity violation?
    YES → status: "warning", next_action: "optimize"

All metrics within budget?
    YES → status: "pass", next_action: "proceed"

Common Violations

| Issue | Detection | Fix | |-------|-----------|-----| | Large images | find -size +100k | Compress/WebP | | Unminified JS | Bundle >500KB | Enable minification | | Too many requests | >50 resources | Bundle/lazy load | | Render-blocking CSS | LCP >2.5s | Critical CSS/async | | Layout shifts | CLS >0.1 | Reserve space for images |

Usage Examples

Basic performance check:

{
  "project_dir": "/projects/oxygen_site",
  "url": "http://localhost:8080"
}

Strict budgets:

{
  "project_dir": "/projects/oxygen_site",
  "url": "http://localhost:8080",
  "budgets": {
    "lcp_ms": 1500,
    "bundle_size_kb": 300,
    "lighthouse_performance": 95
  }
}

Token Efficiency

• Runs automated tools (lighthouse, du, find)
• Returns structured metrics JSON
• Provides actionable violation details
• ~30 second execution time