recovery-probe

Recovery Probe

コードが動くと思い込むのはやめましょう。実際に何が起きるかをテストしてください。

Recovery Probe は、通常のテストでは見逃す可能性のあるバグを、開発者や AI コーディングエージェントが見つけるのに役立ちます。Web アプリや Electron アプリで意図的に障害を発生させ、UI の応答を観察し、問題の再現、修正、検証に使える証拠を作成します。

リクエストに失敗したとき、画面に表示されていたデータが何もないかのように「アイテムが見つかりません」に変わるべきではありません。Recovery Probe を使えば、その失敗を再現し、アプリケーションが期待どおりに復旧するかを確認できます。

試してみる

Node.js 22 以降が必要です。

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

デモでは、小さなアプリの2つのバージョンを実行します。どちらも正常に読み込まれます。503、接続切断、壊れた JSON レスポンスに耐えられるのは、修正版だけです。

自分のアプリをチェックする

Web アプリ。 アプリを起動してから、次を実行します。

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

ブラウザーが開きます。サインインして、確認したい画面に移動し、データの読み込み後にのみ表示される項目をクリックします。Recovery Probe はその背後にあるリクエストを見つけ、3種類の方法で失敗させ、データが復旧したかを知らせます。

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	Discovery
障害を発生させずに古い画面や、古い状態のままの行を検出する	observe	Observe
保存や送信が失敗したとき、ユーザーに何が表示されるか確認する	action	Action check
SDK やメインプロセス独自の HTTPS 接続を失敗させる	net	Network faults
読み取り処理の失敗を「データなし」に変えてしまうコードを見つける	suspects	Suspects
変更によって問題が修正されたことを証明する	compare、watch、verify	Compare、Watch、Verify

コーディングエージェントから使う

recovery-probe mcp は MCP サーバーです。MCP に対応したエージェントなら、コードがエラーを処理すると主張する前に、読み取り処理を失敗させて画面を確認できます。多くのエージェントでは、次の設定を使用できます。

{
  "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 は実行不能。

動作環境

• Recovery Probe によって起動するか、ローカルのデバッグポート経由で接続する Chromium のウェブアプリ。
• HTTP 経由でレンダラー内、またはフックを使って IPC 経由で動作する Electron アプリ。
• HTTPS_PROXY を使用するネイティブ HTTPS クライアント（メインプロセス内の SDK など）。この場合、失敗させられるのは接続全体のみです。
• Android WebView（実験的）。

デバイス全体のオフライン化、WebSocket の切断、トークンの有効期限切れ、スリープ、低速ネットワークはシミュレートしません。

プライバシー

レポートはお使いのマシン内に保存され、テレメトリーはありません。リクエストとレスポンスの本文は記録されず、検出と観察では画面上のテキストをハッシュとしてのみ保持します。ただし、レポートにはエンドポイントのパス、セレクター、マーカーとして選んだテキスト、また --screenshots を指定した場合は画面の内容が含まれることがあります。そのため、共有前に確認してください。オプトインの修復ワークフローを除き、AI サービスへの呼び出しはありません。

復旧チェックに失敗した場合、screenText が保存されることもあります。これは新たに画面に表示されたテキストのうち最大 200 文字で、ターミナル出力、レポート、修正概要、MCP の結果に含まれます。これらの引用は伏せ字にならず、スクリーンショットがなくても個人情報や機密情報が含まれる可能性があります。共有したり、エージェントに渡したりする前に、これらの出力を確認してください。

許可されているテストアプリとアカウントのみを使用し、デバッグポートは 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 は、--out フォルダーに report.json を書き込みます。CLI に対応する IPC フックを使用するため、アップグレード後に開発アプリを再起動してください。公開パッケージのインポートとフックのパスに変更はありません。変更履歴を参照してください。

ドキュメント

ガイド付きスタート · デスクトップとブラウザー · IPC · 検出 · 観察 · 更新 · ネットワーク障害 · Android · 疑わしい箇所 · 比較 · 監視 · 検証 · MCP · API · JSON ランナー · CI · 修復 · 変更履歴

コントリビューション

CONTRIBUTING.mdを参照してください。セキュリティ上の問題は、SECURITY.mdの説明に従って報告してください。

ライセンス

MIT © 2026 Bojan Kovachki