Litmus

Test your website like a pro. Real performance, accessibility, and SEO checks for any URL —
with a video of exactly what happened, so you can watch the moment something broke.

---

Litmus drives a real headless browser (Playwright + Chromium) against a URL you submit, measures real metrics, inspects the rendered DOM, and returns explained pass/fail results with a transparent 0–100 score per category. The session is recorded to video, and failed rendering/interaction checks deep-link to the exact moment they happened.

Honest positioning: tools like Lighthouse already audit performance/a11y/SEO. Litmus doesn't claim to invent that. It differentiates with a cleaner explained-results UI, a live preview + session video with deep-links to failures, score history & trends, before/after & competitor comparison, multi-page crawl, and shareable public report pages.

✨ What makes it different

• 🔴 Watch it test, live. Hit run and watch the actual headless browser load your page in real time (CDP screencast), beside the checks ticking through.
• 🎬 Video deep-links to failures. A layout shift or JS crash links straight to the moment it happened in the recording — see the failure, don't just read it.
• 📱 Desktop & mobile. Audit as a real phone — emulated viewport, touch, and a CPU throttle — with mobile-only tap-target and PWA checks.
• 🔬 Transparent scores. Every 0–100 score shows each check's weighted contribution. No black-box numbers.
• 📈 History & trends. Re-test over time and watch the line climb. Every run is timestamped because live sites change.
• ⚖️ Compare. Diff two runs (before/after) or line your site up against a competitor.
• 🕸️ Multi-page crawl. Audit the homepage + its internal pages and surface the worst offenders.
• 🔗 Shareable reports. Every result gets a clean public /r/[id] link with an Open Graph card.
• 🔓 No signup to try. Anonymous testing is first-class; accounts only add history, comparison, and owned shares.

🧪 What it tests

Engine	Checks
Performance	Load time, Core Web Vitals (LCP, CLS, INP-proxy/TBT), page weight, request count, render-blocking resources
Accessibility	Alt text, colour contrast (computed from real colours), heading order, form labels, ARIA, tap targets — each citing its WCAG criterion
SEO & best practices	Title/meta, headings, mobile viewport, structured data, HTTPS, security headers, broken links, JS errors, PWA installability

Each result is a real measurement with a plain-English explanation and the exact evidence (element, selector, line, or metric).

🚀 Quickstart

git clone https://github.com/kruxshnx/litmus.git
cd litmus
npm install
npx playwright install chromium   # downloads the browser Litmus drives

cp .env.example .env.local         # fill in values (Supabase optional to start)
npm run dev                        # http://localhost:3000

Anonymous testing works without any configuration. Accounts, history sync, and shareable reports need Supabase — see docs/SUPABASE_SETUP.md.

Scripts

npm run dev         # dev server
npm run build       # production build
npm run lint        # eslint
npm run typecheck   # tsc --noEmit
npm test            # vitest (79 unit tests)

There are also live verification scripts: npx tsx scripts/verify-report.ts <url> runs the full audit against a real site and prints the report.

⚠️ Deploying (important — and a good interview talking point)

Playwright needs a real browser binary at runtime, which does not run on serverless/edge functions (e.g. Vercel's default functions). Litmus ships as a single container — frontend and runner — built on Playwright's base image, for a container host: Render, Railway, or Fly.io.

A Dockerfile, docker-compose.yml (local smoke test), render.yaml Blueprint, and a CI workflow are included — see docs/DEPLOY.md for the full guide.

docker compose up --build   # build + run the production image at http://localhost:3000

🏗️ How it works

URL ─▶ Playwright (Chromium)                ─▶ TestReport ─▶ UI / Supabase
        ├─ records video + CDP screencast
        ├─ measures performance (CWV)            ┌ performance.ts ┐
        ├─ scrolls + collects the rendered DOM ──┤ accessibility.ts├─▶ transparent
        └─ captures console / network / shifts   └ seo.ts         ┘   scores + checks

• lib/testing/ — the engine: runner.ts (Playwright session), collectors.ts (in-page DOM/perf collection), performance.ts / accessibility.ts / seo.ts (pure scoring engines), score.ts (transparent composite), crawl.ts (multi-page), index.ts (orchestrator).
• app/api/ — test (streaming NDJSON run + live frames), crawl, runs (RLS history), share, video/[id], auth/callback, og.
• Supabase — Postgres + Auth (email/Google/GitHub) + Storage, with Row Level Security on every user-owned table. The service-role key is server-only.

🧰 Tech stack

Next.js 14 (App Router) · React 18 · TypeScript (strict) · Tailwind CSS 3 + shadcn/ui · Playwright · Supabase (Postgres + Auth + Storage + RLS) · Recharts · Framer Motion · Sonner · Vitest.

🗺️ Roadmap

• Three real engines with transparent scoring
• Live preview + session video with failure deep-links
• Desktop & mobile (device-emulated)
• History, trends, before/after & competitor comparison
• Multi-page crawl
• Shareable /r/[id] reports with OG cards
• PDF export of reports
• Scheduled monitoring + alerts
• Embeddable "Verified Fast & Accessible" badge

📄 License

MIT © Govinda Krishna Arjangi