Welcome to QA Proof Documentation

Complete API reference and architecture guide for QA Proof — automated design QA using AI-powered visual testing.

New to QA Proof? Start with our Quick Start guide or explore the API Reference.

What is QA Proof?

QA Proof is an automated QA tool that bridges the gap between design and implementation. It provides three core capabilities:

Design Fidelity Testing — Compare Figma designs against live web pages using AI vision, with detailed reports on visual differences and CSS fix suggestions
Responsive Testing — Analyze how pages adapt to different device sizes (desktop, tablet, mobile) without needing a reference design
Visual Regression Monitoring — Detect unintended visual changes over time by comparing screenshots against saved baselines

Architecture Overview

QA Proof consists of an Express-based API server that orchestrates:

Figma Service — Fetches design exports via Figma API
Screenshot Service — Captures web pages using Playwright at multiple viewport sizes
AI Provider — Analyzes visual differences using AI Vision API
Baseline Service — Stores reference screenshots for regression testing

Quick Start

Get started with QA Proof in 3 steps:

1. Set up environment variables

# Required
QAPROOF_AI_KEY=your_ai_api_key
FIGMA_TOKEN=your_figma_personal_access_token
# Optional (production)
AUTH_ENABLED=true
MASTER_API_KEY=your_secure_master_key

2. Start the server

npm install
npm run dev

3. Run your first test

curl -X POST http://localhost:3000/api/compare \
  -H "Content-Type: application/json" \
  -d '{
    "pageUrl": "https://example.com",
    "testType": "fidelity",
    "figmaUrl": "https://www.figma.com/design/...",
    "figmaToken": "your_token_here"
  }'

API Reference

Base URL

http://localhost:3000 (development) or your production URL

Authentication

When AUTH_ENABLED=true, all API requests require an API key:

Authorization: Bearer qap_your_api_key_here

Core Endpoints

GET /api/health — Health check (no auth required)
POST /api/compare — Run design fidelity, responsive, or regression test
POST /api/baselines — Create a new baseline
GET /api/baselines — List all baselines
GET /api/baselines/:key — Get specific baseline
DELETE /api/baselines/:key — Delete baseline

Test Types

Design Fidelity Test

Compares Figma design against live implementation. Returns a score (0-100) plus detailed category scores for:

Layout & Structure
Colors & Backgrounds
Typography
Spacing & Sizing
Components & UI Elements

Responsive Test

Analyzes page adaptation across three viewports:

Desktop (1440x900px)
Tablet (768x1024px)
Mobile (375x812px)

Visual Regression Test

Compares current page against a stored baseline to detect unintended visual changes. Returns score where 100 = no changes detected.

Response Format

All successful API responses follow this structure:

{
  "success": true,
  "data": {
    "testType": "fidelity",
    "score": 82,
    "summary": "...",
    "categories": { ... },
    "differences": [ ... ],
    "recommendations": [ ... ],
    "screenshots": { ... }
  }
}

Error Codes

Common error codes you may encounter:

VALIDATION_ERROR (400) — Invalid request parameters
AUTH_ERROR (401) — Missing or invalid API key
RATE_LIMIT_ERROR (429) — Too many requests
BASELINE_NOT_FOUND (404) — Baseline doesn't exist
FIGMA_AUTH_FAILED (502) — Invalid Figma token
SCREENSHOT_ERROR (502) — Failed to capture page
AI_PROVIDER_ERROR (502) — AI provider failure

Next Steps

View the complete Help Center for detailed guides
Explore integration tutorials in our guides
Join our community for support