control-ui

Control UI

使用本地浏览器自动化并提供证据，验证 UI 行为。首先复用仓库自带的 Playwright、浏览器或 Electron 测试框架；如果没有，则围绕应用的开发服务器或 Chromium 调试端口搭建临时测试框架。

用途

• 复现依赖真实浏览器焦点、键盘输入、滚动、调整大小或渲染的 UI 错误。
• 通过截图和快照验证视觉效果或无障碍功能的变更。
• 发布前检查本地 Web、IDE 或 Electron 的行为。
• 捕获控制台日志、网络日志、CPU 配置文件、跟踪记录或堆快照。
• 为 verify-this 创建变更前后的证据。

设置流程

1. 使用仓库文档中说明的开发命令在本地启动应用。
2. 查找现有的本地测试框架：Playwright 测试、Cypress 规格、Storybook、浏览器脚本、Electron 启动脚本或快照工具。
3. 对于 Web 应用，使用现有浏览器工具连接到本地 URL。
4. 对于 Electron/Chromium，在支持的情况下启用远程调试端口。
5. 根据稳定的应用标记选择正确的页面，不要只依赖标签页顺序。
6. 优先使用无障碍角色、标签和稳定的 data-* 选择器，而不是坐标。

通用 Web 测试框架

尽可能使用仓库已安装的浏览器工具。如果仓库已有 Playwright，可以使用以下精简的一次性探测脚本：

import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
await page.goto("http://127.0.0.1:<port>");
await page.getByRole("button", { name: /submit/i }).click();
await page.screenshot({ path: "/tmp/ui-harness-after.png", fullPage: true });
await browser.close();

除非用户提出要求，否则不要仅为此探测脚本添加 Playwright 作为项目依赖。优先使用现有开发依赖项或环境中已有的外部浏览器工具。

通用 CDP 测试框架

对于使用 --remote-debugging-port=<port> 启动的 Electron 或 Chromium 应用，可通过 CDP 连接：

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP("http://127.0.0.1:<debug-port>");
const pages = browser.contexts().flatMap((context) => context.pages());
let page;
for (const candidate of pages) {
  if (await candidate.locator("<app-root-selector>").count()) {
    page = candidate;
    break;
  }
}

if (!page) {
  console.log(await Promise.all(pages.map(async (p) => ({
    title: await p.title(),
    url: p.url(),
  }))));
  throw new Error("No matching app page found");
}

await page.screenshot({ path: "/tmp/ui-harness-cdp.png", fullPage: true });
await browser.close();

将 <app-root-selector> 替换为当前仓库中的稳定标记，例如应用根节点、地标元素或产品专属的 data-* 属性。

交互流程

1. 操作前先截取页面快照或屏幕截图。
2. 从最新的页面结构中选择目标。
3. 只执行一个结构性操作：点击、输入文本、按键、拖动、滚动、导航或调整大小。
4. 重新截取快照或屏幕截图。
5. 验证状态是否按预期变化。
6. 如果用户要求提供证明，则保存用于前后对比的产物。

CDP 功能

仅当更高级的浏览器 API 无法满足需求时，才使用原始 CDP：

• 性能：CPU 配置文件、跟踪记录、绘制闪烁、FPS 计量器、布局偏移检查。
• 内存：堆快照和强制 GC，用于调查内存泄漏。
• 网络：请求拦截、限流、禁用缓存、请求/响应日志。
• 渲染：视口变更、色彩方案模拟、减少动态效果、无障碍检查。
• 调试：控制台流、异常捕获、DOM 快照。

页面选择

当多个应用窗口或标签页共用一个调试端口时：

• 优先使用被测界面的正向标记，例如应用根选择器。
• 必要时使用负向标记，避免选错界面。
• 如果没有匹配的页面，请列出可用的页面标题和 URL，不要猜测。

注意事项

• 导航或结构变更后，不要依赖过期的元素引用。
• 除非刚刚截取了屏幕截图，否则避免按坐标点击。
• 使用本地且可丢弃的测试数据。
• 除非用户明确同意，否则不要保存来自隐私敏感工作区的屏幕截图或堆快照。
• 不要硬编码来自其他仓库的选择器、端口或脚本路径。请查找当前仓库的本地应用标记。
• 完成后清理开发服务器、调试会话和临时配置文件。