frontend-visualqa

Gives coding agents eyes for frontend work — visual QA and verification powered by Yutori Navigator.

CLI demo

What it does

Verifies explicit visual claims against a running localhost frontend
Captures screenshots for quick visual inspection
Reuses browser sessions across MCP tool calls for multi-step debugging
Works as a CLI (frontend-visualqa verify), MCP server (frontend-visualqa serve), or agent skill (/frontend-visualqa)

Does not start your dev server. If the URL is unreachable, claims return not_testable.

Why visualqa?

Playwright MCP can click, type, and assert against the DOM — but it cannot see the page. It can run cleanly on the wrong page, assert modal.isVisible() on a modal rendered off-screen, or miss a layout that broke on mobile.

Navigator is an AI agent powered by a computer-use model (n1.5) that perceives a webpage via a screenshot and predicts actions to take in a browser. Two capabilities matter here:

Self-correcting navigation — Point the agent at the product catalog instead of a specific product page and Navigator recognizes the wrong page, clicks through to the right one, and reports trace.wrong_page_recovered: true. Playwright MCP would run assertions on the wrong page and silently pass — garbage in, garbage out.

Navigator lands on the product catalog →
Navigated to the correct product page
Rich visual evaluation — On the cart page, both items show sale prices ($149.99 and $79.99) but Navigator caught that the subtotal of $279.98 uses the original prices — the discount was never applied. On the API dashboard, the quota label reads "100%" but the progress bar is visibly only two-thirds full. Playwright MCP would pass both — the DOM text is consistent and the progress bar width is just a CSS value.

Navigator catches the discount-not-applied bug
Label says 100% but the bar is only about two-thirds full

Known limitation

Native <select> dropdowns — Native HTML <select> dropdown options can still be unreliable because they render as OS-level widgets outside the browser viewport. If your page uses native selects, prefer custom in-browser dropdown components for visual testing, or pre-fill the selection via URL parameters.

Install

Prerequisites

Install uv if you don't already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Quick install (recommended)

Install CLIs:

uv tool install frontend-visualqa \
  --with-executables-from yutori \
  --with-executables-from playwright
playwright install chromium

This installs the frontend-visualqa, yutori, and playwright CLIs and downloads the Chromium browser binary.

Log into Yutori API:
```
yutori auth login
```
This opens your browser to save your Yutori API key to ~/.yutori/config.json.
Or, manually add your API key

Go to platform.yutori.com and add your key to the config file:
```
mkdir -p ~/.yutori
cat > ~/.yutori/config.json << 'EOF'
{"api_key": "yt-your-api-key"}
EOF
```

frontend-visualqa

Popularity

What's Inside

README