frontend-visualqa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Visual QA

Use this skill after changing UI code when DOM assertions are not enough and you need screenshot-backed proof of what the page actually rendered.

Use it for:

confirming the agent is on the right route or UI state
checking visibility, clipping, overflow, z-index, truncation, and responsive behavior
verifying interactive states such as modals, menus, toasts, tabs, and disabled buttons

Do not use it for:

starting the dev server
vague requests like "make it look better"
broad visual diffing across a large app surface

当DOM断言不足以验证页面实际渲染效果，需要以截图为依据的证明时，可在修改UI代码后使用此skill。

适用场景：

确认Agent处于正确的路由或UI状态
检查可见性、裁剪、溢出、z-index、截断及响应式表现
验证交互状态，如模态框、菜单、提示框、标签页及禁用按钮

不适用场景：

启动开发服务器
模糊的需求，例如“让它看起来更好”
对大型应用界面进行大范围视觉差异对比

Fast Path

快速流程

Make sure the frontend is already running locally.
Prefer the
```
frontend-visualqa
```
MCP tools when available. They keep browser state warm across calls.
If the page is auth-gated and the user can help, call
```
manage_browser
```
with
```
action="login"
```
and the login URL. That opens a persistent headed browser the user can authenticate in. Reuse the same
```
session_key
```
afterward, and call
```
manage_browser(action="close", ...)
```
when you are done with the authenticated session.
If the user provides a URL and explicit claims, go straight to
```
verify_visual_claims
```
— it captures screenshots internally, so a separate
```
take_screenshot
```
is redundant.
Only call
```
take_screenshot
```
first when you have no claims yet and need to see the page before writing them.
Fix the frontend, then rerun the same claims until they pass.

确保前端已在本地运行。
若可用，优先使用
```
frontend-visualqa
```
MCP工具，它们可在多次调用间保持浏览器状态持续活跃。
若页面需要权限验证且用户可协助，调用
```
manage_browser
```
并传入
```
action="login"
```
及登录URL。这会打开一个持久化的带界面浏览器，供用户完成身份验证。后续复用同一个
```
session_key
```
，完成验证会话后调用
```
manage_browser(action="close", ...)
```
关闭浏览器。
若用户提供了URL和明确的断言，直接调用
```
verify_visual_claims
```
即可——它会在内部自动捕获截图，因此单独调用
```
take_screenshot
```
是多余的。
仅当尚未确定断言，需要先查看页面内容再编写断言时，才先调用
```
take_screenshot
```
。
修复前端问题后，重新运行相同的断言，直到验证通过。

Claim Discipline

断言规范

Claims must be observable from pixels. Open

references/claim-writing.md

for examples and anti-patterns.

If a claim requires interaction before it becomes true or false, pass a

navigation_hint

. Keep the claim focused on the final visible state instead of burying a multi-step script inside the claim text.

For multi-claim flows where only some claims need setup, prefer a claims file and put per-claim metadata under the specific bullet, for example:

- After logging in, the dashboard shows "Welcome back, Developer"
  - navigation_hint: Type "test@yutori.com" in the email field, type "password123" in the password field, then click Continue.
- The API Calls Today stat card shows the value 1,247

When using MCP, split warm-session verification into successive

verify_visual_claims

calls if the setup differs between claims. Do not expect one global navigation hint to apply selectively within a single batch.

断言必须是可通过像素观察到的。可查看

references/claim-writing.md

获取示例及反模式说明。

若断言需要先进行交互才能验证真假，需传入

navigation_hint

。断言应聚焦于最终可见状态，而非将多步骤脚本隐藏在断言文本中。

对于仅部分断言需要前置操作的多断言流程，建议使用断言文件，并将每个断言的元数据放在对应的项目下，例如：

- After logging in, the dashboard shows "Welcome back, Developer"
  - navigation_hint: Type "test@yutori.com" in the email field, type "password123" in the password field, then click Continue.
- The API Calls Today stat card shows the value 1,247

使用MCP时，若不同断言的前置操作不同，需将暖会话验证拆分为多次连续的

verify_visual_claims

调用。不要期望一个全局的navigation_hint能在单次批量调用中选择性地应用。

Session Strategy

会话策略

Use ephemeral mode for public pages and quick checks.

Use persistent mode for auth-gated apps, multi-step flows, or any case where cookies and local storage must survive across runs. In MCP-driven workflows, bootstrap auth with

manage_browser(action="login", ...)

before running claims.

Setup and client-specific install commands live in

references/install.md

. The detailed QA playbook, status meanings, and recovery steps live in

references/protocol.md

公共页面和快速检查使用临时模式。

权限验证应用、多步骤流程或需要在多次运行间保留cookie和本地存储的场景，使用持久化模式。在MCP驱动的工作流中，需先调用

manage_browser(action="login", ...)

完成身份验证引导，再运行断言。

安装设置及特定客户端的安装命令见

references/install.md

。详细的QA手册、状态含义及恢复步骤见

references/protocol.md

。

Presenting Proof to the User

向用户展示证据

Every tool response includes file paths to screenshot evidence. Always surface this proof — do not just summarize the text result.

verify_visual_claims

returns an

artifacts_dir

and, for each claim,

results[].proof.screenshot_path

(the decisive screenshot) and

results[].proof.text

(a textual summary). Additional screenshots from intermediate steps live in

results[].trace.screenshot_paths

take_screenshot

returns a

screenshot_path

After a verification run:

Read the proof screenshot file for any failed or inconclusive claim so you can describe what is visually wrong.
Show the user the screenshot path and, if the client supports it, open or display the image inline.
When summarizing results, reference the specific visual evidence — do not just repeat the text finding.

If your client cannot display images inline, print the absolute path so the user can open it manually.

每个工具的响应都包含截图证据的文件路径。务必展示这些证据，而不仅仅是总结文本结果。

verify_visual_claims

会返回

artifacts_dir

，且针对每个断言，会返回

results[].proof.screenshot_path

（关键截图）和

results[].proof.text

（文本摘要）。中间步骤的额外截图存于

results[].trace.screenshot_paths

。

take_screenshot

会返回

screenshot_path

。

验证运行完成后：

查看所有失败或不确定断言的证据截图，以便描述视觉上的问题。
向用户展示截图路径，若客户端支持，可直接打开或内嵌显示图片。
总结结果时，需引用具体的视觉证据，而非仅重复文本结论。

若客户端无法内嵌显示图片，打印绝对路径供用户手动打开。

Tool Preference

工具优先级

Prefer the tools in this order:

```
verify_visual_claims
```
when the user provides claims — this is the primary tool and captures its own screenshots
```
take_screenshot
```
only when you need to see the page before you can write claims
```
manage_browser
```
when the shared browser state is stale, wrong-sized, or needs reset

If the MCP server is not available, use the CLI fallback in

references/install.md

$ARGUMENTS

工具优先级如下：

当用户提供断言时优先使用
```
verify_visual_claims
```
——这是核心工具，可自动捕获截图
仅当需要先查看页面再编写断言时使用
```
take_screenshot
```
当共享浏览器状态失效、尺寸错误或需要重置时使用
```
manage_browser
```

若MCP服务器不可用，使用

references/install.md

中的CLI备选方案。

$ARGUMENTS