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

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!"

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:

// 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'
    }]
  ],
});
npx zerovisual design-qa --url http://localhost:3000 --provider local

npx zerovisual design-qa --url http://localhost:3000 --penpot ./designs/artboard.svg
claude mcp add zerovisual -- npx -y zerovisual-mcp

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. 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. Up 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

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:

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.