{"id":50800487,"url":"https://github.com/ravidsrk/frontguard","last_synced_at":"2026-06-12T19:01:46.160Z","repository":{"id":360254828,"uuid":"1192650057","full_name":"ravidsrk/frontguard","owner":"ravidsrk","description":"AI-powered frontend visual regression testing. Detect, understand, and fix visual bugs before production.","archived":false,"fork":false,"pushed_at":"2026-06-03T10:00:19.000Z","size":2139,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T11:14:31.853Z","etag":null,"topics":["ai","automated-testing","cli","frontend-testing","playwright","screenshot-testing","testing","typescript","visual-regression-testing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ravidsrk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["ravidsrk"]}},"created_at":"2026-03-26T12:31:05.000Z","updated_at":"2026-06-03T09:30:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ravidsrk/frontguard","commit_stats":null,"previous_names":["ravidsrk/frontguard"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ravidsrk/frontguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravidsrk%2Ffrontguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravidsrk%2Ffrontguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravidsrk%2Ffrontguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravidsrk%2Ffrontguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ravidsrk","download_url":"https://codeload.github.com/ravidsrk/frontguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravidsrk%2Ffrontguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34258372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automated-testing","cli","frontend-testing","playwright","screenshot-testing","testing","typescript","visual-regression-testing"],"created_at":"2026-06-12T19:01:43.864Z","updated_at":"2026-06-12T19:01:46.148Z","avatar_url":"https://github.com/ravidsrk.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ravidsrk"],"categories":[],"sub_categories":[],"readme":"# 🛡️ Frontguard\n\n[![CI](https://github.com/ravidsrk/frontguard/actions/workflows/ci.yml/badge.svg)](https://github.com/ravidsrk/frontguard/actions/workflows/ci.yml)\n[![npm: @frontguard/cli](https://img.shields.io/npm/v/@frontguard/cli?label=%40frontguard%2Fcli)](https://www.npmjs.com/package/@frontguard/cli)\n[![npm: @frontguard/playwright](https://img.shields.io/npm/v/@frontguard/playwright?label=%40frontguard%2Fplaywright)](https://www.npmjs.com/package/@frontguard/playwright)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Tests](https://img.shields.io/badge/tests-1000+-brightgreen)]()\n\n**AI-powered frontend visual regression testing. Detect, understand, and fix visual bugs before production.**\n\nBackend has Datadog, Sentry, PagerDuty — a $20B+ monitoring ecosystem. Frontend gets... manual QA and hoping for the best. Frontguard changes that.\n\n\u003e **1000+ tests** · **multi-browser** · **AI vision analysis** · **self-hostable** · **MIT**\n\n\u003c!-- Demo: generate the GIF with `vhs demo/frontguard-demo.tape` → demo/frontguard-demo.gif --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e📽️ Demo: \u003ccode\u003efrontguard init\u003c/code\u003e → \u003ccode\u003edoctor\u003c/code\u003e → \u003ccode\u003erun\u003c/code\u003e → AI classification.\u003c/em\u003e\u003cbr/\u003e\n  See the \u003ca href=\"./demo/frontguard-demo.tape\"\u003eVHS tape script\u003c/a\u003e — render the GIF locally with \u003ccode\u003evhs demo/frontguard-demo.tape\u003c/code\u003e.\n\u003c/p\u003e\n\n## Why Frontguard?\n\n- **🧠 AI-powered analysis** — Doesn't just say \"pixels differ.\" It classifies the change (regression vs intentional vs content update), explains *why*, and suggests a fix. This kills the #1 pain of visual testing: false positives.\n- **🎯 Anti-flake rendering** — Multi-render consensus eliminates the flaky-screenshot noise that makes teams disable their visual suites.\n- **🔓 Open-source \u0026 self-hostable** — CLI-first, free forever. No per-screenshot pricing cliff, no dashboard lock-in, BYO AI key.\n\n## What It Does\n\n```\nDeveloper pushes code → Frontguard renders every page → Compares to baselines →\nAI explains what changed and why → Suggests fixes → Posts PR comment\n```\n\n- **Detect** — Pixel diff + DOM diff catches what humans miss\n- **Understand** — AI explains *why* something broke, not just \"pixels differ\"\n- **Fix** — Verified code fixes, re-rendered to confirm they work (Phase 2)\n\n## Quick Start\n\n**Prerequisites:** [Node.js](https://nodejs.org/) 20+ and npm 9+\n\n```bash\n# Install\nnpm install @frontguard/cli\n\n# Initialize config (auto-detects your framework, --ci adds a GitHub Action)\nnpx frontguard init --ci\n\n# Verify your environment is ready\nnpx frontguard doctor\n\n# Run visual regression tests\nnpx frontguard run --url http://localhost:3000\n\n# Accept current screenshots as new baselines\nnpx frontguard update-baselines\n```\n\n\u003e **Full documentation:** [frontguard.dev](https://frontguard.dev) · [`docs/`](./docs/) folder\n\n## Features\n\n- **Zero-config route discovery** — Auto-crawls your app to find all pages\n- **Multi-browser** — Chromium, Firefox, WebKit via Playwright\n- **AI-powered analysis** — BYOK (OpenAI/Anthropic) classifies regressions vs intentional changes\n- **Smart rendering** — Dependency graph renders only pages affected by your changes\n- **Preview deployments** — Auto-detects Vercel/Netlify preview URLs\n- **Git-native baselines** — Stored in orphan branch, zero main branch bloat\n- **Framework detection** — Next.js, Remix, SvelteKit, Nuxt, Astro out of the box\n- **Security hardened** — Shell injection prevention, path traversal guards, API key redaction\n- **Memory managed** — Streaming buffers, temp file cleanup, bounded concurrency\n- **PR thumbnails** — Baseline/current/diff images embedded in PR comments (R2/S3/GitHub artifacts)\n- **Per-route thresholds** — Strict on `/checkout`, relaxed on `/blog` — all in one config\n\n## How Frontguard Compares\n\n| | Frontguard | Percy | Chromatic | BackstopJS | Lost Pixel |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Open source | ✅ | ❌ | ◐ | ✅ | ◐ (archived) |\n| CLI-first | ✅ | ❌ | ❌ | ✅ | ✅ |\n| **AI change classification** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Anti-flake rendering | ✅ | ◐ | ◐ | ❌ | ❌ |\n| Self-hostable | ✅ | ❌ | ❌ | ✅ | ◐ |\n| Free tier | Forever (CLI) | Trial → $399/mo | Storybook hobby | Free | Dead |\n| Actively maintained | ✅ | ✅ | ✅ | ❌ (6yr) | ❌ |\n\n\u003e Migrating? See the [BackstopJS](https://frontguard.dev/docs/guides/migrate-from-backstopjs) and [Lost Pixel](https://frontguard.dev/docs/guides/migrate-from-lost-pixel) guides.\n\n## AI Classification Example\n\n```\n  ✘ /dashboard @ 375px — 2.34% changed\n    🔴 AI Analysis — Regression (94% confidence)\n    \"The sidebar overlaps the main content on mobile. A flex-direction\n     change in Dashboard.module.css:28 removed the column stacking.\"\n    Suggested fix: restore `flex-direction: column` at the \u003c 768px breakpoint.\n\n  ✓ /pricing @ 1440px — 0.8% changed\n    🟢 AI Analysis — Intentional (91% confidence)\n    \"New 'Enterprise' pricing tier added. Layout intact, content expanded.\"\n```\n\n## Configuration\n\n```typescript\n// frontguard.config.ts\nexport default {\n  version: 1,\n  baseUrl: 'http://localhost:3000',\n\n  // Auto-discover routes (zero config)\n  discover: {\n    startUrl: '/',\n    maxDepth: 3,\n    exclude: ['/admin/*', '/api/*'],\n  },\n\n  // Or explicit routes\n  // routes: ['/', '/pricing', '/checkout'],\n\n  viewports: [375, 768, 1440],\n  browsers: ['chromium'],\n  threshold: 0.1,\n\n  // AI analysis (optional, BYOK)\n  ai: {\n    provider: 'openai',\n    model: 'gpt-4o',\n  },\n\n  // Ignore dynamic content\n  ignore: [\n    { selector: '.dynamic-timestamp' },\n  ],\n};\n```\n\n## How It Works\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│  ROUTE DISCOVERY │───▶│  RENDER PAGES    │───▶│  PIXEL DIFF     │\n│  Crawl / Config  │    │  Playwright ×    │    │  pixelmatch     │\n│  / Filesystem    │    │  viewports ×     │    │  fast gate      │\n│                  │    │  browsers        │    │  (90% pass here)│\n└─────────────────┘    └──────────────────┘    └────────┬────────┘\n                                                        │ changed\n                                                        ▼\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│  PR COMMENT     │◀───│  AI ANALYSIS     │◀───│  DOM DIFF       │\n│  Visual diffs   │    │  GPT-4V / Claude │    │  Structural +   │\n│  Explanation    │    │  Classify +      │    │  computed styles │\n│  Fix suggestion │    │  explain + fix   │    │                 │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n## CLI Output\n\n```\n frontguard v0.1.0\n\n 🔍 Discovering routes... found 47 routes\n 📊 12/47 routes affected by changed files\n 🖥  Rendering 12 routes × 3 viewports\n\n ───────────────────────────────────────────\n  RESULTS                        12 routes\n ───────────────────────────────────────────\n  ✓ /                375  768  1440   PASS\n  ✓ /pricing         375  768  1440   PASS\n  ⚠ /checkout        375  768  1440   WARNING\n  ✘ /dashboard       375  768  1440   REGRESSION\n  ★ /settings        375  768  1440   NEW\n ───────────────────────────────────────────\n\n  ✘ /dashboard @ 375px\n    AI: \"Sidebar overlaps main content on mobile.\n         flex-direction change in Dashboard.module.css:28\"\n    Severity: 🔴 Critical (confidence: 94%)\n\n  1 regression · 1 warning · 9 passed · 1 new\n```\n\n## Plugins\n\nFrontguard ships with a plugin architecture (6 lifecycle hooks) and 5 built-in plugins:\n\n| Plugin | Description | Key Features |\n|--------|-------------|--------------|\n| **Figma** (`src/plugins/figma.ts`) | Design-to-code comparison | Figma API integration, design token extraction, component mapping |\n| **Performance Budgets** (`src/plugins/perf-budgets.ts`) | Web Vitals \u0026 budgets | LCP/CLS/TTFB thresholds, violations correlated with the visual diff |\n| **Accessibility** (`src/plugins/accessibility.ts`) | axe-core audits | WCAG checks (contrast, alt text, target size, focus, headings) in the same render pass |\n| **Third-Party Scripts** (`src/plugins/third-party-scripts.ts`) | Script drift detection | Flags ad/analytics/widget origins that appear or disappear between runs |\n| **Monitor** (`src/plugins/monitor.ts`) | Production visual monitoring (CLI + optional cloud scheduler) | Live-URL checks, threshold alerting, history tracking |\n\n**Plugin lifecycle hooks:** `beforeDiscover`, `afterDiscover`, `afterRender`, `afterCompare`, `afterRun`, `onError`\n\n```typescript\n// frontguard.config.ts\nimport { createFigmaPlugin } from '@frontguard/cli/plugins';\n\nexport default {\n  // ...base config\n  plugins: [\n    createFigmaPlugin({ fileKey: 'your-figma-file-key' }),\n  ],\n};\n```\n\n## Architecture\n\n```\nsrc/\n├── cli/              # CLI entry point (Commander.js)\n├── core/             # Pipeline orchestrator, types, config, plugin system\n├── discovery/        # Route discovery (crawler + filesystem)\n├── render/           # Playwright rendering engine\n├── diff/             # Pixel diff + AI vision analysis\n├── storage/          # Git orphan branch baselines\n├── report/           # Console, JSON, HTML, GitHub PR reporters\n├── plugins/          # Figma, perf budgets, accessibility, third-party scripts, monitoring\n└── utils/            # Redaction, logging, retry\n```\n\nPipeline: `discover → filter → render → diff → analyze → report`\n\nEach stage is independent with error boundaries — one page failing doesn't kill the run.\n\n## Documentation\n\nSee [`docs/`](./docs/) for:\n- [Product deep-dive](./docs/PRODUCT.md) — Architecture decisions and design rationale\n- [Research](./docs/research/) — Market data, technical feasibility, competitive landscape\n\n## Roadmap\n\nSee [ROADMAP.md](./docs/ROADMAP.md) for the full milestone history and upcoming plans.\n\n## Environment Variables\n\n```bash\n# AI Analysis (optional, BYOK — bring your own key, pick one)\nFRONTGUARD_OPENAI_KEY=sk-...\nFRONTGUARD_ANTHROPIC_KEY=...\n\n# GitHub PR comments\nGITHUB_TOKEN=ghp_...\n```\n\n\u003e **Note:** AI keys are optional. Frontguard works without them — pixel diff and DOM diff run locally. AI analysis (classification, explanations, fix suggestions) activates only when a key is provided.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines, development setup, and how to submit PRs.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravidsrk%2Ffrontguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravidsrk%2Ffrontguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravidsrk%2Ffrontguard/lists"}