vitexec

vitexec

当真相存在于正在运行的浏览器中时，请使用 vitexec：例如客户端状态、导入的应用模块、DOM、canvas/WebGL、屏幕截图、录制内容或仅在浏览器中出现的错误。

对于静态文件、单元测试或 TypeScript 可以直接回答的问题，请优先使用它们。

参考资料

• 关于鼠标、键盘或指针锁定，请阅读 references/inputs.md。
• 关于 CPU、网络、性能时间线或堆分析，请阅读 references/performance.md。
• 关于 WebXR，请阅读 references/webxr.md。

工作流

1. 如果页面路径不是 /，请先确定页面路径。
2. 编写最精简的代码片段，执行类似用户的操作或读取仅存在于浏览器中的状态。
3. 对于 ./vitexec/check.ts，运行 vitexec '<snippet>' 或 vitexec check.ts。
4. 检查日志和退出状态。脚本失败或超时会以非零状态退出；打印出错误不代表成功完成。

如果缺少 vitexec，请使用项目已采用的包管理器安装 vitexec。

vitexec 'console.log("ready")'
vitexec check-scene.ts

对于单个参数，CLI 会先检查按原样指定的路径，然后检查 ./vitexec 下的路径，最后将其视为内联代码。

对于结构化状态，请记录 JSON：

vitexec --path /cart '
  import { mouse } from "vitexec";
  import { useCartStore } from "/src/store/cart.ts";

  const button = document.querySelector("[data-testid=add-to-cart]");
  if (!(button instanceof HTMLElement)) throw new Error("Add button not found");
  const box = button.getBoundingClientRect();
  await mouse.moveTo(box.x + box.width / 2, box.y + box.height / 2);
  await mouse.click();
  await new Promise((resolve) => requestAnimationFrame(resolve));
  console.log("cart", JSON.stringify(useCartStore.getState()));
'

默认情况下，浏览器窗口处于隐藏状态。若用户想要观看，请在一次性命令或 open 中添加 --headed，而不是添加到 run 中。以编程方式使用时，请向 openPage 或 openBrowser 传入 headless: false。对于远程启动，窗口会显示在远程主机上；连接到已运行的浏览器不会改变其可见状态。

重用页面

如果后续脚本需要使用先前操作创建的状态，请使用会话：

vitexec open game
vitexec run game setup.ts
vitexec run game play.ts

使用 Agent 的后台终端工具启动 open；它会在前台持续运行，并实时输出常规页面诊断信息。run 会自动等待页面启动。所有命令都使用相同的工作目录。浏览器/Vite/视口选项应传给 open；每次运行的屏幕截图、录制内容和性能分析配置文件应传给 run。

每次 run 都会等待执行完成，并输出可追溯到其脚本的控制台日志。无法通过脚本堆栈确定来源的应用日志会留在 open 中，其中包括某些由物理输入触发的日志。调查应用故障时，请检查这些输出。脚本应等待其所需日志对应的工作完成。执行超时后，请停止并重启会话：旧代码可能仍在运行。

为便于在输入操作的同时观察，可以让多个独立的 run 调用重叠执行。它们共用同一个页面；同一时间只能使用一个输入驱动程序。录制和性能分析操作不能重叠。完成后，使用 SIGINT 或 SIGTERM 停止 open 进程，并等待其退出；该进程会关闭页面、浏览器和服务端。

以编程方式组合操作时，请使用 const page = await openPage(options)、await run(page, code, { onLog })，并在 finally 中调用 await page.close()。openPage 会管理自己的服务端和浏览器；其 onLog 会接收页面诊断信息。run 只会向现有的 Chromium 页面注入代码，不会导航到其他页面或将其关闭。

指南

• 如果有可用的状态，优先导入导出的应用状态，而不是抓取 DOM。
• 断言时优先直接读取状态；验证用户交互时使用物理输入。
• 使用 vitexec 中的 mouse 和 keyboard 进行物理输入；合成 DOM 事件无法验证相同的行为。
• --timeout 用于设置 open 的导航超时，以及 run 的连接、启动和执行超时；应将物理输入的实际耗时纳入预算，而不仅仅是应用耗时。
• 使用实时进度日志和有针对性的断言，以便在失败时尽早退出并查看当前进度。
• 保持日志简洁；过于冗长的日志难以阅读，还会不必要地占用上下文。
• 优先使用浏览器根路径导入，例如 /src/store.ts，而不是本地文件系统路径。
• 默认启用 GPU 加速。测试不使用硬件加速时，请使用 --no-gpu（API：gpu: false）；该选项属于浏览器创建配置，而非会话 run。
• 如果本地机器没有可用的 GPU，请使用 --browser-ws-endpoint <ws-url> 连接到已使用正确的主机专属 GPU 设置启动的远程 Playwright 服务。
• 如果重复运行需要相同的端点或制品设置，优先使用 VITEXEC_* 环境变量，而不是反复传入冗长的标志。
• 仅在视觉证据重要时使用截图或录制。
• 优先使用临时的 Vitexec 脚本，而不是向应用添加检查代码。

项目集成

Vite 应用可以从 vitexec 包中添加 vitexec()。该插件会将 ./vitexec 中的每个顶层模块映射到同名页面：

import { vitexec } from "vitexec";

export default {
  plugins: [vitexec()]
};

vitexec/smoke.ts → /smoke.html

此映射在 Vite 开发服务器和 vite build 中均有效。每个生成的页面 都会加载常规的 index.html，然后加载其 vitexec 脚本。多个 vitexec() 声明可以安全共存，并会去重；发生页面映射冲突时会清晰地报错。

将截图作为证据来审查

根据请求的结果检查截图或录制：仅有渲染帧并不能证明行为正确。检查与应用相关的视觉缺陷，并尽可能将视觉证据与状态断言结合起来（例如，计数发生了变化、某个实体消失了，或动画已推进）。