recovery-probe

Recovery Probe

别再假设代码能正常运行。测试实际会发生什么。

Recovery Probe 帮助开发者和 AI 编码 Agent 发现普通测试可能遗漏的错误。它会刻意在 Web 和 Electron 应用中触发故障，观察 UI 如何响应，并生成证据，供你复现、修复和验证问题。

请求失败时，不应该悄无声息地把内容充实的页面变成“未找到任何项目”。Recovery Probe 帮你复现这种故障，并检查应用是否按预期恢复。

试用

你需要 Node.js 22 或更高版本。

npm install --save-dev recovery-probe playwright
npx playwright install chromium
npx recovery-probe demo

该演示会运行两个版本的小型应用。两者都能正常加载。只有修复后的版本能在遇到 503、连接中断和损坏的 JSON 响应时正常运行。

检查你自己的应用

Web 应用。 启动应用，然后运行：

npx recovery-probe init http://localhost:3000

浏览器会打开。登录，前往你关心的页面，然后点击一个只有在数据加载后才会显示的内容。Recovery Probe 会找到其背后的请求，以三种方式让请求失败，并告知你数据是否恢复。

Electron 应用。 使用 --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 启动应用，然后运行 npx recovery-probe init。

通过 IPC 加载数据的 Electron 应用。 在主进程中加载仅用于开发的轻量钩子。npx recovery-probe doctor 会打印代码以及需要加载该代码的路径。启用检查器后重启应用，然后运行 npx recovery-probe init：它会列出钩子的通道，询问哪个通道负责加载页面，并以几种方式让其失败。

每次运行都会保存 HTML 和 JSON 报告。再次运行相同命令即可重复检查，或者添加 --fresh 重新设置。如果缺少什么，npx recovery-probe doctor 会说明缺少的内容以及如何修复。

更多

目标	运行	文档
无需编写断言，即可让页面背后的读取请求失败	discover	发现
无需注入故障，即可捕获过时页面和状态卡在旧状态的行	observe	观察
查看保存或发送失败时用户会看到什么	action	操作检查
让 SDK 或主进程自身的 HTTPS 连接失败	net	网络故障
找出会把读取失败转成“无数据”的代码	suspects	可疑代码
证明某项更改已修复问题	compare、watch、verify	比较、监控、验证

在编码 Agent 中使用

recovery-probe mcp 是一个 MCP 服务。任何支持 MCP 的 Agent 都可以用它让读取请求失败，并查看页面，然后再声称代码能够处理错误。大多数 Agent 都可使用以下配置：

{
  "mcpServers": {
    "recovery-probe": { "command": "npx", "args": ["recovery-probe", "mcp"] }
  }
}

其他配置格式和工具列表请参阅 MCP。

在测试中使用

withFault 会在 Playwright 测试中让匹配的请求失败：

import { test, expect } from '@playwright/test'
import { withFault } from 'recovery-probe'

test('profile recovers after a 503', async ({ page }) => {
  const stats = await withFault(
    page,
    { match: '**/api/profile', kind: 'http-error', status: 503 },
    async () => {
      await page.goto('http://127.0.0.1:3000/profile')
      await page.getByRole('button', { name: 'Retry' }).click()
      await expect(page.getByTestId('profile-name')).toHaveText('Test User')
    },
  )
  expect(stats.applied).toBe(1)
})

如果没有匹配项，withFault 会抛出 FAULT_NOT_TRIGGERED，而不是通过测试。对于接收 fetch 函数的代码，可以使用 createFaultFetch。请参阅 API。

判定方式

• 每次注入故障的运行之前，都会在同一页面上进行一次正常运行，报告会比较两者。
• 结果分为通过、失败或无法确定。故障未触发、基线不稳定或路径无法访问时，结果为无法确定，绝不会判定为通过。
• 有些发现（例如 SILENT_EMPTY）只是线索，用来指明检查方向，并不代表代码有问题。
• 退出码：0 表示通过，1 表示检查失败，2 表示需要复核或无法确定，3 表示用法或配置错误，4 表示无法运行。

适用场景

• Chromium 中的 Web 应用，可由 Recovery Probe 启动，也可通过本地调试端口连接。
• Electron 应用，可通过渲染进程中的 HTTP 或配合 hook 使用 IPC。
• 使用 HTTPS_PROXY 的原生 HTTPS 客户端，例如主进程中的 SDK。此类客户端只能让整个连接失败。
• Android WebView，实验性支持。

它不会模拟整个设备离线、WebSocket 断开、令牌过期、休眠或网络变慢。

隐私

报告保存在你的设备上，不会发送遥测数据。不会记录请求和响应正文；发现和观察只会将屏幕文本保存为哈希值。不过，报告仍可能包含端点路径、选择器、你选作标记的文本，以及使用 --screenshots 时的屏幕内容，因此分享前请先检查。除非你主动选择使用修复工作流，否则不会调用 AI 服务。

恢复检查失败时，也可能保存 screenText：最多包含 200 个字符的新显示屏幕文本，并会出现在终端输出、报告、修复摘要和 MCP 结果中。这些引文不会经过脱敏处理，即使没有截图，也可能包含个人或敏感数据。分享这些输出或将其交给 Agent 前，请先检查。

只能测试你有权测试的应用和账户，并确保调试端口仅监听 localhost。

1.x 版本兼容性

兼容性承诺涵盖文档中说明的非实验性包导出、CLI 命令和选项、退出代码、配置字段、MCP 工具及 JSON 报告字段。移除或重命名这些接口、以不兼容方式更改其类型，或更改文档中说明的含义，都需要发布主版本。向后兼容的新增内容可以在次要版本中发布；恢复文档所述行为的修复可以在补丁版本中发布。

使用方应能容忍 JSON 中出现额外字段。终端输出的确切措辞、HTML 布局、计时测量值和启发式分析结果不属于固定契约。dist/ 下的内部文件不是公开导入接口；请使用包声明的导出。明确标记为实验性的功能（包括 Android WebView 支持和修复）可能会在次要版本中更改，相关变更会记录在变更日志中。

升级到 1.0

1.0 移除了旧命令拼写 desktop、web、ipc、--demo 和 --config。现在这些命令都会停止执行并报用法错误，说明替代命令，例如 windows、reads、check、discover、action 和 demo。用法错误的退出代码为 3，设置失败的退出代码为 4；旧拼写对应的退出代码为 2，因此请更新读取退出代码的 CI 脚本。demo 和 JSON 运行器的 check 会将 report.json 写入 --out 文件夹。升级后请重启开发应用，使其 IPC hook 与 CLI 匹配。公开的包导入接口和 hook 路径没有变化。请参阅变更日志。

文档

入门指南 · 桌面应用和浏览器 · IPC · 发现 · 观察 · 刷新 · 网络故障 · Android · 疑似问题 · 比较 · 监视 · 验证 · MCP · API · JSON 运行器 · CI · 修复 · 变更日志

贡献

请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明报告安全问题。

许可证

MIT © 2026 Bojan Kovachki