{"slug": "zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it", "title": "ZeroVisual: I Was Too Lazy to Do Manual UI Testing, So I Made Open-Source AI Do It", "summary": "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.", "body_md": "*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)*\n\nI am lazy to do manual UI testing. Truly, unapologetically lazy.\n\nThere 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.\n\nWhen Vision LLMs arrived, the promise seemed magical: *\"Just dump a screenshot into an AI agent and let it review your UI!\"*\n\nExcept laziness quickly met reality:\n\nSloths 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.\n\n**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.\n\nIt addresses the two most tedious UI tasks developers dread:\n\n**Automated Visual Regression (`zerovisual regression` & Playwright Custom Reporter):**\n\nInstead of immediately bombarding a vision model with full-page screenshots, ZeroVisual relies on a **Two-Stage Architecture**:\n\n`ariaSnapshot`), and aggregates Desktop, Tablet, and Mobile failures under one `testId`. Your AI agent diagnoses the responsive layout bug in a single prompt.\n**Automated Design QA (`zerovisual design-qa`):**\n\nFor 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.\n\n**Built-in MCP Server & Agent Skills:**\n\nZeroVisual 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.\n\n```\n[Stage 1: Deterministic Engine (0 Tokens)]\nPlaywright Pixel Diff / CSS Heuristic Math / Penpot Token Diff\n       │\n       ├──► PASS ──► Workflow Ends Immediately (0 AI Tokens Used)\n       │\n       └──► FAIL / AUDIT ──► Triggers ZeroVisual Pre-Processor\n                                    │\n[Stage 2: ZeroVisual Optimizer]     ▼\n  1. Detects diff bounding box + 32px context padding\n  2. Resizes & encodes to WebP based on Model Tile Grid (512px / 504px / 768px / 448px)\n  3. Scopes Accessibility Tree (ariaSnapshot) & 14 Computed CSS layout styles\n  4. Aggregates Desktop + Tablet + Mobile viewports by testId\n                                    │\n                                    ▼\n              Outputs ./test-results/triage-ready.json\n                                    │\n            ┌───────────────────────┴───────────────────────┐\n            ▼                                               ▼\n   [Local IDE via MCP]                             [CI/CD Pipeline CLI]\nCursor / Claude Code / Antigravity               GitHub Actions / GitLab CI\nqueries ZeroVisual MCP Server + Skill          reads JSON & posts PR Verdict\n```\n\n`<think>`).\nAdd ZeroVisual as a custom reporter in `playwright.config.ts`:\n\n``` js\n// playwright.config.ts\nimport { defineConfig, devices } from '@playwright/test';\n\nexport default defineConfig({\n  testDir: './tests',\n  projects: [\n    { name: 'Desktop Chrome', use: { ...devices['Desktop Chrome'] } },\n    { name: 'Mobile Safari', use: { ...devices['iPhone 14'] } },\n  ],\n  reporter: [\n    ['list'],\n    ['zerovisual/reporter', {\n      targetProvider: 'local', // 'local' | 'openai' | 'anthropic' | 'gemini'\n      padding: 32,             // Context padding around diff bounding box\n      outputDir: './test-results'\n    }]\n  ],\n});\n# Audit live local UI against 8pt grid, WCAG contrast, and tap targets\nnpx zerovisual design-qa --url http://localhost:3000 --provider local\n\n# Or compare directly with an open-source Penpot design artboard\nnpx zerovisual design-qa --url http://localhost:3000 --penpot ./designs/artboard.svg\n# Register with Claude Code\nclaude mcp add zerovisual -- npx -y zerovisual-mcp\n\n# Or install Agent Skills for Antigravity / Cursor\nnpx skills add hotcode-dev/zerovisual\n```\n\n**Zero-waste, zero-API-key visual regression and automated UI design QA pre-processor for AI Agents.**\n\n**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.\n\n🌐 **Full Documentation & Interactive Token Calculator:** Visit our [Astro Documentation Site](https://hotcode-dev.github.io/zerovisual/). Local dev: `npm run docs:dev`.\n\nZeroVisual solves two major pain points in modern software engineering:\n\n`regression` mode)\nStandard 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…\n\nThe repository is 100% open source under the **Apache-2.0 License**:\n\n`@modelcontextprotocol/sdk`, `@playwright/test`, `sharp`, `citty`, `zod`, `fast-xml-parser`, Astro + Starlight.\nZeroVisual is designed from the ground up around **open-source AI and local inference**:\n\n**Local Vision-Language Models (Open-Weight ViTs):**\n\nWe 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:\n\n`local`):` lowTokenMode`)\n**Model Context Protocol (MCP) Standard:**\n\nBuilt 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.\n\n**Deterministic Local Math Pre-Engine:**\n\n`#ff00ff`, rose, and red).\n**Isolated Agent Skills:**\n\nShips 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.\n\nOpen innovation is what makes ZeroVisual fundamentally possible. A closed API approach wouldn't work for three critical reasons:\n\n**Privacy & Zero Data Leaks:**\n\nUI 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**.\n\n**ViT Patch Mechanics Transparency:**\n\nProprietary 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.\n\n**Uncapped, Meter-Free Automation:**\n\nCommercial 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.\n\nJudges and readers can inspect the full interactive agent session trace showing the benchmark execution and triage optimization on local Qwen-27B:\n\n*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)*\n\nHow much effort does ZeroVisual actually save?\n\nWe 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:\n\n| Core Metric | Without ZeroVisual (Raw Viewport) | With ZeroVisual (Optimized) | The Lazy Payoff | \n|---|---|---|---|\n| **Vision Image Tokens (ViT)** | **11,680 tokens** | **1,489 tokens** | **-87.3% ViT Token Reduction** | \n| **Network Payload Transfer** | **638.9 KB** | **66.0 KB** | **-89.7% Bandwidth Reduced** | \n| **Total Tokens Consumed** | **11,556 tokens** | **5,421 tokens** | **-53.1% Total Tokens Saved** | \n| **Average Roundtrip Latency** | **53.3 seconds** | **36.4 seconds** | **32% Faster (up to 3.8x on complex UIs)** | \n| **Average Triage Accuracy** | **76.7%** | **82.5%** | **+5.8% Accuracy Boost (Zero Canvas Noise)** | \n\n`translateY` offset in seconds and suggested the exact CSS fix: `margin-top: 0`.\n**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.", "url": "https://wpnews.pro/news/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it", "canonical_source": "https://dev.to/ntsd/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it-1jei", "published_at": "2026-10-23 05:00:32+00:00", "updated_at": "2026-10-23 05:10:58.882172+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "agent-protocols", "developer-tools", "ai-products"], "entities": ["ZeroVisual", "Playwright", "Penpot", "Cursor", "Claude Code", "Antigravity", "GitHub Actions", "GitLab CI"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it", "markdown": "https://wpnews.pro/news/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it.md", "text": "https://wpnews.pro/news/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it.txt", "jsonld": "https://wpnews.pro/news/zerovisual-i-was-too-lazy-to-do-manual-ui-testing-so-i-made-open-source-ai-do-it.jsonld"}}