测试与调试

选择正确的测试边界#

浏览器测试验证自己的 UI，真实 Host 会话验证原生接入，安装包验证分发。Mock 返回期望值，不能证明原生服务存在，也不能证明发布包包含所需资源。

显式使用浏览器 Mock#

下面代码需要测试环境已安装 SDK，使用独立客户端。生产代码继续使用连接 Host 的客户端。

import {
  createMockBridge,
  createTroveClient,
  TroveError,
} from "@trove/plugin-sdk";

const bridge = createMockBridge({
  "host.runtime.echo": (params) => params,
  "example.failure": () => {
    throw new TroveError({ code: "example.unavailable", message: "Try again" });
  },
});
const client = createTroveClient({
  bridge,
  context: {
    curioId: "dev.example.test",
    curioVersion: "0.1.0",
    instanceId: "test-instance",
    apiVersion: 1,
    mode: "development",
  },
});

try {
  const response = await client.call("host.runtime", "echo", { value: 42 });
  console.log(response); // { value: 42 }
  const subscription = await client.subscribe(
    "example", "changed", {}, (event) => console.log(event),
  );
  bridge.emit("example", "changed", { value: 43 });
  await subscription.close();
  // In a separate test, call example.failure and assert the error UI.
} finally {
  client.disconnect();
}

处理函数接收 (params, { signal })，可用 signal 停止异步 Mock 工作。未注册的方法返回 service.not_found。bridge.emit(service, topic, data) 明确向匹配的 Mock 订阅发送事件。Mock 不校验真实服务 Contract，也不模拟 macOS。

验证原生 Backend#

trove protocol test
trove protocol test --command node -- backend/index.mjs

第一条优先读取开发 Backend 命令，否则使用生产入口与 args；第二条在临时隔离会话中运行指定命令。探针成功表示这部分传输行为通过，还需要独立验证服务实际业务约定。具体探针要求见 Backend 指南。

使用 Trove 调试控制台#

打开 My Curios，点击 Curio 右侧的虫子图标或页头调试按钮。选择 Curio，按网页 console、Backend、UI 开发进程或 stderr 筛选。搜索方法名、错误 code 或 trace ID；分享复现信息时复制筛选后的输出。

WebView 捕获 console.log/info/debug/warn/error、未捕获错误和未处理 Promise 拒绝。Backend 与 UI 开发进程使用 stdout/stderr。stderr 是输出流，不一定意味着业务错误。

暂停会冻结视图，恢复后读取新输出。清空只重置当前视图读取位置，不删除磁盘日志。切换工作空间页面时，控制台保持可用。

了解日志边界#

控制台读取每路最新 32 KiB，最多显示每路 400 行。WebView 日志单文件达到 5 MiB 后轮转，保留一个备份。高频捕获有上限，可能显示省略提示；崩溃或强制结束可能丢失最后一批日志。

通过 host.runtime.getPaths 找到当前 Curio 的日志目录，视图片段不足时查看磁盘文件。不要记录会话 token、密钥或不必要的用户文件内容。

发布前复现完整流程#

1. 启动新开发会话，执行一次真实原生调用。
2. 触发可恢复错误，确认 UI 退出加载状态。
3. 请求未完成时关闭界面，检查取消和订阅清理。
4. 停止开发，打包并安装，再次执行核心流程。
5. 有 Backend 时关闭、重开 Curio，验证配置的生命周期。

若某一步失败，先按常见问题排查缩小原因，再发布版本。