frontend-visualqa-plugins

frontend-visualqa

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

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.

n1 is a pixels-to-actions model trained with RL on live websites. Two capabilities matter here:

• Self-correcting navigation — Point the agent at the product catalog instead of a specific product page and n1 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.

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

  n1 catches the discount-not-applied bug

  Label says 100% but the bar is only at 2/3rds

Known limitation

• Native <select> dropdowns — n1 cannot see or interact with native HTML <select> dropdown options because they render as OS-level widgets outside the browser viewport. If your page uses native selects, replace them with 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)

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

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

3. Register the MCP server using add-mcp (works with all clients):

   npx add-mcp -g -n frontend-visualqa "frontend-visualqa serve"
   

   Pick the clients you want to configure.

4. Install skills using skills.sh:

   npx skills add yutori-ai/frontend-visualqa -g
   

   Adds the /frontend-visualqa slash command for claim-based visual QA guidance.

   -g installs at user scope. Omit -g for project-local install.

5. Restart your agent (Codex, Claude Code, etc) so the installs are picked up.

   To uninstall later:

   uv tool uninstall frontend-visualqa
   npx skills remove -g frontend-visualqa