wvankuipers/inspectre repository overview

⁠Inspectre

Visual regression testing as a service. CI pipelines POST screenshots to Inspectre; Inspectre diffs them against approved baselines and reports pass/fail. A web UI lets your team review failures, inspect diff images, and promote new baselines with one click.

Built as a modern Python/Angular rewrite of the original Spectre⁠ Rails app.

⁠How it works

CI job
  └─ POST /runs          → creates a run
  └─ POST /tests         → uploads screenshot, returns immediately (~50 ms)
  └─ GET  /tests/:id/status  → poll until status == "done"

Celery worker (async)
  └─ ImageMagick compare vs stored baseline
  └─ Stores diff image + thumbnails to S3
  └─ Marks test passed / failed

Human
  └─ Opens http://localhost:4200
  └─ Reviews diff images, clicks "Set as baseline" to accept regressions

The first submission for any (project, suite, name, browser, size) combination has nothing to compare against, so it's stored with no comparison images, marked is_new_baseline: true, and marked not passed. A human must review it and click "Set as baseline" before it becomes the reference image subsequent submissions compare against. Later submissions that match an established baseline pass automatically, with no human involved.

⁠Architecture

⁠Domain model

Project ──▶ Suite ──▶ Run ──▶ Test
                  └─▶ Baseline  (one per test "key", lives on the Suite)

• Project — top-level grouping, e.g. "Acme Marketing Site"
• Suite — category of tests inside a project, e.g. "Desktop" or "Mobile"
• Run — one CI execution of a suite; the last 5 runs are kept per suite
• Test — one screenshot submission; carries diff %, pass/fail, and S3 image URLs
• Baseline — the accepted-good screenshot for a key; updated automatically when a test passes against an existing baseline, or manually via a human's "Set as baseline" click in the UI (required for the very first submission of a key, since there's nothing to compare it against and it never passes automatically)

⁠Image pipeline

POST /tests returns in ~50 ms. The heavy work runs in a Celery worker:

1. Download staged upload from S3
2. Optionally crop to a specified region
3. Pad both images to the same canvas
4. imagemagick compare -metric AE → diff pixel count → diff percentage
5. Upload original, baseline snapshot, diff overlay, and 300 px JPEG thumbnails
6. Upsert Baseline if passing against an existing baseline; set status = "done"

⁠API surfaces

Two URL namespaces:

• /api/* — SPA endpoints; can evolve freely
• Legacy (un-prefixed) — frozen contract for CI clients: POST /runs, POST /tests, GET /tests/:id/status, PATCH /tests/:id, GET /baselines/:key.png, GET /baselines/:key.json

⁠Docker images

⁠Documentation

• Overview⁠
• API reference⁠
• Data model⁠
• Image diffing⁠
• Storage & thumbnails⁠
• Deployment & config⁠
• UI⁠
• Tests & fixtures⁠
• Architecture decisions⁠

⁠Development

⁠Prerequisites

• Docker Desktop (or Docker Engine + Compose plugin)
• make

⁠First-time setup

cp deploy/.env.example .env
# Edit .env — at minimum set ADMIN_PASSWORD
make build
make up
make migrate

Services:

The SPA's nginx reverse-proxies /api, /runs, /tests, /baselines, and /admin to the API container — everything is same-origin from the browser.

⁠Seed demo data

make seed

Populates three projects with runs, pass/fail tests, and baselines so you can explore the UI without a real CI pipeline.

⁠Common commands

⁠Rebuilding after code changes

Backend / worker:

docker compose build api worker && docker compose up -d api worker

Frontend:

docker compose build spa && docker compose up -d spa

⁠Production deployment

⁠Environment variables

⁠Deploy

# First deploy
cp deploy/.env.example .env   # fill in production values
docker compose -f deploy/docker-compose.yml up -d
docker compose -f deploy/docker-compose.yml exec api python manage.py migrate

# Subsequent deploys
docker compose -f deploy/docker-compose.yml build api spa worker
docker compose -f deploy/docker-compose.yml up -d api spa worker
docker compose -f deploy/docker-compose.yml exec api python manage.py migrate

⁠Production checklist

• DEBUG=0
• DJANGO_SECRET_KEY is unique and random
• ALLOWED_HOSTS includes the production hostname
• S3 bucket exists; credentials have s3:PutObject, s3:GetObject, s3:DeleteObject
• Database backed up before running migrations
• S3_PUBLIC_BASE_URL set if serving images through a CDN

⁠Submitting screenshots from CI

# 1. Create a run
RUN=$(curl -s -X POST http://inspectre.example.com/runs \
  -d "project=My App&suite=Desktop" | jq -r .id)

# 2. Submit a screenshot (returns immediately with status=pending)
TEST_ID=$(curl -s -X POST http://inspectre.example.com/tests \
  -F "test[run_id]=$RUN" \
  -F "test[name]=Homepage" \
  -F "test[browser]=Chrome" \
  -F "test[size]=1440" \
  -F "test[screenshot][email protected]" | jq -r .id)

# 3. Poll for result
while true; do
  STATUS=$(curl -s http://inspectre.example.com/tests/$TEST_ID/status | jq -r .status)
  [ "$STATUS" = "done" ] || [ "$STATUS" = "failed" ] && break
  sleep 1
done

The pass field in the final response is true if the diff percentage is below the threshold.

⁠CI/CD

The GitHub Actions workflow (.github/workflows/ci.yml) runs lint and tests on every push and pull request to main, then builds and pushes multi-arch Docker images to Docker Hub on successful merges to main.

⁠Required repository secrets

Set these under Settings → Secrets and variables → Actions in the GitHub repository.

⁠Published images

⁠License

See LICENSE⁠.