ApiCatcher
ApiCatcher
iOS向けHTTP(s)キャプチャ＆デバッグツール

ApiCatcher ユーザーマニュアル

ApiCatcherは、開発者、テストエンジニア、およびネットワークトラブルシューティング担当者のために作られたプロフェッショナルなiOSネットワークデバッグツールです。ローカルに仮想ゲートウェイを確立することで、開発中のアプリのHTTP/HTTPSおよびWebSocketトラフィックを簡単にキャプチャ、表示、分析、およびデバッグできるようになります。

このマニュアルでは、日々の開発デバッグ、Mockテスト、API自動化分析、およびパフォーマンストラブルシューティングに役立つ各機能モジュールの設定と使用方法について詳しく説明します。

目次

  1. 基本準備：証明書の設定とデバッグの承認
  2. トラフィックフィルタリング：デバッグ対象を正確に特定
  3. APIのモックと変更：Rewriteルール
  4. 高度なカスタム処理：JavaScriptスクリプト
  5. 自動テスト：Combo Replay（コンボリプレイ）
  6. バックグラウンド監視：スケジュールタスク
  7. 品質とパフォーマンスのトラブルシューティング：APIスキャン
  8. ユーティリティツール：暗号化/復号化とデスクトップ同期

1. 基本準備：証明書の設定とデバッグの承認

1.1 CA証明書のインストールと信頼（HTTPSデバッグに必須）

現代のアプリケーションでのデータ通信は、一般的にHTTPSプロトコルに基づいて暗号化されています。自社アプリの開発とデバッグを行う際、APIの平文の要求と応答データを正常に表示するには、復号化を許可するためのデバッグ証明書を設定して信頼する必要があります。

ApiCatcherには、2つの証明書設定方法があります：

  1. システムがデフォルトで生成するCA証明書を使用（ほとんどのシナリオで推奨）：以下のガイダンスに従って、ApiCatcherが自動的に生成した専用CA証明書をインストールします。
  2. 独自の証明書をインポート（エンタープライズ証明書）：企業が自己署名した証明書を使用する必要がある場合は、このセクションをスキップして、1.2 エンタープライズ証明書のインポートセクションをお読みください。

デフォルトのCA証明書を使用する手順：

  1. アプリ内で「証明書をインストール」をクリックすると、システムがブラウザにジャンプして設定プロファイルをダウンロードします。
  2. iOSの 「設定」 -> 「一般」 -> 「VPNとデバイス管理」 に移動し、ダウンロードしたApiCatcherプロファイルをインストールします。
  3. 重要な手順： 「設定」 -> 「一般」 -> 「情報」 -> 「証明書信頼設定」 に移動し、ApiCatcher CA で始まる証明書を見つけて、スイッチをオンにして完全に信頼します。

💡 よくあるトラブルシューティングガイド：

  • デバッグ時に「接続タイムアウト」またはステータスコードの異常が発生する場合：通常、手順3で証明書を「完全に信頼」していないことが原因です。
  • アプリを削除して再インストールした場合：古いデバッグ証明書はすでに無効になっています。システム設定から古いプロファイルを削除し、上記の手順をもう一度繰り返す必要があります。

1.2 エンタープライズ証明書のインポート（企業イントラネットデバッグシナリオ）

企業内部での開発テスト中、一部の社内アプリは特定の証明書信頼ポリシー（社内CAのみを信頼するなど）を設定している場合があります。

  • 用途：企業が提供する.pemまたは.p12証明書をインポートし、内部テストドメイン（例：*.corp.internal）とバインドすることで、ローカルデバッグ時の正当なTLSハンドシェイクを完了します。
  • 注意：インポートや設定の変更は、必ずキャプチャを停止した状態で行ってください。完了後に再起動すると有効になります。

1.3 カスタム証明書の使用

エンタープライズ証明書をお持ちでない個人開発者や、ApiCatcher が提供するデフォルトの証明書を使用しない場合は、エンタープライズ証明書機能を使用して独自の証明書をインポートできます。 詳細については、ドキュメントを参照してください：カスタム証明書の使用

2. トラフィックフィルタリング：デバッグ対象を正確に特定

開発中、システム基盤や他のバックグラウンドアプリからのトラフィックの干渉を排除するために、フィルタリングルールを設定し、現在デバッグ中のプロジェクトにのみ焦点を当てることをお勧めします。

  • ブロックリスト：ブロックリストに含まれるドメインは記録されません。許可リストが空の場合、デフォルトでブロックリスト以外のすべてのリクエストが記録されます。
  • 許可リスト：許可リストにルールが含まれている限り、システムは許可リストに一致するリクエストのみを記録し、他のトラフィックはデバッグチャネルに入りません。
  • 設定のヒント：*ワイルドカードをサポートしています。たとえば、*.example-api.comと入力すると、そのメインドメイン下のすべてのテスト環境サブドメインに一致します。

💡 よくあるトラブルシューティングガイド：

  • 対象アプリのリクエストが表示されない：許可リストを有効にしたが対象ドメインを記入し忘れたか、対象ドメインを誤ってブロックリストに追加していないか確認してください。
  • 構文の注意：基本的なアスタリスクのマッチング（例：*.api.com）を使用してください。複雑な正規表現を記述する必要はありません。

3. APIのモックと変更：Rewriteルール

フロントエンドとバックエンドの並行開発時、バックエンドのAPIがまだ準備できていなかったり、特定の異常なステータスコードをテストする必要があることがよくあります。Rewriteルールを使用すると、APIのMockや境界テストをエレガントに実行できます。

3.1 スコープ設定 (Scope)

Rewriteルールを追加する際、無関係なリクエストに影響を与えないように、そのルールが有効になる範囲を指定する必要があります。システムは非常に簡単な設定方法を提供しており、複雑なマッチング条件を記述する必要はありません：

  • ドメイン/ホストの選択 (Host)：すでにキャプチャされたターゲットホストのドロップダウンリストからすばやく選択するか、手動で入力できます。ワイルドカードがサポートされています（例：*.example.com）。
  • APIの選択 (Path)：Hostを選択した後、リストから特定のAPIを直接選択するか（MethodとPathが自動的に入力されます）、特定のパスを手動で入力できます（/api/v1/*のようなワイルドカードパスのマッチングをサポートします）。

💡 効率化のヒント：リストから既存のAPIを選択すると、システムは後続のMockレスポンステンプレートやHeadersを自動的に事前入力（Prefill）し、設定時間を大幅に節約します！

3.2 デバッグアクション (Rewrite Action)

  • リダイレクト (Redirect)：リクエストを別のアドレスにルーティングします（本番環境のトラフィックをLocalhostやステージング環境にリダイレクトするなど）。
  • Mockレスポンス：実際のネットワークリクエストを送信せず、事前に設定したテストデータ（JSON/XML）を直接返します。ステータスコード（404、500の異常などをシミュレート）、レスポンスヘッダー、およびレスポンスボディの設定をサポートします。
  • 破棄 (Drop)：
    • リクエストの破棄：リクエストが送信できない状態をシミュレートします（ネットワーク切断シナリオなど）。
    • レスポンスの破棄：サーバーの無応答/タイムアウトをシミュレートします。
  • 遅延 (Delay)：人為的にネットワーク遅延を注入し、弱ネットワーク環境下でのアプリのLoadingのインタラクションパフォーマンスをテストします。
  • リクエスト/レスポンスの変更 (Modify)：
    • Headerの編集：リクエストヘッダーにテストTokenを注入したり、User-Agentを変更したりするために使用します。
    • Bodyの置換：リクエストボディまたはレスポンスボディの内容を完全に置換します。
    • 正規表現で検索しBodyを置換：JSONのフィールドを細かく置換します。たとえば、正規表現を使用して "status": "pending" を "status": "success" に置換して後続のロジックをテストします。

💡 よくあるトラブルシューティングガイド：

  • ルールが有効にならない：現在のルールを上書きする、優先度の高い（最近追加された）他のルールが存在します。
  • 正規表現の置換に失敗する：JSONデータにはインデントやスペースが含まれることがよくあります。正規表現が空白文字（\s*など）を考慮していない場合、マッチングが失敗する可能性があります。組み込みの「テスト」パネルを使用して式を検証することをお勧めします。

4. 高度なカスタム処理：JavaScriptスクリプト (Script)

動的な計算が必要な複雑なMockシナリオ（タイムスタンプ署名の計算、動的データの組み立てなど）のために、スクリプトエンジンは最高レベルのプログラマブルなデバッグ機能を提供します。

4.1 コア機能パネルと補助ツール

手動コーディングに加えて、ApiCatcherにはスクリプトの作成と検証を完了するのに役立つ強力な周辺ツールが用意されています：

  • AIによる自動生成スクリプト：コードを1行も書く必要はありません。自然言語による指示を入力するだけで（例：「レスポンスボディのpriceフィールドの値を9.9に変更し、discount_tag: trueを追加して」）、内蔵のAIアシスタントが標準的なJSコードを直接生成し入力してくれます。
  • ローカルテスト環境 (Test Script)：正式に保存して有効にする前に、直接クリックしてテストできます。履歴から実際にキャプチャされたリクエストを選択してスクリプトに渡すことで、システムが変更前後のデータ比較結果とエラーログを直感的に表示し、構文が正しいことを確認できます。
  • リモートスクリプトのホスティング (Remote Script)：パブリックなhttp://またはhttps://のスクリプトURLを直接入力することをサポートします。ApiCatcherはローカルでクラウドスクリプトをロードして実行するため、チーム内で共通のMockルールを統一的に展開・維持するのに非常に役立ちます！

4.2 スクリプトのコア関数

スクリプトの作成方法については、ドキュメントをお読みください：APICatcher スクリプト機能使用ガイド

事前に定義されたライフサイクル関数を実装するだけです：

// 送信リクエストの処理
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // 戻り値のアクション: passthrough(パススルー), modify(変更), mock(モック), drop(破棄)
    return { action: 'modify', request: request };
}

// 受信レスポンスの処理
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // 内蔵の安全な解析関数
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

4.2 組み込みの高度なAPI

  • localStore：リクエスト間の状態維持に使用されます。たとえば、ログインAPIで認証状態を保存し、後続のAPIで自動的に注入します。
    • localStore.write('session_id', 'abc')
    • var t = localStore.read('session_id')
  • httpClient：スクリプトの実行中に追加のネットワークリクエストを送信することをサポートします（外部状態の同期や動的設定の取得に使用）。
    • var res = httpClient.get('https://api.ipify.org')

💡 よくあるトラブルシューティングガイド：

  • 構文またはランタイムエラー：組み込みの「テストスクリプト」ボタンを使用してロジックを検証します。console.log("...") を使用して、「ログ (Logs)」ページで出力を確認できます。
  • ライフサイクルの競合：あるリクエストがすでに優先度の高い「Rewriteルール」によってMockまたはDropとして実行されている場合、そのリクエストのそれ以降のスクリプト実行フローには入りません。

5. 自動テスト：Combo Replay（コンボリプレイ）

単一のAPIテストでは、完全なビジネスフローの検証（例：ログイン -> 認証の取得 -> 情報の照会 -> フォームの送信）を満たすことはできません。Combo Replayは、複数の関連APIに対する視覚的なオーケストレーションと自動化された回帰テストをサポートします。

5.1 設定手順

  1. ノードの追加：履歴からビジネスフローの各リクエストを順番にキャンバスに追加します。
  2. 依存関係の確立：ノード間に有向エッジを確立し、リクエストが依存順序に厳密に従って順番に実行されるようにします。
  3. パラメータマッピング（依存性注入）：データフローを設定します。上流のAPIレスポンスから特定のフィールドを、下流のリクエストに動的に注入します。

5.2 パラメータマッピング設定の詳細

  • 抽出元：上流の レスポンスボディ(responseBody) または レスポンスヘッダー(responseHeader) から抽出できます。
    • 抽出パス：JSONレスポンスボディの場合、直接JSON Path（例：data.session.token）を使用します。
  • 注入先：下流の リクエストヘッダー(requestHeader)、URLパラメータ(queryParam)、または リクエストボディ(requestBody) に注入できます。
  • オプションのプレフィックス (Optional Prefix)：特定の標準の自動補完に使用されます。たとえば、抽出された値が abc だが、標準ではヘッダーに Bearer abc を含める必要がある場合、ここに Bearer と入力するだけで自動的に連結されます。

💡 よくあるトラブルシューティングガイド：

  • パラメータが正常に抽出されない：手動でパスを記述することによる形式の階層エラーを避けるために、キャンバスのノードに組み込まれている「サンプルレスポンスボディ」のツリー構造を使用してクリック選択してください。

6. バックグラウンド実行：スケジュールタスク (Scheduled Tasks)

VPNプロセスに基づくバックグラウンド常駐機能を利用して、「スケジュールタスク」を使用して特定のリクエストやCombo Replayルールを定期的に実行できます。 典型的なアプリケーションシナリオ：Eコマースの「フラッシュセール（秒殺）」イベントを開発またはテストする場合、時間が極めて短いため、手動でのクリックテストでは瞬間を逃すことがよくあります。このとき、スケジュールタスクを設定して、フラッシュセールが始まる前にAPIに高頻度で注文を自動リクエストさせることで、フラッシュセールの同時並行性の安定性とビジネスロジックを十分に検証できます。

6.1 スケジュール設定 (Schedule Type)

  • Cron式：標準の5桁のCron構文（例：*/5 * * * * は5分ごとに実行することを意味します）を使用します。内蔵AIを使用して生成することもできます。
  • カスタム設定：開始時間、間隔、および最大実行回数の細かい設定をサポートします。

6.2 自動終了条件 (Auto Terminate)

異常な状況での無意味な再試行を避けるか、目標に達した後に自動的に終了するように終了条件を設定します：

  • JSONフィールドの一致：たとえば、「フラッシュセールテスト」シナリオでは、戻り値の code フィールドを監視します。code が 200（購入成功）に等しい場合、または 400（在庫がなくイベントが終了したことを意味する）に等しい場合、終了がトリガーされます。
  • 正規表現の照合：レスポンスボディに対してフルテキストマッチングを実行します。"msg": "購入成功" や "error": "イベントは終了しました" などの文字特徴に一致する限り、タスクは自動的に完全に停止します。

💡 よくあるトラブルシューティングガイド：

  • タスクが実行できない：iOSシステムには厳格なバックグラウンド管理があります。メモリが不足している場合、VPNプロセスがシステムによって回収され、スケジュールタスクも一緒に一時停止する可能性があります。
  • 履歴レコードが表示されない：スケジュールタスクは、基盤となるエンジンによって直接開始される監視リクエストであり、メインアプリの通常の「履歴」には記録されません。成功率やp95などのレポートは、タスク専用の「実行履歴」パネルで確認する必要があります。
  • ルールの更新が反映されない：スケジュールタスクの作成時に、ルールのスナップショットがバインドされます。元の「Combo Replay」ルールが変更された場合、スケジュールタスクを再作成する必要があります。

7. 品質とパフォーマンスのトラブルシューティング：APIスキャン (API Scan)

ローカルでキャプチャされたトラフィックレコードに基づいて、非侵入型のAPI品質、セキュリティコンプライアンス、およびパフォーマンスのヘルスチェックを提供します。すべての分析は、デバイスのローカルメモリ内で完全に完了します。

7.1 内蔵スキャンエンジン

  • 機密情報の自己チェック：電話番号、IDカード、電子メール、およびクラウドサービス認証情報（AWS Key、OpenAI API Keyなど）の平文送信の検出をサポートし、フロントエンドおよびAPI設計者がデータの匿名化の漏れを早期に発見するのに役立ちます。
  • 異常なスタックリーク：レスポンスボディに誤って返されたJava、Python、またはSQLの呼び出しスタックを識別します。
  • 高頻度呼び出し分析：設定されたしきい値（平均リクエスト間隔が特定のミリ秒未満など）に基づいて、無限ループや不適切なロジックによって引き起こされた冗長なAPI呼び出しが存在するかどうかをトラブルシューティングします。
  • 所要時間評価：各APIのp95およびp99の遅延を集計および計算し、バックエンドのパフォーマンスのボトルネックを特定するのに役立ちます。

7.2 カスタム品質検出 (Custom Scan)

ビジネスに合わせてカスタマイズされたコンプライアンスチェックを実行するためのJSスクリプトを作成できます。

  • 戻り値の規約：関数がリクエストが要件を満たしていると判断した場合は null を返します。コンプライアンス違反が検出された場合（レスポンスボディが大きすぎる、セキュリティヘッダーが欠落しているなど）は、簡潔な説明（200文字以下）を返すと、システムが自動的にスキャンレポートに含めます。

💡 よくあるトラブルシューティングガイド：

  • 結果が分析されない：「スキャン範囲 (Host/Session)」に、純粋な静的リソースではなく、有効なJSON/APIトラフィックレコードが実際に含まれているかどうかを確認してください。エクスペリエンスを保証するために、1回のスキャンのレコード数には上限があります。

8. ユーティリティツール：暗号化/復号化とデスクトップ同期

8.1 開発者ツールボックス (Decrypt/Encrypt)

メッセージの暗号化送信に対処するために、一般的なコーデックツールが組み込まれています：

  • AES復号化：カスタムキー（Key）と初期ベクトル（IV）を入力して、Payloadをすばやく復号化してテストすることをサポートします。
  • Base64 / URL Encode / MD5 / SHA256。
  • カスタム処理：選択したテキストのデータ変換を実行するために、1回だけ実行されるJSスニペットの書き込みをサポートします。

8.2 デスクトップへのリアルタイム同期 (Realtime Sync)

用途：PC側のより広い視野でデータをデバッグする必要がある場合は、WebSocketプロトコルを使用して、デバイスがキャプチャしたデータパケットをApiCatcher Desktopアプリケーションにシームレスにプッシュできます。 設定：

  • ローカルネットワーク内で割り当てられたWebSocketアドレスを入力します。
  • ハンドシェイクの成功を確認するために、必ず事前に「接続テスト」に合格してください。
  • トラブルシューティング：モバイル端末に「ローカルネットワーク」権限が付与されていること、PCファイアウォールで対応するポートが許可されていること、および両方が同じLANサブネット内にあることを確認してください。