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

A developer built ZeroVisual, an open-source visual regression and UI design QA pre-processor that sits between Playwright browser tests and Vision LLMs, cutting token usage by up to 88% and network payloads by 90% without requiring any external API key. The tool uses a two-stage architecture: a deterministic engine (pixel diff, CSS heuristic math, Penpot token diff) that ends the workflow with zero AI tokens on pass, and an optimizer that crops diff bounding boxes, resizes to model tile grids, scopes the accessibility tree, and aggregates desktop, tablet and mobile failures by testId into a triage-ready JSON. It ships as a CLI, a custom Playwright reporter, and an MCP server exposing tools such as list_visual_failures and audit_live_ui_design for use in Cursor, Claude Code and CI pipelines.

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady https://dev.to/challenges/hacktoberfest-week3-2026-10-19 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 " Except laziness quickly met reality: 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 : ariaSnapshot , and aggregates Desktop, Tablet, and Mobile failures under one testId . Your AI agent diagnoses the responsive layout bug in a single prompt. 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 <think . Add ZeroVisual as a custom reporter in playwright.config.ts : js // 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' } , } ; 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 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 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 https://hotcode-dev.github.io/zerovisual/ . Local dev: npm run docs:dev . ZeroVisual solves two major pain points in modern software engineering: regression mode 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… The repository is 100% open source under the Apache-2.0 License : @modelcontextprotocol/sdk , @playwright/test , sharp , citty , zod , fast-xml-parser , Astro + Starlight. ZeroVisual is designed from the ground up around open-source AI and local inference : Local Vision-Language Models Open-Weight ViTs : We benchmarked and validated ZeroVisual against RadixArk/Qwen3.8-27B-NVFP4 running completely locally on our workstation via SGLang and Ollama. Because open-weight vision models such as Qwen 2.5/3.8, Gemma 2, and PaliGemma publish their exact Vision Transformer patch dimensions e.g. 28×28px or 14×14px patch grids , ZeroVisual mathematically fits cropped diffs into the exact minimum patch allocation: local : lowTokenMode Model Context Protocol MCP Standard: Built on @modelcontextprotocol/sdk , exposing standard tools and prompts over stdio . Any MCP-compatible agent harness Claude Code, Cursor, Windsurf, Antigravity can query test results, inspect failure bundles, and trigger UI audits without custom glue code. Deterministic Local Math Pre-Engine: ff00ff , rose, and red . Isolated Agent Skills: Ships strictly-typed Agent Skills zerovisual-regression , zerovisual-design-qa , zerovisual-optimize that instruct coding models with precise JSON schemas and design rules, preventing instruction dilution. Open innovation is what makes ZeroVisual fundamentally possible. A closed API approach wouldn't work for three critical reasons: Privacy & Zero Data Leaks: UI test suites run against staging dashboards, internal admin portals, checkout flows, and unreleased features. Uploading full-resolution screenshots of private company data to commercial cloud APIs violates enterprise security and compliance policies. With open-weight models Qwen, Gemma running locally through ZeroVisual, zero pixels ever leave your local machine or internal CI runner . ViT Patch Mechanics Transparency: Proprietary vision APIs treat image processing as an opaque black box. In contrast, open-source model architectures expose their exact Vision Transformer tokenization logic patch sizes, position embeddings, and aspect ratio bucketing . This open transparency allowed us to engineer mathematically optimal cropping algorithms that align pixel boundaries directly with the model's ViT patches. Uncapped, Meter-Free Automation: Commercial vision APIs charge between $0.01 and $0.03 per image. In an active development team running hundreds of Playwright visual tests across multiple responsive viewports, running visual AI triage on every PR would incur crippling costs. Open innovation and local inference liberate developers from API meter anxiety—allowing you to run thorough UI testing on every single commit for $0. Judges and readers can inspect the full interactive agent session trace showing the benchmark execution and triage optimization on local Qwen-27B: Direct session link: View on DEV Agent Sessions https://dev.to/agent sessions/zerovisual-vision-llm-empirical-benchmark-877-vit-token-reduction-on-local-qwen-27b-pf9ccb How much effort does ZeroVisual actually save? We ran an empirical benchmark across 11 visual regression scenarios —including 5 live production websites Wikipedia Desktop & Mobile, Hacker News, GitHub Pricing, MDN Web Docs and 6 synthetic component regressions—comparing raw viewport screenshots against ZeroVisual optimization on local Qwen 3.8-27B: | Core Metric | Without ZeroVisual Raw Viewport | With ZeroVisual Optimized | The Lazy Payoff | |---|---|---|---| | Vision Image Tokens ViT | 11,680 tokens | 1,489 tokens | -87.3% ViT Token Reduction | | Network Payload Transfer | 638.9 KB | 66.0 KB | -89.7% Bandwidth Reduced | | Total Tokens Consumed | 11,556 tokens | 5,421 tokens | -53.1% Total Tokens Saved | | Average Roundtrip Latency | 53.3 seconds | 36.4 seconds | 32% Faster up to 3.8x on complex UIs | | Average Triage Accuracy | 76.7% | 82.5% | +5.8% Accuracy Boost Zero Canvas Noise | translateY offset in seconds and suggested the exact CSS fix: margin-top: 0 . The Real Payoff: Instead of spending 20 minutes manually reproducing a broken responsive layout and inspecting DevTools styles, ZeroVisual intercepts the failure, hands a token-optimized bundle to the local AI agent, and outputs the exact CSS diff to paste into your pull request.