sanity-check

用途 sanity-check 用于对一个已发布的 rivetkit 版本执行快速端到端检查：在临时目录中从公共 npm registry 安装指定版本的包，启动 hello-world counter actor 服务，并通过客户端脚本验证 HTTP 动作与 WebSocket 连接及事件广播是否工作正常。

适用场景

• 用户希望验证某个已发布 rivetkit 版本可用（如 rivetkit@0.0.0-pr.4701.a818b77、rivetkit@latest、rivetkit@2.5.0）。
• 预览发布后验证构建是否可用。
• 正式发布后验证包能否正确安装和运行。
• 用户说出“sanity check”“smoke test”“verify the build”或“test this version”。

输入

• 版本或标签（必填）：显式的 pkg-pr-new 预览版本、npm dist-tag 或 semver。若用户消息中未提供，需向用户询问。
• 附加测试行为（可选）：例如“also verify workflows persist”“check that KV works”。若提供，需在运行前按下方“扩展自定义测试”菜单修改 src/index.ts 与 test.mjs。

使用方式

• /sanity-check <version>：在主机临时目录中运行。
• /sanity-check docker <version>：在 node:22 Docker 容器内运行。
• /sanity-check <version> <custom instructions>：附加额外指令，例如“also hit a KV action”“verify state persists across restart”“use pnpm”“test on node 20”。 <version> 为任意 npm 可解析的规格：显式 pkg-pr-new 预览版本（0.0.0-pr.4701.a818b77）、npm dist-tag（latest、rc、next）或 semver（2.3.0-rc.4）。

测试内容

• 从公共 npm registry 安装 rivetkit、@rivetkit/react 及平台相关的 @rivetkit/rivetkit-napi-* 原生绑定。
• 通过 registry.start() 在 6420 端口启动 hello-world counter actor 服务。
• HTTP 路径：调用 counter.increment(5)、counter.increment(3)、counter.getCount() 并断言返回值。
• WebSocket 路径：打开 .connect() 连接，订阅 newCount 事件，调用 increment(10)，断言动作响应值与广播事件值一致。
• 报告 rivetkit 与 @rivetkit/rivetkit-napi 的解析版本。

要求

• Node.js 22+（或使用 node:22 的 Docker）。
• 本地需有该仓库——仅用于复制 examples/hello-world/src/ 作为种子，不使用其 node_modules 或 workspace 链接。

步骤概要

1. 创建临时目录（mktemp -d /tmp/rivetkit-sanity-XXXXXX），复制 hello-world 的 src 与 tsconfig.json，写入含指定版本依赖的 package.json。对 pkg-pr-new 预览版本可先用裸版本字符串，失败则回退到 https://pkg.pr.new/rivet-dev/rivet/rivetkit@<short-sha> URL 形式。
2. 编写 test.mjs：启动服务、等待 /health 就绪（30 秒超时）、创建客户端、断言 HTTP 三次调用的值、建立 WebSocket 连接并断言 increment(10) 返回值与 newCount 事件值均为 10。
3. 安装并运行：默认在主机执行 npm install && node test.mjs；Docker 模式使用 docker run --rm -v "$SANITY_DIR":/app -w /app node:22 bash -c "npm install && timeout 120 node test.mjs"。
4. 读取 node_modules 中各包 package.json，输出 rivetkit、@rivetkit/react、@rivetkit/rivetkit-napi 的安装版本。
5. 报告解析版本、HTTP 路径结果、WebSocket 路径结果与事件值；失败时输出最近 2KB 服务日志。
6. 清理：主机模式下 rm -rf 临时目录；Docker 模式需等 docker run --rm 退出后再清理，以便容器创建的 node_modules 被 --rm 清除。

扩展自定义测试 在基础测试之上叠加修改，而非重写。常见需求：

• KV 往返：在 src/index.ts 添加 setKv/getKv 动作，在 test.mjs 中调用 set 后 get 并断言。
• Workflow：添加 workflow 动作，等待完成并断言最终状态。
• SQLite + migrations：添加迁移与查询动作，调用并断言行数据。
• 状态持久化：increment 后 kill 服务（SIGTERM），等待退出并重启，调用 getCount() 断言值保留。
• 多 actor 实例：使用不同 key，验证隔离性。

规则

• 始终使用全新临时目录，不在仓库内运行。
• 始终从公共 npm registry 或 pkg-pr-new 安装，不使用本地 workspace 链接或 file: 依赖。
• rivetkit 与 @rivetkit/react 固定为用户指定版本，由 npm 的 optionalDependencies 自动解析对应平台的 @rivetkit/rivetkit-napi-<platform> 二进制。
• 若裸 pkg-pr-new 版本字符串安装失败，改用 URL 形式重试。
• 若服务 30 秒内未就绪，先输出最近 2KB 服务标准错误/输出再失败——安装或运行时问题（缺少原生二进制、Node 版本不符、端口冲突）通常在此可见。
• Docker 模式须在容器退出后再删除临时目录。

限制 官方资料未提供收费、价格、平台支持范围（除 Node.js 22+ 与 Docker node:22）及性能效果等信息。