ZeroVisual: I Was Too Lazy to Do Manual UI Testing, So I Made Open-Source AI Do It

Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady Submission 🦥

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

I am lazy to do manual UI testing. Truly, unapologetically lazy.

There is nothing quite as soul-crushing on a Friday afternoon as manually resizing browser windows, squinting at full-HD screenshots to see which button shifted by 3 pixels, inspecting CSS flexbox margins on three different viewports, or calculating whether a muted gray button passes WCAG 2.1 AA color contrast.

When Vision LLMs arrived, the promise seemed magical: "Just dump a screenshot into an AI agent and let it review your UI!"

Sloths have it figured out: move at your own pace, conserve energy, and let the work do itself. So in honor of International Sloth Day, I built ZeroVisual —an open-source, zero-API-key visual regression and automated UI design QA pre-processor that acts as a token-optimizing firewall between browser tests and Vision LLMs.

ZeroVisual is a local pre-processing engine, custom Playwright Reporter, CLI, and Model Context Protocol (MCP) server. It cuts Vision LLM token usage by up to 88% and network payloads by 90%, without requiring a single external API key.

It addresses the two most tedious UI tasks developers dread:

Automated Visual Regression ( zerovisual regression & Playwright Custom Reporter): Instead of immediately bombarding a vision model with full-page screenshots, ZeroVisual relies on a Two-Stage Architecture:

Automated Design QA ( zerovisual design-qa ): For developers building web apps without a dedicated UI/UX designer, guessing spacing and accessibility in CSS is exhausting. zerovisual design-qa audits any localhost URL against mathematical heuristics (8pt spatial grid rhythm, WCAG 2.1 contrast math, 44×44px touch targets) and compares live DOM against open-source Penpot design exports—zero proprietary Figma lock-in.

Built-in MCP Server & Agent Skills: ZeroVisual exposes native tools over stdio ( list_visual_failures, get_visual_failure_bundle, audit_live_ui_design, optimize_image ) and includes strictly-typed Agent Skills ( zerovisual-regression, zerovisual-design-qa, zerovisual-optimize ) compatible with Cursor, Claude Code, Antigravity, and custom CI agents.

[Stage 1: Deterministic Engine (0 Tokens)] Playwright Pixel Diff / CSS Heuristic Math / Penpot Token Diff │ ├──► PASS ──► Workflow Ends Immediately (0 AI Tokens Used) │ └──► FAIL / AUDIT ──► Triggers ZeroVisual Pre-Processor │ [Stage 2: ZeroVisual Optimizer] ▼ 1. Detects diff bounding box + 32px context padding 2. Resizes & encodes to WebP based on Model Tile Grid (512px / 504px / 768px / 448px) 3.

Scopes Accessibility Tree (ariaSnapshot) & 14 Computed CSS layout styles 4. Aggregates Desktop + Tablet + Mobile viewports by testId │ ▼ Outputs./test-results/triage-ready.json │ ┌───────────────────────┴───────────────────────┐ ▼ ▼ [Local IDE via MCP] [CI/CD Pipeline CLI] Cursor / Claude Code / Antigravity GitHub Actions / GitLab CI queries ZeroVisual MCP Server + Skill reads JSON & posts PR Verdict Enter fullscreen mode Exit fullscreen mode Demo 🌐 Live Documentation & Interactive Benchmark Explorer: hotcode-dev.github.io/zerovisual 🧮 Interactive Token Calculator: Calculate exact ViT token and byte savings directly on the homepage for OpenAI, Anthropic, Gemini, and Local models. 🔬 Real-World Benchmark Explorer: Inspect side-by-side screenshots (Baseline, Actual, Diff, Crop) across live production websites (Wikipedia, Hacker News, GitHub, MDN) and examine actual local VLM reasoning traces ( <think> ). Quick Start in Playwright Add ZeroVisual as a custom reporter in playwright.config.ts:

// playwright.config.ts import { defineConfig, devices } from ' @playwright/test '; export default defineConfig ({ testDir: './tests ', projects: [ { name: ' Desktop Chrome ', use: {... devices [ ' Desktop Chrome ' ] } }, { name: ' Mobile Safari ', use: {... devices [ ' iPhone 14 ' ] } }, ], reporter: [ [ ' list ' ], [ ' zerovisual/reporter ', { targetProvider: ' local ', // 'local' | 'openai' | 'anthropic' | 'gemini' padding: 32, // Context padding around diff bounding box outputDir: './test-results ' }] ], }); Enter fullscreen mode Exit fullscreen mode Run Standalone Design QA on Localhost # Audit live local UI against 8pt grid, WCAG contrast, and tap targets npx zerovisual design-qa --url http://localhost:3000 --provider local # Or compare directly with an open-source Penpot design artboard npx zerovisual design-qa --url http://localhost:3000 --penpot./designs/artboard.svg Enter fullscreen mode Exit fullscreen mode Connect to Coding Agents via MCP # Register with Claude Code claude mcp add zerovisual -- npx -y zerovisual-mcp # Or install Agent Skills for Antigravity / Cursor npx skills add hotcode-dev/zerovisual Enter fullscreen mode Exit fullscreen mode Code hotcode-dev / zerovisual Zero-waste, zero-API-key visual regression and automated UI design QA pre-processor for AI Agents. ZeroVisual Zero-waste, zero-API-key visual regression and automated UI design QA pre-processor for AI Agents.

ZeroVisual is a local pre-processing engine, Playwright Custom Reporter, CLI, and Model Context Protocol (MCP) server. It acts as a token-optimizing firewall between your browser tests/UI and your Vision LLMs—reducing vision token consumption by up to 90% without requiring a single LLM API key.

🌐 Full Documentation & Interactive Token Calculator: Visit our Astro Documentation Site. Local dev: npm run docs:dev.

ZeroVisual solves two major pain points in modern software engineering:

Standard Playwright toHaveScreenshot() pixel-diffing is fast and free, but fails on harmless sub-pixel font anti-aliasing or minor OS rendering shifts. Conversely, sending raw 1920x1080 screenshots across Desktop, Tablet, and Mobile viewports to a Vision LLM to triage failures will burn through your token budget and slow…